Guides
Authorizations
System
curl --request POST \
--url https://api.sandbox.trycollate.ai/v1/prior-auth/authorizations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"providerNpi": "<string>",
"templateSelection": {
"payerId": "<string>",
"insuranceState": "<string>",
"serviceType": "inpatient",
"serviceCode": "<string>",
"serviceCodeSystem": "hcpcs"
}
}
'{
"id": "<string>",
"version": 123,
"status": "requires_input",
"policy": {
"finalSubmission": "automatic"
},
"providerNpi": "<string>",
"payer": {
"id": "<string>",
"displayName": "<string>",
"supportedStates": [
"<string>"
],
"supportedServiceTypes": [
"inpatient"
],
"aliases": [
"<string>"
],
"status": "<string>",
"brand": "<string>",
"lineOfBusiness": "<string>"
},
"templateSelection": {
"payerId": "<string>",
"insuranceState": "<string>",
"serviceType": "inpatient",
"serviceCode": "<string>",
"serviceCodeSystem": "hcpcs"
},
"questionnaire": [
{
"id": "<string>",
"title": "<string>",
"items": [
{
"linkId": "<string>",
"text": "<string>",
"required": false,
"answerType": "string",
"options": [
{
"code": "<string>",
"display": "<string>"
}
],
"pattern": "<string>",
"maxLength": 123,
"min": "<string>",
"max": "<string>",
"errorMessage": "<string>",
"mode": "<string>",
"defaultValue": {},
"requiredWhen": {},
"notAllowedWhen": {},
"valuesWhen": {},
"textWhen": {}
}
]
}
],
"questionnaireResponse": {
"item": [
{
"linkId": "<string>",
"answer": [
{
"valueString": "<string>",
"valueBoolean": true,
"valueDate": "<string>",
"valueDecimal": 123,
"valueCoding": {
"code": "<string>"
}
}
]
}
]
},
"requirements": {
"version": 123,
"questions": [
{
"linkId": "<string>",
"message": "<string>"
}
],
"documents": [
{
"type": "<string>",
"message": "<string>"
}
],
"issues": [
{
"code": "<string>",
"message": "<string>",
"field": "<string>",
"severity": "error"
}
]
},
"submission": {
"reviewSnapshot": {
"id": "<string>",
"generatedAt": "2023-11-07T05:31:56Z",
"covers": {
"authorizationVersion": 123,
"requirementsVersion": 123,
"questionnaireResponseVersion": 123,
"attachmentVersion": 123
},
"status": "current",
"kind": "final_submission",
"summary": {},
"questionnaireResponse": {
"item": [
{
"linkId": "<string>",
"answer": [
{
"valueString": "<string>",
"valueBoolean": true,
"valueDate": "<string>",
"valueDecimal": 123,
"valueCoding": {
"code": "<string>"
}
}
]
}
]
},
"attachments": [
{
"id": "<string>",
"fileId": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"documentTypes": [
"<string>"
],
"label": "<string>",
"description": "<string>"
}
],
"warnings": [
"<string>"
],
"liveViewUrl": "<string>"
},
"payerReceipt": {
"receivedAt": "2023-11-07T05:31:56Z",
"referenceNumber": "<string>",
"channel": "<string>",
"payerStatusText": "<string>",
"details": {}
},
"decision": {
"receivedAt": "2023-11-07T05:31:56Z",
"authorizationNumber": "<string>",
"payerStatusText": "<string>",
"effectiveFrom": "2023-11-07T05:31:56Z",
"effectiveTo": "2023-11-07T05:31:56Z",
"modifications": [
"<string>"
],
"denialReasons": [
"<string>"
],
"details": {}
}
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"outcome": "approved",
"portalAuthMode": "automated",
"attachments": [
{
"id": "<string>",
"fileId": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"documentTypes": [
"<string>"
],
"label": "<string>",
"description": "<string>"
}
],
"nextAction": {
"id": "<string>",
"type": "provide_requirements",
"description": "<string>",
"authorizationVersion": 123,
"requirementsVersion": 123,
"createdAt": "2023-11-07T05:31:56Z",
"owner": "customer",
"reviewSnapshotId": "<string>",
"expiresAt": "2023-11-07T05:31:56Z"
},
"completedAt": "2023-11-07T05:31:56Z",
"canceledAt": "2023-11-07T05:31:56Z"
}Create an authorization
Creates an Authorization for a single prior-authorization request.
curl --request POST \
--url https://api.sandbox.trycollate.ai/v1/prior-auth/authorizations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"providerNpi": "<string>",
"templateSelection": {
"payerId": "<string>",
"insuranceState": "<string>",
"serviceType": "inpatient",
"serviceCode": "<string>",
"serviceCodeSystem": "hcpcs"
}
}
'{
"id": "<string>",
"version": 123,
"status": "requires_input",
"policy": {
"finalSubmission": "automatic"
},
"providerNpi": "<string>",
"payer": {
"id": "<string>",
"displayName": "<string>",
"supportedStates": [
"<string>"
],
"supportedServiceTypes": [
"inpatient"
],
"aliases": [
"<string>"
],
"status": "<string>",
"brand": "<string>",
"lineOfBusiness": "<string>"
},
"templateSelection": {
"payerId": "<string>",
"insuranceState": "<string>",
"serviceType": "inpatient",
"serviceCode": "<string>",
"serviceCodeSystem": "hcpcs"
},
"questionnaire": [
{
"id": "<string>",
"title": "<string>",
"items": [
{
"linkId": "<string>",
"text": "<string>",
"required": false,
"answerType": "string",
"options": [
{
"code": "<string>",
"display": "<string>"
}
],
"pattern": "<string>",
"maxLength": 123,
"min": "<string>",
"max": "<string>",
"errorMessage": "<string>",
"mode": "<string>",
"defaultValue": {},
"requiredWhen": {},
"notAllowedWhen": {},
"valuesWhen": {},
"textWhen": {}
}
]
}
],
"questionnaireResponse": {
"item": [
{
"linkId": "<string>",
"answer": [
{
"valueString": "<string>",
"valueBoolean": true,
"valueDate": "<string>",
"valueDecimal": 123,
"valueCoding": {
"code": "<string>"
}
}
]
}
]
},
"requirements": {
"version": 123,
"questions": [
{
"linkId": "<string>",
"message": "<string>"
}
],
"documents": [
{
"type": "<string>",
"message": "<string>"
}
],
"issues": [
{
"code": "<string>",
"message": "<string>",
"field": "<string>",
"severity": "error"
}
]
},
"submission": {
"reviewSnapshot": {
"id": "<string>",
"generatedAt": "2023-11-07T05:31:56Z",
"covers": {
"authorizationVersion": 123,
"requirementsVersion": 123,
"questionnaireResponseVersion": 123,
"attachmentVersion": 123
},
"status": "current",
"kind": "final_submission",
"summary": {},
"questionnaireResponse": {
"item": [
{
"linkId": "<string>",
"answer": [
{
"valueString": "<string>",
"valueBoolean": true,
"valueDate": "<string>",
"valueDecimal": 123,
"valueCoding": {
"code": "<string>"
}
}
]
}
]
},
"attachments": [
{
"id": "<string>",
"fileId": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"documentTypes": [
"<string>"
],
"label": "<string>",
"description": "<string>"
}
],
"warnings": [
"<string>"
],
"liveViewUrl": "<string>"
},
"payerReceipt": {
"receivedAt": "2023-11-07T05:31:56Z",
"referenceNumber": "<string>",
"channel": "<string>",
"payerStatusText": "<string>",
"details": {}
},
"decision": {
"receivedAt": "2023-11-07T05:31:56Z",
"authorizationNumber": "<string>",
"payerStatusText": "<string>",
"effectiveFrom": "2023-11-07T05:31:56Z",
"effectiveTo": "2023-11-07T05:31:56Z",
"modifications": [
"<string>"
],
"denialReasons": [
"<string>"
],
"details": {}
}
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"outcome": "approved",
"portalAuthMode": "automated",
"attachments": [
{
"id": "<string>",
"fileId": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"documentTypes": [
"<string>"
],
"label": "<string>",
"description": "<string>"
}
],
"nextAction": {
"id": "<string>",
"type": "provide_requirements",
"description": "<string>",
"authorizationVersion": 123,
"requirementsVersion": 123,
"createdAt": "2023-11-07T05:31:56Z",
"owner": "customer",
"reviewSnapshotId": "<string>",
"expiresAt": "2023-11-07T05:31:56Z"
},
"completedAt": "2023-11-07T05:31:56Z",
"canceledAt": "2023-11-07T05:31:56Z"
}An authorization is the durable case Collate uses to track requirement collection, payer submission, receipt, and final outcome. Create one authorization per payer submission you want Collate to manage. The request pins the provider, payer route, service code, and final-submission policy. Optional initial answers are merged before the case is created. The response is the canonical authorization snapshot — questionnaire, current requirements, andDocumentation Index
Fetch the complete documentation index at: https://docs.trycollate.ai/llms.txt
Use this file to discover all available pages before exploring further.
nextAction — at version 1.
Creating an authorization does not submit anything to the payer. Inspect the
returned snapshot, resolve any blockers, and call
Confirm an authorization only when
the authorization exposes a confirmable nextAction.
Reuse the same Idempotency-Key to retry a create safely. Reusing it with a
different request body returns 409 idempotency_key_reused.
Returns
Returns the newly created authorization.Authorizations
API key passed as Authorization: Bearer <API_KEY>.
Headers
Unique key used to retry command requests safely. Reusing the same key with a different request body returns 409 idempotency_key_reused.
Body
Provider NPI for the authorization.
Payer route and service code to use for the authorization.
Hide child attributes
Hide child attributes
Canonical payer ID to route the authorization to.
Two-letter insurance state for the request.
Prior-auth service category.
inpatient, outpatient, drug HCPCS, CPT, or NDC code for the requested service.
Code system used by serviceCode.
hcpcs, cpt, ndc Required final-submission policy for the authorization.
Hide child attributes
Hide child attributes
Controls whether Collate may submit to the payer automatically at the final submission boundary or must pause for approval.
automatic, requires_confirmation Portal auth mode to use when the selected route supports multiple modes.
automated, customer_login Optional initial answer set to apply at create time.
Hide child attributes
Hide child attributes
Normalized answer items keyed by questionnaire linkId.
Hide child attributes
Hide child attributes
Questionnaire linkId this answer applies to.
Answers supplied for this field.
Hide child attributes
Hide child attributes
String answer value.
Boolean answer value.
Date answer value.
Decimal answer value.
Response
Successful Response
Stable authorization ID.
Optimistic-concurrency version for mutable operations.
Current lifecycle status.
requires_input, requires_confirmation, processing, waiting_on_payer, completed, canceled Authorization policy selected at create time.
Hide child attributes
Hide child attributes
Controls whether Collate may submit to the payer automatically at the final submission boundary or must pause for approval.
automatic, requires_confirmation Tenant-scoped provider NPI for the case.
Canonical payer destination for the case.
Hide child attributes
Hide child attributes
Canonical payer ID.
Human-readable payer name.
Two-letter states supported for this payer.
Prior-auth service categories supported for this payer.
inpatient, outpatient, drug Common payer aliases used for search and matching.
Catalog status for the payer.
Parent payer brand, when available.
Payer line of business, when available.
Pinned route and service-code selection used for the authorization.
Hide child attributes
Hide child attributes
Canonical payer ID to route the authorization to.
Two-letter insurance state for the request.
Prior-auth service category.
inpatient, outpatient, drug HCPCS, CPT, or NDC code for the requested service.
Code system used by serviceCode.
hcpcs, cpt, ndc Full current editable question surface.
Hide child attributes
Hide child attributes
Stable group ID.
Human-readable group title.
Questionnaire items in this group.
Hide child attributes
Hide child attributes
Stable field key used in questionnaireResponse.
Question text to show the user.
Whether the field is required.
Answer value type expected for this field.
string, date, boolean, decimal, coding Regular expression constraint for string answers.
Maximum string length when constrained.
Minimum allowed value when constrained.
Maximum allowed value when constrained.
Custom validation message for the field.
Rendering or collection mode hint.
Default answer value, when configured.
Condition that makes the field required.
Condition that makes the field invalid to answer.
Conditionally available option values.
Conditionally displayed text variants.
Current normalized answer set.
Hide child attributes
Hide child attributes
Normalized answer items keyed by questionnaire linkId.
Hide child attributes
Hide child attributes
Questionnaire linkId this answer applies to.
Answers supplied for this field.
Hide child attributes
Hide child attributes
String answer value.
Boolean answer value.
Date answer value.
Decimal answer value.
Current unresolved blocker set.
Hide child attributes
Hide child attributes
Requirements version for concurrency and nextAction checks.
Validation issues Collate detected on the current snapshot.
Hide child attributes
Hide child attributes
Stable validation issue code.
Human-readable issue message.
Questionnaire linkId or field path related to the issue.
Issue severity.
error, warning, info Submission review, receipt, and decision projections.
Hide child attributes
Hide child attributes
Final-submission review snapshot when approval is required.
Hide child attributes
Hide child attributes
Stable review snapshot ID.
Time when Collate generated the snapshot.
Version coverage used to reject stale final approvals.
Hide child attributes
Hide child attributes
Authorization version covered by the review snapshot.
Requirements version covered by the review snapshot.
Answer-set version covered by the review snapshot.
Attachment-set version covered by the review snapshot.
Review snapshot status. Current snapshots can be approved.
Review snapshot purpose.
Structured final-submission summary for review.
Answer set represented in the final review snapshot.
Hide child attributes
Hide child attributes
Normalized answer items keyed by questionnaire linkId.
Hide child attributes
Hide child attributes
Questionnaire linkId this answer applies to.
Answers supplied for this field.
Hide child attributes
Hide child attributes
String answer value.
Boolean answer value.
Date answer value.
Decimal answer value.
Attachments represented in the final review snapshot.
Hide child attributes
Hide child attributes
Stable attachment ID scoped to the authorization.
File ID linked as the attachment source.
Time when the attachment was linked.
Document requirement types this attachment satisfies.
Human-readable file label, usually the original file name.
Optional description for the attachment.
Warnings to review before approval.
Live browser view URL when browser sign-in is active.
Evidence-backed proof that the payer received the submission.
Hide child attributes
Hide child attributes
Time when payer receipt was proven.
Payer or portal reference number when available.
Submission channel that produced the receipt.
Raw payer-visible status text associated with the receipt.
Terminal payer decision details when known.
Hide child attributes
Hide child attributes
Time when the terminal payer decision was observed.
Payer-issued authorization number, when approved or modified.
Raw payer-visible status text for the decision.
Start of the payer-approved authorization window, when available.
End of the payer-approved authorization window, when available.
Payer modifications to the requested service.
Payer denial reasons when the outcome is denied.
Time when the authorization was created.
Time when the authorization last changed.
Terminal outcome when status = completed.
approved, denied, modified, not_required, failed How Collate should access the payer portal for this route.
automated, customer_login Supporting documents linked to the authorization.
Hide child attributes
Hide child attributes
Stable attachment ID scoped to the authorization.
File ID linked as the attachment source.
Time when the attachment was linked.
Document requirement types this attachment satisfies.
Human-readable file label, usually the original file name.
Optional description for the attachment.
Current action, when one is open.
Hide child attributes
Hide child attributes
Stable ID for the current action.
The kind of action needed before the case can advance.
provide_requirements, advance_case, approve_submission Human-readable description of the action.
Authorization version this action was created against.
Requirements version this action was created against.
Time when the action was created.
The party responsible for resolving this action.
Review snapshot ID for approve_submission actions.
Time when the action expires, if the action is time-limited.
Time when the authorization reached completed.
Time when the authorization reached canceled.