Resolve requirements | Collate API Documentation

Use this guide when an authorization asks for resolve_requirements. Requirements are the current blockers that prevent Collate from continuing.

The returned questionnaire is a machine-readable answer contract. Your integration can satisfy it from backend mappings, an agent, imported clinical data, or a controlled human workflow. Answer and attachment writes recompute requirements. They do not resume processing by themselves.

Requirement loop

Read the latest authorization

Start from the full authorization object.

1 GET /v1/prior-authorizations/auth_123
2 Authorization: Bearer <API_KEY>

Field	Use it for
`version`	Send as `If-Match` on mutable authorization writes.
`questionnaire`	Determine the current answerable items and allowed values.
`answers`	Pre-fill fields with existing normalized answers.
`requirements.questions`	Fields that are missing or invalid.
`requirements.documents`	Supporting documents still required.
`requirements.issues`	Validation issues on the current snapshot.

Interpret the questionnaire

Treat the returned questionnaire as the current answer contract instead of assuming one universal field list. Each item has a linkId, prompt, type, and optional validation hints.

1 {
2   "linkId": "diagnoses",
3   "text": "Diagnoses",
4   "type": "group",
5   "required": true,
6   "repeats": true,
7   "minOccurs": 1,
8   "maxOccurs": 12,
9   "item": [
10     { "linkId": "code", "text": "Diagnosis Code", "type": "string", "required": true },
11     {
12       "linkId": "qualifierCode",
13       "text": "Diagnosis Qualifier",
14       "type": "choice",
15       "required": true,
16       "options": [{ "code": "ABF", "display": "ICD-10" }]
17     }
18   ]
19 }

For choices, submit the option code, not the display label. For repeated groups, submit nested group items, not flat indexed slots such as diagnoses.0.code.

Patch answers

Send only the answer items you want to change. Omitted items are left as-is.

1 PATCH /v1/prior-authorizations/auth_123/answers
2 Authorization: Bearer <API_KEY>
3 If-Match: "4"
4 Content-Type: application/json
5 
6 {
7   "answers": {
8     "item": [
9       { "linkId": "coverage.member_id", "answer": [{ "valueString": "W123456789" }] },
10       { "linkId": "request.urgency", "answer": [{ "valueCoding": { "code": "standard" } }] },
11       { "linkId": "service.requested_start_date", "answer": [{ "valueDate": "2026-06-01" }] },
12       {
13         "linkId": "diagnoses",
14         "item": [
15           { "linkId": "code", "answer": [{ "valueString": "M06.9" }] },
16           { "linkId": "qualifierCode", "answer": [{ "valueCoding": { "code": "ABF" } }] }
17         ]
18       }
19     ]
20   }
21 }

Field type	Submit
`string`	`valueString`
`boolean`	`valueBoolean`
`date`	`valueDate`
`number`	`valueDecimal`
`choice`	`valueCoding.code`

Attach required documents

For every requirements.documents entry, upload a file and link it with the matching documentTypes value.

1 {
2   "fileId": "file_123",
3   "documentTypes": ["clinical_notes"]
4 }

One file can satisfy multiple document requirements:

1 {
2   "fileId": "file_123",
3   "documentTypes": ["clinical_notes", "labs"]
4 }

See Attaching files for the upload flow.

Continue when blockers clear

Each answer or attachment write returns the updated authorization.

Updated `nextAction.type`	What to do
`resolve_requirements`	Keep resolving the returned blockers.
`continue_authorization`	Call `POST /confirm` with the current `version`.
`approve_submission`	Review `submission.reviewSnapshot`, then call `POST /confirm`.
`complete_payer_interaction`	Follow the manual handoff flow.

Answer and attachment writes are rejected while Collate owns the case, after terminal states, and while an active manual handoff owns payer interaction.