Create Authorization

Creates an authorization against one of the case's coverages. The coverage must be the case's primary or secondary coverage.

Endpoint

POST /v2/cases/{spry_case_id}/coverages/{coverage_id}/authorizations

Path Parameters

Parameter	Type	Required	Description
spry_case_id	string	Yes	The case's business key.
coverage_id	string	Yes	One of the patient's coverages, from GET /v2/patients/{patient_id}/coverages.

Request Body

Parameter	Type	Required	Description
authorized_visit_count	integer	Yes	Visits the payer authorized.
reference_number	string	No	The payer's authorization reference.
status	string	No	One of ACTIVE, INACTIVE, EXPIRED.
effective_from	string	No
effective_to	string	No
plan_start_date	string	Yes	Required on create. A bare date is widened to the start of that day.
plan_end_date	string	Yes	Required on create.
cpt_codes	array of object	No	Procedure codes this authorization covers, each with its own visit counts. See Cpt Codes.
icd_codes	array of string	No
contact	object	No	Contact details for the payer on this authorization. See Contact.
comments	string	No

Cpt Codes

Parameter	Type	Required	Description
code	string	Yes
authorized_visit_count	integer or null	No	Visits the payer authorized.
used_visit_count	integer or null	No	Visits consumed against the authorization.

Contact

Parameter	Type	Required	Description
phone	string	No
fax	string	No

Request

curl --location '{base_url}/v2/cases/SPRY-63120-2/coverages/90455/authorizations' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "authorized_visit_count": 24,
  "reference_number": "REF-88213",
  "status": "ACTIVE",
  "effective_from": "2026-01-01",
  "effective_to": null,
  "plan_start_date": "2026-01-01",
  "plan_end_date": "2026-12-31",
  "cpt_codes": [
    {
      "code": "97110",
      "authorized_visit_count": 24,
      "used_visit_count": 6
    }
  ],
  "icd_codes": [
    "M25.562"
  ],
  "contact": {
    "phone": "+1-555-0143",
    "fax": null
  },
  "comments": null
}'

Response

Success Response

Code: 201 Created

{
  "id": "auth-5512",
  "spry_case_id": "SPRY-63120-2",
  "coverage_id": "90455",
  "reference_number": "REF-88213",
  "status": "ACTIVE",
  "payer": {
    "id": "auth-5512",
    "name": "Example Therapy \u2014 Riverside"
  },
  "authorized_visit_count": 24,
  "used_visit_count": 6,
  "remaining_visit_count": 18,
  "effective_from": "2026-08-27T14:30:00Z",
  "effective_to": null,
  "plan_start_date": "2026-08-27T14:30:00Z",
  "plan_end_date": "2026-08-27T14:30:00Z",
  "cpt_codes": [
    {
      "code": "97110",
      "authorized_visit_count": 24,
      "used_visit_count": 6
    }
  ],
  "icd_codes": [
    "M25.562"
  ],
  "contact": {
    "phone": "+1-555-0143",
    "fax": null
  },
  "comments": null,
  "created_at": "2026-08-27T14:30:00Z",
  "updated_at": "2026-08-27T14:30:00Z"
}

The Location header carries the URL of the created resource.

Response Fields

Field	Type	Description
id	string	The authorization id.
spry_case_id	string	The case's business key.
coverage_id	string or null	One of the patient's coverages, from GET /v2/patients/{patient_id}/coverages.
reference_number	string or null	The payer's authorization reference.
status	string or null	One of ACTIVE, INACTIVE, EXPIRED.
payer	object	The insurance payer, as a registry reference. See Payer.
authorized_visit_count	integer or null	Visits the payer authorized.
used_visit_count	integer or null	Visits consumed against the authorization.
remaining_visit_count	integer or null	Visits still available.
effective_from	string (date-time) or null
effective_to	string (date-time) or null
plan_start_date	string (date-time) or null	Required on create. A bare date is widened to the start of that day.
plan_end_date	string (date-time) or null	Required on create.
cpt_codes	array of object	Procedure codes this authorization covers, each with its own visit counts. See Cpt Codes.
icd_codes	array of string
contact	object	Contact details for the payer on this authorization. See Contact.
comments	string or null
created_at	string (date-time) or null
updated_at	string (date-time) or null

Payer

Field	Type	Description
id	string or null	The authorization id.
name	string or null

Cpt Codes

Field	Type	Description
code	string
authorized_visit_count	integer or null	Visits the payer authorized.
used_visit_count	integer or null	Visits consumed against the authorization.

Contact

Field	Type	Description
phone	string or null
fax	string or null

Error Response

Code: 400 Bad Request

{
  "code": "bad_request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "patient_id",
      "message": "must be a string"
    }
  ]
}

Every error has the same shape — a machine-readable code, a message, and an errors[] array that's empty when there's nothing field-specific to report. The HTTP status is authoritative.

Status	code	Meaning
400 Bad Request	bad_request	The request body or parameters failed validation. errors[] names the offending fields.
401 Unauthorized	unauthorized	The access token is missing, malformed or expired.
403 Forbidden	forbidden	The request references a resource outside the token's organisation or clinic scope.
404 Not Found	not_found	No such resource, or it's outside your scope.
429 Too Many Requests	rate_limited	Rate limit exceeded. Back off and retry.
500 Internal Server Error	internal_error	Unexpected server error.
502 Bad Gateway	upstream_error	Upstream service failed or timed out.