ECM Authorizations API

Administrative endpoints for importing and managing ECM authorization files. Authorization files contain approval records for ECM services including Form I, E, C, D, and W submissions.

Overview

Authorization files are Excel files (XLSX, XLS, or XLSM) containing ECM authorization records. When imported, the system creates or updates authorization records and associates them with patients via their member_id. The system also automatically updates patient member record status based on authorization status.

Import Authorization File

Import an ECM authorization file to create or update authorization records.

Endpoint: POST /v1/admin/clinic/ecm/authorizations
Authentication: Required (Admin role)

Request Body Parameters

Parameter	Type	Required	Description
`authorization`	object	Yes	Authorization file data object
`authorization.file`	string	Conditional	Base64-encoded file content with data URI prefix
`authorization.url`	string	Conditional	URL to fetch the file from
`authorization.path`	string	Conditional	Server-side file path
`authorization.file_type`	string	No	File type: `xlsx`, `xls`, or `xlsm` (auto-detected if not provided)

Note: You must provide at least one of: file, url, or path.

Data URI Prefixes

File Type	Data URI Prefix
XLSX	`data:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;base64,`
XLS	`data:application/vnd.ms-excel;base64,`
XLSM	`data:application/vnd.ms-excel.sheet.macroEnabled.12;base64,`

Example Request


POST /v1/admin/clinic/ecm/authorizations HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here
 
{
  "authorization": {
    "file": "data:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;base64,UEsDBBQAAAAI...",
    "file_type": "xlsx"
  }
}

Success Response


{
  "message": "Authorization data imported successfully",
  "imported_count": 10,
  "updated_count": 5,
  "authorization_file_id": 2
}

Error Response


{
  "errors": [
    "Invalid Excel format: Unable to read file",
    "Validation failed: Auth No can't be blank"
  ]
}

Import Behavior

The authorization import process follows these rules:

Authorization Matching: Authorizations are matched by auth_no. If an authorization with the same auth_no exists, it is updated.
New Authorizations: If no matching authorization is found, a new record is created.
Patient Association: Authorizations are associated with patients via member_id.
Eligibility Linking: Authorizations are linked to ecm_eligibility_information records.
Status Updates: The system automatically updates ecm_member_record status based on authorization status:
- “Cancel” -> terminated_member
- “Pending” -> pending_member
- “Approved” -> new_member or continuing_member
Status History: Creates ecm_status_history entries when status changes.
File Association: All imported authorization records are associated with the authorization file.

Authorization Field Mapping

Excel Field	Database Field	Description
`AUTH_NO`	`auth_no`	Unique authorization number
`AUTH_TYPE`	`auth_type`	Authorization type code (e.g., “ES”)
`AUTH_DESCRIPTION`	`auth_description`	Authorization description
`MEMBER_ID`	`member_id`	Patient member ID (CIN)
`MEMBER_NAME`	`member_name`	Patient name
`AUTHORIZATION_TYPE`	`authorization_type`	Form type (Form I, E, C, D, W)
`STATUS`	`status`	Authorization status
`REQUESTING_PROVIDER`	`requesting_provider`	Provider who requested authorization
`SERVICING_PROVIDER`	`servicing_provider`	Provider delivering services
`RECEIVED_DATE`	`received_date`	Date authorization was received
`DECISION_DATE`	`decision_date`	Date decision was made
`START_DATE`	`start_date`	Authorization start date
`EXPIRATION_DATE`	`expiration_date`	Authorization expiration date
`CONTACT_NAME`	`contact_name`	Contact person name
`REMARKS`	`remarks`	Additional remarks

List Authorization Files

Retrieve a paginated list of all authorization files that have been uploaded and processed.

Endpoint: GET /v1/admin/clinic/ecm/authorizations
Authentication: Required (Admin role)

Query Parameters

Parameter	Type	Required	Description
`per_page`	integer	No	Number of items per page (default: 25)
`page`	integer	No	Page number (default: 1)

Example Request


GET /v1/admin/clinic/ecm/authorizations?per_page=10 HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here

Example Response


