> ## Documentation Index
> Fetch the complete documentation index at: https://docs.develophealth.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a benefit verification

> Required fields, insurance inputs, drug identifiers, quantity, and multi-drug requests.

Create a BV with `POST /benefit-verification`. Use the
[example sandbox request](#example-sandbox-request) to test with synthetic data.
The [endpoint reference](/api-reference/medication-benefit-check/post) 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

<Accordion title="View example request">
  Set `DEVELOP_HEALTH_SANDBOX_TOKEN` to an API token for your
  [sandbox organization](/guides/testing#environment-and-credentials). 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.

  ```json theme={null}
  {
    "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:

  ```bash theme={null}
  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](/guides/testing#simulate-benefit-verification-outcomes).
</Accordion>

## 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](#identify-medications-by-ndc) 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](#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](/api-reference/medication-benefit-check/response-handling).

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](/api-reference/medication-benefit-check/response-handling#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](#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:

```json theme={null}
{
  "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}`](/api-reference/medication-benefit-check/get_item) 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`:

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>

PA prescriptions have a separate quantity contract. See the
[PA prescription guide](/api-reference/prior-authorization/request-guide#prescription-and-quantity).

<Accordion title="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`:

  ```json theme={null}
  {
    "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.
</Accordion>

## 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](/api-reference/medication-benefit-check/realtime-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](/api-reference/rate-limits#requests-containing-multiple-drugs).
Confirm billing terms separately with your Develop Health contact.

## Receive the result

Wait for `benefit_verification.status_change` or use
[`GET /benefit-verification/{id}`](/api-reference/medication-benefit-check/get_item).
Completion time depends on the verification method and payer, including after
real-time fallback.
See [completion time](/api-reference/medication-benefit-check/overview#completion-time-and-verification-methods)
for typical timings by method and [response handling](/api-reference/medication-benefit-check/response-handling)
to determine when results are ready.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.