Create a benefit verification

Create a BV with POST /benefit-verification. Use the example sandbox request to test with synthetic data. The endpoint reference contains all request and response fields. Use National Drug Codes (NDCs) whenever possible. They identify the intended medication and are required for real-time processing.

Example sandbox request

View example request

Set DEVELOP_HEALTH_SANDBOX_TOKEN to an API token for your sandbox organization. Store it securely on your server.Save this as bv-request.json. The sandbox-only mock_result returns a simulated result. The NPI is illustrative. Use your configured sandbox test provider if your workflow requires one.

{
  "patient": {
    "internal_id": "sandbox-patient-001",
    "first_name": "Jamie",
    "last_name": "Example",
    "date_of_birth": "1990-01-15",
    "gender": "female",
    "address": {
      "street": "123 Example Street",
      "city": "San Francisco",
      "state_province": "CA",
      "zip_postal_code": "94107"
    }
  },
  "provider": {
    "first_name": "Alex",
    "last_name": "Example",
    "npi": "1234567893",
    "address": {
      "street": "456 Example Avenue",
      "city": "San Francisco",
      "state_province": "CA",
      "zip_postal_code": "94107"
    }
  },
  "insurance_content": {
    "member_number": "SANDBOX001",
    "rx_bin": "012345",
    "rx_pcn": "TESTPCN",
    "rx_group": "TESTGROUP",
    "payer_name": "Example Health Plan",
    "plan_name": "Example Pharmacy Plan"
  },
  "drugs": [
    {
      "ndc": "00169450514",
      "quantity": 4
    }
  ],
  "preferred_processing_mode": "standard",
  "mock_result": {
    "status": "completed",
    "case": "drugs_covered__prior_auth_not_required__has_copay"
  }
}

Submit the request:

curl https://api.develophealth.ai/benefit-verification \
  -H "Authorization: Bearer $DEVELOP_HEALTH_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @bv-request.json

Save the returned data.id to track the result. For more simulated outcomes, see sandbox testing.

Minimum request and recommended inputs

Field	Requirement	Recommended for completion
`patient`	Stable `internal_id`, first and last name, date of birth, gender, and complete address	Accurate demographics matching the insurance record; phone and email when available
`provider`	First and last name, NPI, and complete address	Provider phone and fax when available
`drugs`	One to seven medications	Use the NDC format for each medication to avoid ambiguity
`insurance` or `insurance_content`	At least one is required	Prefer member ID with Rx BIN, PCN, and group. See insurance for alternatives
`entity`	Optional	Legal name and tax ID when available, because some payers require them
`diagnoses`	Optional	Relevant ICD-10 codes to help interpret coverage for the prescribed indication
`preferred_processing_mode`	Optional; defaults to `standard`	Choose whether to attempt real-time processing and allow standard fallback

Include the patient, provider, drug, and insurance inputs above. An accepted request can still fail later if the payer cannot identify the member or needs more information.

Patient and provider data

Addresses

Both the patient and provider require a complete address with:

street
city
state_province, using a valid US state
zip_postal_code, as a string so leading zeros are preserved

street_line_2 is optional and country defaults to USA. Use the patient’s current address as recorded with their insurer.

Gender

patient.gender is required and accepts male, female, other, or not_specified. Use not_specified when the information has not been provided. Send known information that matches the payer record. Missing demographics can affect matching and cause delays or inaccurate results.

Patient identifiers

Use a stable patient.internal_id for the same patient across BV and PA requests. Store each returned BV ID separately so you can associate webhook updates with the correct workflow. The patient ID does not deduplicate create requests.

Provider NPI and tax ID

Send the provider whose NPI is authorized for the verification. Supplying the provider object does not itself authorize the provider. Resolve authorization requirements during onboarding and handle authorization errors. The NPI identifies the provider and is different from an entity’s tax ID. entity.legal_name and entity.tax_id are optional at intake, but some payers require them to complete verification. A missing tax ID can cause a later failure even though the API accepted the request. See BV failure detail codes.

Insurance

Provide at least one of insurance (card images) or insurance_content (structured details). You can send both. For insurance_content, prioritize the member ID and pharmacy routing codes:

Preferred: Member ID with Rx BIN, Rx PCN, and Rx group.
Some Rx codes missing: Member ID with every Rx code you have, plus payer and plan names.
No Rx codes available: Member ID with payer and plan names.

Field	What to send
`member_number`	The member ID on the card, preserved as a string
`rx_bin`	The six-digit pharmacy routing BIN, as a string to preserve leading zeros
`rx_pcn`	The pharmacy processor control number
`rx_group`	The pharmacy benefit group identifier; keep it separate from `group_number`
`payer_name`	The payer name as shown on the card, as free text
`plan_name`	The plan name as shown on the card
`member_name`	The member name on the card, when available
`group_number`	The group number on the card, when available
`client_name`	The employer or client name, when shown