{
  "authorization_files": [
    {
      "id": 1,
      "filename": "authorization_20241124_130530.xlsx",
      "file_type": "xlsx",
      "source_type": "base64",
      "records_imported": 10,
      "records_updated": 5,
      "import_errors": null,
      "status": "completed",
      "created_at": "2024-11-24T13:05:30.000Z",
      "updated_at": "2024-11-24T13:05:35.000Z",
      "file_url": "https://s3.amazonaws.com/bucket/path/to/file.xlsx?X-Amz-Algorithm=..."
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 2,
    "total_count": 15,
    "per_page": 10
  }
}

Response Fields

Field	Type	Description
`id`	integer	Unique identifier for the authorization file
`filename`	string	Generated filename for the uploaded file
`file_type`	string	Type of file: `xlsx`, `xls`, or `xlsm`
`source_type`	string	How the file was provided: `base64`, `url`, or `path`
`records_imported`	integer	Number of new authorization records created
`records_updated`	integer	Number of existing authorization records updated
`import_errors`	string	Error messages if import failed (null if successful)
`status`	string	Import status: `pending`, `processing`, `completed`, `failed`
`created_at`	string	Timestamp when the file was uploaded
`updated_at`	string	Timestamp when the file was last updated
`file_url`	string	Presigned S3 URL to download the file (expires in 30 minutes)

Get Authorization File Details

Retrieve details of a specific authorization file including all authorization records that were imported from it.

Endpoint: GET /v1/admin/clinic/ecm/authorizations/{id}
Authentication: Required (Admin role)

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	Authorization file ID

Example Request


GET /v1/admin/clinic/ecm/authorizations/1 HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here

Example Response


{
  "authorization_file": {
    "id": 1,
    "filename": "authorization_20241124_130530.xlsx",
    "file_type": "xlsx",
    "source_type": "base64",
    "records_imported": 10,
    "records_updated": 5,
    "import_errors": null,
    "status": "completed",
    "created_at": "2024-11-24T13:05:30.000Z",
    "updated_at": "2024-11-24T13:05:35.000Z",
    "file_url": "https://s3.amazonaws.com/bucket/path/to/file.xlsx?X-Amz-Algorithm=...",
    "authorizations": [
      {
        "id": 123,
        "auth_no": "AUTH0000000001",
        "auth_type": "ES",
        "auth_description": "ECM Service",
        "member_id": "MEM0000000001",
        "member_name": "John Doe",
        "authorization_type": "Form I",
        "status": "Approved",
        "requesting_provider": "Dr. Smith",
        "servicing_provider": "Esteem Health PSC",
        "received_date": "2024-11-01",
        "decision_date": "2024-11-15",
        "start_date": "2024-11-15",
        "expiration_date": "2025-11-15",
        "contact_name": "Jane Contact",
        "remarks": "Initial authorization approved",
        "ecm_eligibility_information_id": 456,
        "patient_id": 789,
        "patient_name": "John Doe",
        "created_at": "2024-11-24T13:05:32.000Z",
        "updated_at": "2024-11-24T13:05:32.000Z"
      }
    ]
  }
}

Authorization Types (Forms)

ECM authorizations are categorized by form type:

Form	Description
Form I	Initial enrollment authorization
Form E	Extension authorization
Form C	Comprehensive assessment
Form D	Disenrollment
Form W	Withdrawal

Authorization Status Values

Status	Description	Member Record Status
`Approved`	Authorization approved	`new_member` or `continuing_member`
`Pending`	Authorization pending review	`pending_member`
`Cancel`	Authorization cancelled	`terminated_member`
`Denied`	Authorization denied	No change

Python Example


import base64
import requests
 
# Read and encode file
with open('authorizations.xlsx', 'rb') as f:
    file_content = base64.b64encode(f.read()).decode('utf-8')
 
# Prepare request
url = 'https://your-api-domain.com/v1/admin/clinic/ecm/authorizations'
headers = {
    'Content-Type': 'application/json',
    'X-User-Token': 'YOUR_TOKEN'
}
data = {
    'authorization': {
        'file': f'data:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;base64,{file_content}',
        'file_type': 'xlsx'
    }
}
 
# Send request
response = requests.post(url, json=data, headers=headers)
print(response.json())

cURL Example


# Encode file to base64
BASE64_FILE=$(base64 -i authorizations.xlsx | tr -d '\n')
 
# Send request
curl -X POST "https://your-api-domain.com/v1/admin/clinic/ecm/authorizations" \
  -H "Content-Type: application/json" \
  -H "X-User-Token: YOUR_TOKEN" \
  -d "{
    \"authorization\": {
      \"file\": \"data:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;base64,${BASE64_FILE}\",
      \"file_type\": \"xlsx\"
    }
  }"

Error Responses

403 Forbidden


{
  "errors": ["Admin access required"]
}

404 Not Found


{
  "errors": ["Authorization file not found"]
}

422 Unprocessable Entity


{
  "errors": [
    "Invalid Excel format: Unable to read file",
    "Validation failed: Auth No can't be blank"
  ]
}

Best Practices

File Format: Use XLSX format for best compatibility
Required Fields: Ensure auth_no and member_id are present in all records
Date Format: Use consistent date formats (YYYY-MM-DD recommended)
Status Values: Use exact status values (Approved, Pending, Cancel, Denied)
Member ID Matching: Ensure member_id values match those in the MIF import
Error Handling: Check import_errors field after import for any issues
URL Expiration: Download files promptly as presigned URLs expire after 30 minutes