Skip to Content
Admin APIClaims

Admin Claims API

Administrative endpoints for managing insurance claims and billing.

List Claims

Get a list of insurance claims.

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

Query Parameters

ParameterTypeRequiredDescription
pageintegerNoPage number for pagination
page_sizeintegerNoNumber of items per page
sort_bystringNoField to sort by
sort_dirstringNoSort direction (“ASC” or “DESC”)
statusstringNoFilter by claim status
patient_idintegerNoFilter by patient ID
provider_idintegerNoFilter by provider ID

Example Request

GET /v1/admin/clinic/claims?status=submitted&page=1 HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here

Filter Claims

Filter claims with advanced criteria.

Endpoint: POST /v1/admin/clinic/claims/filter_claims
Authentication: Required (Admin role)

Request Body Parameters

ParameterTypeRequiredDescription
searchstringNoSearch term
sort_bystringNoField to sort by
sort_dirstringNoSort direction
filtersobjectNoFilter criteria with available parameters: date (object with start_date/end_date), status (string), appointment_type (string), insurance_plan_id (integer), appointment_id (integer), patient_name (string), provider_name (string)
page_sizeintegerNoNumber of items per page

Example Request

POST /v1/admin/clinic/claims/filter_claims HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here
 
{
  "search": "therapy",
  "filters": {
    "status": "pending",
    "date_range": {
      "start": "2023-10-01",
      "end": "2023-10-31"
    },
    "amount_range": {
      "min": 100,
      "max": 500
    }
  },
  "page_size": 50
}

Create Claim

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

Request Body Parameters

ParameterTypeRequiredDescription
claimobjectYesClaim data object
claim.patient_idintegerYesPatient ID
claim.provider_idintegerYesProvider ID
claim.appointment_idintegerYesAppointment ID
claim.cpt_codestringYesCPT procedure code
claim.diagnosis_codesarrayYesArray of ICD-10 diagnosis codes
claim.service_datestringYesDate of service (YYYY-MM-DD)
claim.amountnumberYesClaim amount

Example Request

POST /v1/admin/clinic/claims HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here
 
{
  "claim": {
    "patient_id": 1049,
    "provider_id": 456,
    "appointment_id": 789,
    "cpt_code": "90834",
    "diagnosis_codes": ["F41.1", "F32.9"],
    "service_date": "2023-10-27",
    "amount": 150.00
  }
}

Get Claim Details

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

Path Parameters

ParameterTypeRequiredDescription
idintegerYesClaim ID

Update Claim

Endpoint: PUT /v1/admin/clinic/claims/{id}
Authentication: Required (Admin role)

Request Body Parameters

Same as Create Claim endpoint.

Delete Claim

Endpoint: DELETE /v1/admin/clinic/claims/{id}
Authentication: Required (Admin role)

Path Parameters

ParameterTypeRequiredDescription
idintegerYesClaim ID

Generate EDI

Generate Electronic Data Interchange (EDI) files for claims submission.

Endpoint: POST /v1/admin/clinic/claims/generate_edi
Authentication: Required (Admin role)

Request Body Parameters

ParameterTypeRequiredDescription
claim_idsarrayYesArray of claim IDs to include
formatstringNoEDI format (default: “837P”)
batch_namestringNoName for the batch

Example Request

POST /v1/admin/clinic/claims/generate_edi HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here
 
{
  "claim_ids": [123, 124, 125],
  "format": "837P",
  "batch_name": "October_2023_Batch_1"
}

Claim Documents

List Claim Documents

Endpoint: GET /v1/admin/clinic/claims/{claim_id}/documents
Authentication: Required (Admin role)

Create Claim Document

Endpoint: POST /v1/admin/clinic/claims/{claim_id}/documents
Authentication: Required (Admin role)

Get Claim Document

Endpoint: GET /v1/admin/clinic/claims/{claim_id}/documents/{id}
Authentication: Required (Admin role)

Update Claim Document

Endpoint: PUT /v1/admin/clinic/claims/{claim_id}/documents/{id}
Authentication: Required (Admin role)

Delete Claim Document

Endpoint: DELETE /v1/admin/clinic/claims/{claim_id}/documents/{id}
Authentication: Required (Admin role)

Claims Filters

Get available filter options for claims.

Endpoint: GET /v1/admin/clinic/claims/filters
Authentication: Required (Admin role)

Response Format

Claim Response

{
  "id": 123,
  "patient_id": 1049,
  "provider_id": 456,
  "appointment_id": 789,
  "claim_number": "CLM-2023-001234",
  "cpt_code": "90834",
  "diagnosis_codes": ["F41.1", "F32.9"],
  "service_date": "2023-10-27",
  "amount": 150.00,
  "status": "submitted",
  "submission_date": "2023-10-28T10:00:00.000Z",
  "payment_amount": null,
  "payment_date": null,
  "denial_reason": null,
  "created_at": "2023-10-27T16:00:00.000Z",
  "updated_at": "2023-10-28T10:00:00.000Z"
}

EDI Generation Response

{
  "batch_id": "BATCH-2023-001",
  "file_url": "https://storage.example.com/edi/batch-2023-001.txt",
  "claim_count": 3,
  "total_amount": 450.00,
  "generated_at": "2023-10-28T15:30:00.000Z"
}

Claim Status Values

  • draft - Claim is being prepared
  • ready - Claim is ready for submission
  • submitted - Claim has been submitted to insurance
  • pending - Claim is pending review by insurance
  • approved - Claim has been approved
  • paid - Claim has been paid
  • denied - Claim has been denied
  • rejected - Claim was rejected due to errors

Common CPT Codes

  • 90834 - Psychotherapy, 45 minutes
  • 90837 - Psychotherapy, 60 minutes
  • 90791 - Psychiatric diagnostic evaluation
  • 90792 - Psychiatric diagnostic evaluation with medical services
  • 90847 - Family psychotherapy with patient present
  • 90853 - Group psychotherapy

Error Responses

403 Forbidden

{
  "errors": "Admin access required"
}

422 Unprocessable Entity

{
  "errors": {
    "cpt_code": ["can't be blank", "is invalid"],
    "diagnosis_codes": ["can't be blank"],
    "amount": ["must be greater than 0"]
  }
}

404 Not Found

{
  "errors": "Claim not found"
}

Notes

  • All admin claims endpoints require administrative privileges
  • Claims must include valid CPT codes and ICD-10 diagnosis codes
  • EDI generation creates files in standard healthcare formats
  • Claim status tracking helps monitor the billing process
  • Documents can be attached to claims for supporting evidence
  • Payment tracking helps with revenue cycle management
  • Denial reasons help identify patterns and improve claim success rates
UsersOverview