Send a prior authorization through the API. A physician signs every production determination. Sample keys stop after validation. HIPAA-compliant, BAA in place, encrypted.
Authentication
Send header x-api-key with a key from your organization. You can also send Authorization: Bearer with the same key, or with an OAuth access token.
Production keys start with vum_live_. Sandbox keys start with vum_test_. An API key includes pas.submit and pas.read.
OAuth uses grant type client_credentials at /api/fhir/pas/token. Scopes are pas.submit and pas.read. If you omit scope, the token includes pas.submit and pas.read.
Endpoint
POST /api/fhir/pas/Claim/$submit on your Vanta host. The body is a JSON Bundle. Content-Type may be application/fhir+json or application/json.
Required FHIR resources
- A Bundle with type collection and meta.profile http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-pas-request-bundle.
- One Claim with meta.profile http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim, status active, and use preauthorization.
- Claim.id and Claim.identifier so the case can be correlated later.
- Claim.patient.reference, plus a Patient entry that uses a synthetic member token.
- At least one Claim.item with sequence and productOrService.coding.
- Insurer and provider references. The Organization resources themselves are optional.
Minimal synthetic example
This bundle is the one the intake validator accepts. It uses synthetic tokens only.
Bundle
{
"resourceType": "Bundle",
"id": "pas-docs-bundle",
"meta": {
"profile": [
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-pas-request-bundle"
]
},
"identifier": {
"system": "https://vantaum.example/submitter-transaction",
"value": "txn-docs-1"
},
"type": "collection",
"timestamp": "2026-10-26T12:00:00Z",
"entry": [
{
"resource": {
"resourceType": "Claim",
"id": "pas-docs-claim",
"meta": {
"profile": [
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim"
]
},
"identifier": [
{
"system": "https://vantaum.example/patient-event-trace",
"value": "TRACE-DOC-1"
}
],
"status": "active",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/claim-type",
"code": "professional"
}
]
},
"use": "preauthorization",
"patient": {
"reference": "Patient/DocsSubscriber"
},
"created": "2026-10-26T12:00:00Z",
"insurer": {
"reference": "Organization/SyntheticInsurer"
},
"provider": {
"reference": "Organization/SyntheticRequestor"
},
"priority": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/processpriority",
"code": "normal"
}
]
},
"item": [
{
"sequence": 1,
"productOrService": {
"coding": [
{
"system": "http://www.ama-assn.org/go/cpt",
"code": "99213",
"display": "Synthetic office visit"
}
]
}
}
]
}
},
{
"resource": {
"resourceType": "Patient",
"id": "DocsSubscriber",
"identifier": [
{
"system": "https://vantaum.example/synthetic-member",
"value": "SYN-MEM-DOCS"
}
]
}
}
]
}Pended response
A successful submit returns HTTP 200 and a ClaimResponse bundle. Disposition is Pending. The review action is A4 (Pending) with reason E8 (Requires Medical Review). The sample below is built by the same acknowledgement function the endpoint uses.
Pended response
{
"resourceType": "Bundle",
"id": "pas-response-00000000-0000-4000-8000-0000000000d0",
"meta": {
"profile": [
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-pas-response-bundle"
]
},
"type": "collection",
"timestamp": "2026-10-26T12:00:00.000Z",
"identifier": {
"system": "https://vantaum.example/submitter-transaction",
"value": "txn-docs-1"
},
"entry": [
{
"fullUrl": "https://vantaum.example/fhir/ClaimResponse/response-00000000-0000-4000-8000-0000000000d0",
"resource": {
"resourceType": "ClaimResponse",
"id": "response-00000000-0000-4000-8000-0000000000d0",
"meta": {
"profile": [
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claimresponse"
]
},
"identifier": [
{
"system": "https://vantaum.example/patient-event-trace",
"value": "TRACE-DOC-1"
}
],
"status": "active",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/claim-type",
"code": "professional"
}
]
},
"use": "preauthorization",
"patient": {
"reference": "Patient/DocsSubscriber"
},
"created": "2026-10-26T12:00:00.000Z",
"insurer": {
"reference": "Organization/SyntheticInsurer"
},
"requestor": {
"reference": "Organization/SyntheticRequestor"
},
"request": {
"reference": "Claim/pas-docs-claim"
},
"outcome": "complete",
"disposition": "Pending",
"preAuthRef": [
"VUM-SBX-DOCS"
],
"item": [
{
"itemSequence": 1,
"adjudication": [
{
"extension": [
{
"url": "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-reviewAction",
"extension": [
{
"url": "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-reviewActionCode",
"valueCodeableConcept": {
"coding": [
{
"system": "https://codesystem.x12.org/005010/306",
"code": "A4",
"display": "Pending"
}
]
}
},
{
"url": "reasonCode",
"valueCodeableConcept": {
"coding": [
{
"system": "https://codesystem.x12.org/external/886",
"code": "E8",
"display": "Requires Medical Review"
}
]
}
}
]
}
],
"category": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/adjudication",
"code": "submitted"
}
]
}
}
],
"extension": [
{
"url": "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-administrationReferenceNumber",
"valueString": "VUM-SBX-DOCS"
}
]
}
]
}
},
{
"fullUrl": "https://vantaum.example/fhir/Patient/DocsSubscriber",
"resource": {
"resourceType": "Patient",
"id": "DocsSubscriber",
"meta": {
"profile": [
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-subscriber"
]
},
"identifier": [
{
"system": "https://vantaum.example/synthetic-member",
"value": "SYN-MEM-DOCS"
}
]
}
}
]
}How results come back
Push
After a clinician signs a production case, Vanta POSTs the final ClaimResponse to the callback URL on your organization. Pull stays available if that URL is not set. Sandbox submissions are not pushed and are not signed.
Pull with $response
POST /api/fhir/pas/Claim/$response. POST the $response endpoint with pas.read, or with an API key, and JSON that contains case_id or trace. Until a clinician signs, production pull returns awaiting_human_signature. The final body is the signed ClaimResponse. A sandbox pull returns the same pended body from $submit.
Sandbox
Sandbox. Not the production queue.
A sandbox key runs the same validation and returns the same pended ClaimResponse shape. The response header x-vanta-sandbox: true marks it. The case is not created, not placed on the doctor queue, and not billed. Do not send real patient information. Names, birth dates, addresses, phone numbers, and email addresses are refused and are not written to sandbox logs.
Error codes
| Code | Status | What it means | How to fix it |
|---|---|---|---|
| unauthorized | 401 | The API key or bearer token is missing, unknown, or revoked. | Send the x-api-key header or Authorization: Bearer with a key from your organization. Create a new key if this one was revoked. |
| insufficient_scope | 403 | An OAuth token is missing pas.submit on $submit or pas.read on $response. | Request the scope you need at the token endpoint. An API key already includes both scopes. |
| invalid_scope | 400 | The token request asked for a scope other than pas.submit or pas.read. | Send scope=pas.submit, scope=pas.read, or both separated by a space. Omit scope to receive both. |
| invalid_json | 400 | The body is not JSON. | Post a JSON Bundle with Content-Type application/fhir+json or application/json. |
| invalid_bundle | 400 | The body is not a collection Bundle, or it does not contain exactly one Claim. | Use resourceType Bundle, type collection, and a single Claim entry. |
| invalid_profile | 400 | The Bundle or Claim is missing the PAS profile URL. | Set Bundle.meta.profile and Claim.meta.profile to the PAS request-bundle and claim profiles. |
| invalid_claim | 400 | The Claim is missing id, identifier, patient, status, use, or a coded item. | Set status active, use preauthorization, and include Claim.id, Claim.identifier, patient.reference, and one item.productOrService. |
| med_review_not_enabled | 403 | API intake is not enabled for this organization. | Request access. Staff turns on API intake for the organization. |
| sandbox_phi_refused | 400 | A sandbox key submitted a bundle that contains a patient name, birth date, address, phone, or email. | Replace those fields with synthetic tokens such as SYN-MEM-DOCS. Sandbox does not accept real patient information. |
| awaiting_human_signature | 409 | You called $response before a clinician signed the production case. | Read the pended $submit response, then call $response again after the determination is signed. Sandbox cases stay pended. |
| not_found | 404 | $response cannot find a case for that id on your organization and channel. | Use the case id from your own $submit response, or the Claim.identifier trace. A sandbox key cannot read a production case. |