Create Authorization

Create a prior authorization record linked to a patient case.

Endpoint

POST /apis/soap-enrichment/v1/authorization

Request Body

Parameter	Type	Required	Description
spry_case_id	string	Yes	The spry_case_id of the case this authorization belongs to
authorization_reference_number	string	Yes	Reference number issued by the payer for this authorization
case_title	string	No	Title of the associated case
plan_start_date	string (datetime)	No	Insurance plan start date (YYYY-MM-DDTHH:mm:ss)
plan_end_date	string (datetime)	No	Insurance plan end date (YYYY-MM-DDTHH:mm:ss)
effective_start_date	string (datetime)	No	Authorization effective start date
effective_end_date	string (datetime)	No	Authorization effective end date
insurance_payer	object	No	Payer details (see Insurance Payer Object)
authorized_visit_count	integer	No	Total number of visits authorized
current_visit_count	integer	No	Number of visits consumed in the current period
previous_consumed_visit_count	integer	No	Visits consumed in previous authorization periods
phone_number	string	No	Payer contact phone number
fax_number	string	No	Payer contact fax number
comments	string	No	Free-text notes about the authorization
authorization_status	string	No	ACTIVE, INACTIVE, or EXPIRED (default ACTIVE)
icd_codes	array	No	ICD-10 codes covered by this authorization (see ICD Code Object)
cpt_code_authorization_details	array	No	Per-CPT-code authorization limits (see CPT Code Authorization Object)
patient_id	integer	No	Patient ID
organisation_id	integer	No	Organization ID
clinic_id	integer	No	Clinic ID

Insurance Payer Object

Parameter	Type	Required	Description
payer_reg_id	integer	No	Payer registration ID in Spry
name	string	No	Payer name
payer_id	string	No	Payer EDI identifier
payer_type	string	No	Payer type (e.g., COMMERCIAL, MEDICARE, MEDICAID)
payer_state	string	No	State code for the payer

ICD Code Object

Parameter	Type	Required	Description
id	integer	Yes	ICD code ID from Spry; use Search ICD Codes to find valid IDs
code	string	Yes	ICD-10 code (e.g., M25.50)
description	string	No	Diagnosis description
revision	string	Yes	Always "ICD10"

CPT Code Authorization Object

Parameter	Type	Required	Description
cpt_code_id	string	No	CPT code identifier
cpt_code_name	string	No	CPT code name/description
authorized_cpt_units_count	integer	No	Total units authorized for this CPT code
cpt_units_authorization_start_date	string (datetime)	No	Start of authorized period for this CPT code
cpt_units_authorization_end_date	string (datetime)	No	End of authorized period for this CPT code
cpt_code_authorization_status	string	No	Authorization status for this CPT code
cpt_code_authorization_remark	string	No	Notes or remarks for this CPT code
cpt_code_units_requested	integer	No	Units requested from the payer

Request

curl --location '{base_url}/apis/soap-enrichment/v1/authorization' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "spry_case_id": "SPRY_CASE_69cd0c97e7562d613ea89bc7",
    "authorization_reference_number": "AUTH-2026-001",
    "case_title": "Stable Burst Fracture",
    "plan_start_date": "2026-04-01T00:00:00",
    "plan_end_date": "2026-07-01T00:00:00",
    "effective_start_date": "2026-04-01T00:00:00",
    "effective_end_date": "2026-07-01T00:00:00",
    "insurance_payer": {
      "payer_reg_id": 2207,
      "name": "PEHP - Utah Public Employee Health Plan",
      "payer_id": "SX106",
      "payer_type": "COMMERCIAL"
    },
    "authorized_visit_count": 20,
    "current_visit_count": 0,
    "previous_consumed_visit_count": 0,
    "phone_number": "8015551234",
    "fax_number": "8015555678",
    "comments": "Prior auth approved for MSK therapy",
    "authorization_status": "ACTIVE",
    "patient_id": 1172416,
    "organisation_id": 638,
    "clinic_id": 101,
    "icd_codes": [
      {
        "id": 9676,
        "code": "M72.1",
        "description": "Knuckle pads",
        "revision": "ICD10"
      }
    ],
    "cpt_code_authorization_details": []
  }'

Response

Success Response

Code: 200 OK

{
  "code": 2000,
  "data": {
    "authorization_id": "auth_69cd0c97abc123",
    "authorization_reference_number": "AUTH-2026-001",
    "spry_case_id": "SPRY_CASE_69cd0c97e7562d613ea89bc7",
    "case_title": "Stable Burst Fracture",
    "plan_start_date": "2026-04-01T00:00:00",
    "plan_end_date": "2026-07-01T00:00:00",
    "effective_start_date": "2026-04-01T00:00:00",
    "effective_end_date": "2026-07-01T00:00:00",
    "insurance_payer": {
      "payer_reg_id": 2207,
      "name": "PEHP - Utah Public Employee Health Plan",
      "payer_id": "SX106",
      "payer_type": "COMMERCIAL"
    },
    "authorized_visit_count": 20,
    "current_visit_count": 0,
    "previous_consumed_visit_count": 0,
    "final_consumed_visit_count": 0,
    "phone_number": "8015551234",
    "fax_number": "8015555678",
    "comments": "Prior auth approved for MSK therapy",
    "authorization_status": "ACTIVE",
    "patient_id": 1172416,
    "patient_name": "John Doe",
    "organisation_id": 638,
    "clinic_id": 101,
    "icd_codes": [
      {
        "id": 9676,
        "code": "M72.1",
        "description": "Knuckle pads",
        "revision": "ICD10"
      }
    ],
    "cpt_code_authorization_details": [],
    "created_at": "2026-04-01T12:00:00",
    "updated_at": "2026-04-01T12:00:00",
    "created_date": "2026-04-01T12:00:00Z"
  },
  "message": "Success"
}

Response Fields

Field	Type	Description
authorization_id	string	Unique identifier for the authorization record
authorization_reference_number	string	Payer-issued authorization reference number
spry_case_id	string	Associated Spry case ID
case_title	string	Title of the associated case
plan_start_date	string	Insurance plan start date
plan_end_date	string	Insurance plan end date
effective_start_date	string	Authorization effective start date
effective_end_date	string	Authorization effective end date
insurance_payer	object	Payer details
authorized_visit_count	integer	Total visits authorized
current_visit_count	integer	Visits consumed in current period
previous_consumed_visit_count	integer	Visits consumed in prior periods
final_consumed_visit_count	integer	Computed total visits consumed
phone_number	string	Payer contact phone
fax_number	string	Payer contact fax
comments	string	Free-text notes
authorization_status	string	ACTIVE, INACTIVE, or EXPIRED
patient_id	integer	Patient ID
patient_name	string	Patient full name
organisation_id	integer	Organization ID
clinic_id	integer	Clinic ID
icd_codes	array	ICD-10 codes covered by this authorization
cpt_code_authorization_details	array	Per-CPT-code authorization details
created_at	string	Creation timestamp
updated_at	string	Last update timestamp
created_date	string	Creation timestamp (ISO 8601 with timezone)

Error Response

Code: 400 Bad Request

{
  "code": 4000,
  "message": "Error description",
  "data": null
}

Notes

• authorization_status values: ACTIVE (valid, in-use), INACTIVE (disabled), EXPIRED (past end date).
• authorized_visit_count tracks the total visits the payer approved; current_visit_count is incremented as appointments are completed.
• cpt_code_authorization_details allows per-procedure-code visit limits within a single authorization.