Skip to main content
POST
Create Benefit Verification Route
Create an asynchronous verification for up to seven medications. Follow Create a benefit verification for a complete request example, input recommendations, and sandbox testing. Provide at least one of insurance (card images) or insurance_content (structured details). Prefer member ID with Rx BIN, PCN, and group. See insurance inputs for alternatives when Rx codes are missing.

Response handling

Store the returned data.id. A successful response means the verification was accepted. Retrieve the result with GET /benefit-verification/{id} or receive a webhook event when it completes or fails. See statuses and error codes for exact states, request errors, and workflow failures.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Models a request to create a benefit verification.

drugs
CodedDrugInfo · object
required

Like DrugInfo, but more closely aligned with NCPDP standards. Helps reduce any confusion on the payer-side.

patient
Patient · object
required

Demographic information for the patient

provider
Provider · object
required

Details of the healthcare provider whose NPI number can be used for the benefit verification.

priority
enum<integer>
default:3

The priority of the benefit verification request, where 0 is most urgent and 3 is least urgent. This will determine the order in which the request is processed.

Available options:
0,
1,
2,
3
preferred_processing_mode
enum<string>
default:standard

The requested processing mode. standard uses standard processing, realtime prefers real-time processing with standard fallback, and realtime_only requires real-time processing without fallback.

Available options:
standard,
realtime,
realtime_only
replaces
string

If this Benefit Verification is being submitted as a replacement for a canceled one, the ID of the canceled Benefit Verification it replaces.

drug_history
Drug History · object
deprecated

The patient's current and previously taken medications.

diagnoses
Diagnosis · object[]

Clinical diagnoses for the patient in ICD-10 format. i.e. 'E66.9'

insurance
InsuranceDocument · object[]

Insurance information for the patient. We will extract the required information from the insurance card images you provide. Please provide both the front and the back of the card. Provide at least one card unless insurance_content contains at least one nonblank field.

insurance_content
Insurance Content · object

Insurance information for the patient. Required with at least one nonblank field unless insurance contains at least one card. An empty object or an object containing only null or blank values does not satisfy this requirement. If you provide both insurance and insurance_content, the values provided here will be used and the values extracted from insurance will be used as a fallback.

entity
Entity · object

The legal entity associated with the provider. The entity and its legal_name and tax_id fields are optional at API intake. Some payers require these details to complete verification, so missing information can cause a later verification failure. Supply them when available.

mock_result
Mock Result · object

Specifies the simulated outcome for a completed verification. The selected case determines the individual drug results. This field is only accepted for sandbox organizations.

use_patient_plan_fund_source_check
boolean
default:false

Whether to check the patient's plan fund source during the benefit verification call.

Response

Successful creation of a benefit verification

Models the response received upon creating a benefit verification request.

status
default:success
Available options:
success
error
ApiError · object
data
CreateBenefitVerificationResponseData · object

Represents the data contained in the response for a create benefit verification request.