The alternatives above apply to standard processing. See real-time inputs for the structured insurance requirements in real-time modes.

Upload insurance cards

Send each card side as a separate item in insurance, with the file bytes encoded as Base64 in file_content. Insurance-card uploads require file contents; download URLs are unsupported. Replace these placeholders with Base64-encoded files:

{
  "insurance": [
    { "file_content": "BASE64_FRONT_OF_CARD" },
    { "file_content": "BASE64_BACK_OF_CARD" }
  ]
}

Supported formats are JPEG/JPG, PNG, TIFF, BMP, HEIC, or a single-page PDF. Keep each decoded insurance-card image below 4 MiB (4,194,304 bytes) before Base64 encoding. Resize larger images before uploading. This size guidance applies only to decoded insurance-card images. Send each PDF card side as a single-page file.

Read extracted insurance data

GET /benefit-verification/{id} returns insurance records in data.insurance. Each record uses discrete_content for the values you supplied and scanned_content for values extracted from card images.

Identify medications by NDC

Use CodedDrugInfo with an ndc and an integer quantity for each medication. This format supports standard and real-time processing. Example entry in drugs:

{
  "ndc": "00169450514",
  "quantity": 4
}

The coded format accepts supported product or package NDC representations, including the examples in the endpoint schema. Prefer the exact package NDC when available and keep it as a string to preserve leading zeros. A syntactically valid code must still resolve to a supported drug. For brand versus generic comparisons, submit each exact NDC separately.

Quantity and units

Quantity is separate from days supply. For the specific Wegovy presentation in the coded example above, four individual single-dose pens use quantity: 4. Confirm the mapping for other presentations, including quantities recorded in cartons or milliliters.

BV drug objects have no quantity unit field or general unit-conversion rule. An NDC alone does not specify whether your quantity represents cartons, pens, or mL. Before sending fractional quantities, liquids, or multidose pens, confirm the mapping with Develop Health. Do not round a fractional quantity to fit CodedDrugInfo, or add the PA-only quantity_unit_of_measure field to a BV request.

PA prescriptions have a separate quantity contract. See the PA prescription guide.

Only when an NDC is unavailable

Use the name-based DrugInfo format only when you cannot obtain an NDC. This fallback supports standard processing only. Provide name, dosage, and quantity:

{
  "name": "Metformin",
  "dosage": "500 mg",
  "quantity": 30
}

Keep the entire drugs array in one format. Do not mix name-based and NDC-based entries.DrugInfo accepts a numeric quantity, including decimals. Confirm the dispensing unit as described above. Its ndc field is read-only and ignored on input; use CodedDrugInfo when supplying an NDC.

Real-time inputs

Both realtime and realtime_only require real-time access to be enabled for your organization and an NDC for every drug. Include structured insurance in insurance_content, with the member number and Rx BIN, PCN, and group when applicable. Card images alone do not qualify. Use realtime when standard fallback is acceptable, or realtime_only when your application can handle a failed real-time attempt without fallback. See real-time processing for the complete eligibility and fallback rules.

Multiple drugs

Submit one to seven drugs in a single request. Store the returned BV ID and inspect each drug’s result after completion. Real-time completion requires all requested drugs to complete within the real-time deadline. Each submitted drug consumes one unit of the applicable BV drug quota. Confirm billing terms separately with your Develop Health contact.

Receive the result

Wait for benefit_verification.status_change or use GET /benefit-verification/{id}. Completion time depends on the verification method and payer, including after real-time fallback. See completion time for typical timings by method and response handling to determine when results are ready.

Start here

Benefit verification

Prior authorization

Integration

Create a benefit verification

Example sandbox request

Minimum request and recommended inputs

Patient and provider data

Addresses

Gender

Patient identifiers

Provider NPI and tax ID

Insurance

Upload insurance cards

Read extracted insurance data

Identify medications by NDC

Quantity and units

Real-time inputs

Multiple drugs

Receive the result

​Example sandbox request

​Minimum request and recommended inputs

​Patient and provider data

​Addresses

​Gender

​Patient identifiers

​Provider NPI and tax ID

​Insurance

​Upload insurance cards

​Read extracted insurance data

​Identify medications by NDC

​Quantity and units

​Real-time inputs

​Multiple drugs

​Receive the result

Example sandbox request

Minimum request and recommended inputs

Patient and provider data

Addresses

Gender

Patient identifiers

Provider NPI and tax ID

Insurance

Upload insurance cards

Read extracted insurance data

Identify medications by NDC

Quantity and units

Real-time inputs

Multiple drugs

Receive the result