VeriFi API Documentation

The VeriFi Eligibility Verification API enables real-time insurance eligibility checks across 600+ PPO payers. One REST call returns structured eligibility data, plan details, and benefits breakdowns in under 500ms.

Quick Start

Create an account at /dashboard to register your application.
Get your API key from the dashboard under Settings → API Keys.
Make your first call using the example below.

Quick start

curl -X POST https://api.verifi.dev/api/v1/eligibility \
  -H "Authorization: Bearer vf_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "member_id": "TEST123456",
    "payer_code": "BCBS",
    "first_name": "Jane",
    "last_name": "Smith",
    "date_of_birth": "1985-03-15"
  }'

ⓘ

Use the TEST member ID prefix in test mode to receive simulated eligible responses without hitting real payer systems. See Test Mode for details.

Authentication

All authenticated endpoints require an API key. You can pass it in one of two ways:

Option 1: Authorization Header (Recommended)

Bearer token

Authorization: Bearer vf_live_your_api_key

Option 2: X-API-Key Header

X-API-Key header

X-API-Key: vf_live_your_api_key

API keys are prefixed with vf_live_ for production and vf_test_ for test mode. Keep your keys secret. Do not expose them in client-side code, public repositories, or browser requests.

⚠

Never share your API key. If you believe a key has been compromised, rotate it immediately from the Dashboard. Revoked keys return 401 Unauthorized within 60 seconds.

Base URL

All API requests should be made to:

Base URL

https://api.verifi.dev/api/v1

All requests must use HTTPS. HTTP requests will be rejected with a 301 redirect. TLS 1.2 or higher is required.

Rate Limits

Default rate limits apply to all API keys. If you need higher limits, contact us through the dashboard.

Limit	Default	Description
Per-minute	60 requests	Rolling 60-second window
Per-day	1,000 requests	Resets at midnight UTC

Rate Limit Headers

Every response includes headers to help you track your usage:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the current window
X-RateLimit-Remaining	Number of requests remaining in the current window
Retry-After	Seconds until the rate limit resets (only present on `429` responses)

Rate limit response (429)

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 23

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 23 seconds.",
    "retry_after": 23
  }
}

ⓘ

Implement exponential backoff when you receive a 429 response. Use the Retry-After header value as the minimum wait time before retrying.

Test Mode

Test mode lets you develop and test your integration without making real payer calls. Use special member_id prefixes to control the simulated outcome:

Prefix	Behavior	Example
TEST*	Always returns eligible with sample plan data	`TEST123456`
FAIL*	Always returns ineligible	`FAIL789012`
ERR*	Simulates a payer timeout (502 response)	`ERR345678`

Test mode requests do not count against your daily rate limit, but they do count against the per-minute limit. Test mode responses include "mode": "test" in the response body.

Test mode request

curl -X POST https://api.verifi.dev/api/v1/eligibility \
  -H "Authorization: Bearer vf_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "member_id": "TEST123456",
    "payer_code": "BCBS",
    "first_name": "Jane",
    "last_name": "Smith",
    "date_of_birth": "1985-03-15"
  }'

POST /api/v1/eligibility Auth Required

Run a real-time eligibility verification against a payer. Returns structured eligibility status, subscriber information, plan details, and benefits breakdown.

Request Body

Parameter	Type	Description
member_idrequired	string	The member/subscriber ID from the insurance card. In test mode, use `TEST`, `FAIL`, or `ERR*` prefixes.
payer_coderequired*	string	The VeriFi payer code (e.g., `BCBS`, `AETNA`, `UHC`). See GET /payers for the full list. *Either `payer_code` or `provider` is required.
providerrequired*	string	Alias for `payer_code`. Accepts the same values. *Either `payer_code` or `provider` is required.
first_namerequired	string	Subscriber's first name as it appears on the insurance card.
last_namerequired	string	Subscriber's last name as it appears on the insurance card.
date_of_birthrequired	string	Subscriber's date of birth in `YYYY-MM-DD` format.
service_typeoptional	string	Service type code for benefit-specific lookups (e.g., `30` for mental health, `47` for hospital). Defaults to `30` (general health benefit).
provider_npioptional	string	10-digit National Provider Identifier. When provided, the response includes network status for the given provider.

Example Request

curl

curl -X POST https://api.verifi.dev/api/v1/eligibility \
  -H "Authorization: Bearer vf_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "member_id": "XYZ123456789",
    "payer_code": "BCBS",
    "first_name": "Jane",
    "last_name": "Smith",
    "date_of_birth": "1985-03-15",
    "service_type": "30",
    "provider_npi": "1234567890"
  }'

Example Response

200 OK

{
  "request_id": "req_a1b2c3d4e5f6",
  "eligible": true,
  "status": "active",
  "transaction_id": "txn_98765432",
  "subscriber": {
    "first_name": "Jane",
    "last_name": "Smith",
    "member_id": "XYZ123456789",
    "date_of_birth": "1985-03-15",
    "relationship": "self"
  },
  "payer": {
    "code": "BCBS",
    "name": "Blue Cross Blue Shield",
    "payer_id": "00234"
  },
  "plan": {
    "name": "PPO Gold 1500",
    "type": "PPO",
    "group_number": "GRP-7890",
    "effective_date": "2025-01-01",
    "termination_date": null
  },
  "benefits": {
    "deductible": {
      "individual": 1500,
      "family": 3000,
      "remaining": 450.00
    },
    "out_of_pocket_max": {
      "individual": 6000,
      "family": 12000,
      "remaining": 4200.00
    },
    "copay": {
      "primary_care": 25,
      "specialist": 50,
      "emergency": 250
    },
    "coinsurance": {
      "in_network": 20,
      "out_of_network": 40
    }
  },
  "service_type": "30",
  "verification_date": "2026-04-28T14:30:00Z",
  "mode": "live",
  "response_time_ms": 342
}

Response Fields

Field	Type	Description
request_id	string	Unique identifier for this request. Use for support inquiries.
eligible	boolean	`true` if the member has active coverage, `false` otherwise.
status	string	Coverage status: `active`, `inactive`, `pending`, or `unknown`.
transaction_id	string	The EDI 271 transaction control number from the payer.
subscriber	object	Subscriber details as returned by the payer (name, member ID, DOB, relationship).
payer	object	Payer identification (code, name, payer_id).
plan	object	Plan details (name, type, group number, effective/termination dates).
benefits	object	Structured benefits: deductible, out-of-pocket max, copay, and coinsurance. Amounts in USD.
service_type	string	The service type code used for this verification.
verification_date	string	ISO 8601 timestamp of when the verification was performed.
mode	string	`live` for production verifications, `test` for test mode.
response_time_ms	number	Server-side response time in milliseconds.

Error Responses

400 Bad Request — Validation error

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": [
      { "field": "date_of_birth", "message": "Invalid format. Expected YYYY-MM-DD." },
      { "field": "payer_code", "message": "Required. Provide payer_code or provider." }
    ]
  }
}

401 Unauthorized — Invalid or missing API key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key. Check your Authorization header or X-API-Key."
  }
}

429 Too Many Requests — Rate limited

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 23 seconds.",
    "retry_after": 23
  }
}

500 Internal Server Error

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again.",
    "request_id": "req_a1b2c3d4e5f6"
  }
}

502 Bad Gateway — Payer unreachable

{
  "error": {
    "code": "payer_unavailable",
    "message": "The payer system is currently unavailable. Try again shortly.",
    "payer_code": "BCBS",
    "request_id": "req_a1b2c3d4e5f6"
  }
}

GET /api/v1/payers No Auth Required

Returns the full list of supported payer codes. This endpoint is public and does not require authentication. Use it to populate a payer dropdown in your UI or to validate payer codes before making eligibility requests.

Example Request

curl

curl https://api.verifi.dev/api/v1/payers

Example Response

200 OK

{
  "payers": [
    {
      "code": "AETNA",
      "name": "Aetna",
      "payer_id": "60054",
      "supported_transactions": ["270/271"],
      "status": "active"
    },
    {
      "code": "BCBS",
      "name": "Blue Cross Blue Shield",
      "payer_id": "00234",
      "supported_transactions": ["270/271"],
      "status": "active"
    },
    {
      "code": "CIGNA",
      "name": "Cigna Healthcare",
      "payer_id": "62308",
      "supported_transactions": ["270/271"],
      "status": "active"
    },
    {
      "code": "UHC",
      "name": "UnitedHealthcare",
      "payer_id": "87726",
      "supported_transactions": ["270/271"],
      "status": "active"
    }
  ],
  "total": 643
}

Response Fields

Field	Type	Description
payers	array	Array of payer objects.
payers[].code	string	The payer code to use in eligibility requests.
payers[].name	string	Human-readable payer name.
payers[].payer_id	string	X12 payer identifier.
payers[].status	string	`active` or `degraded`. Degraded payers may have slower response times.
total	number	Total number of supported payers.

GET /api/v1/verifications Auth Required

Returns a paginated list of your recent eligibility verifications. Useful for building verification history views, audit logs, and debugging past requests.

Query Parameters

Parameter	Type	Description
limitoptional	integer	Number of records to return. Default: `20`. Max: `100`.
offsetoptional	integer	Number of records to skip for pagination. Default: `0`.

Example Request

curl

curl "https://api.verifi.dev/api/v1/verifications?limit=5&offset=0" \
  -H "Authorization: Bearer vf_live_your_api_key"

Example Response

200 OK

{
  "verifications": [
    {
      "request_id": "req_a1b2c3d4e5f6",
      "eligible": true,
      "status": "active",
      "payer_code": "BCBS",
      "payer_name": "Blue Cross Blue Shield",
      "service_type": "30",
      "mode": "live",
      "response_time_ms": 342,
      "created_at": "2026-04-28T14:30:00Z"
    },
    {
      "request_id": "req_f6e5d4c3b2a1",
      "eligible": false,
      "status": "inactive",
      "payer_code": "AETNA",
      "payer_name": "Aetna",
      "service_type": "30",
      "mode": "live",
      "response_time_ms": 287,
      "created_at": "2026-04-28T13:15:00Z"
    }
  ],
  "total": 47,
  "limit": 5,
  "offset": 0
}

ⓘ

Verification records do not include full subscriber or benefits data. To retrieve the complete response for a past verification, use the request_id from this list. PHI fields are hashed in the history view.

GET /api/v1/usage Auth Required

Returns usage statistics for your API key, including request counts, rate limit status, and daily usage for the current billing period.

Example Request

curl

curl https://api.verifi.dev/api/v1/usage \
  -H "Authorization: Bearer vf_live_your_api_key"

Example Response

200 OK

{
  "api_key_id": "key_abc123",
  "plan": "starter",
  "rate_limits": {
    "per_minute": 60,
    "per_day": 1000
  },
  "usage": {
    "today": {
      "total_requests": 142,
      "successful": 138,
      "failed": 4,
      "remaining": 858
    },
    "this_month": {
      "total_requests": 3847,
      "successful": 3791,
      "failed": 56
    }
  },
  "current_minute": {
    "requests": 3,
    "remaining": 57
  }
}

Response Fields

Field	Type	Description
api_key_id	string	Your API key identifier (not the full key).
plan	string	Your current plan: `starter`, `professional`, or `enterprise`.
rate_limits	object	Your configured rate limits (per_minute, per_day).
usage.today	object	Today's request counts (total, successful, failed, remaining against daily limit).
usage.this_month	object	Current billing period totals (total, successful, failed).
current_minute	object	Requests in the current rolling 60-second window and remaining capacity.

Error Codes

All errors follow a consistent format. The top-level error object always includes a machine-readable code and a human-readable message. Some errors include additional context fields.

Error response format

{
  "error": {
    "code": "error_code_here",
    "message": "Human-readable description.",
    "request_id": "req_..."     // included when available
  }
}

HTTP Status Codes

Status	Code	Description	Action
400	`validation_error`	Request body failed validation. Check the `details` array for specific field errors.	Fix the request body and retry.
401	`unauthorized`	API key is missing, invalid, or revoked.	Check your API key in the Authorization header or X-API-Key header.
403	`forbidden`	API key does not have permission for this resource.	Check your plan limits or contact support.
404	`not_found`	The requested resource does not exist.	Check the URL path.
422	`unprocessable_entity`	The request was valid but the payer returned no matching subscriber.	Verify the member ID and subscriber details match the insurance card exactly.
429	`rate_limit_exceeded`	Too many requests. Check the `Retry-After` header.	Wait for the specified duration and retry with exponential backoff.
500	`internal_error`	An unexpected error occurred on our end.	Retry after a brief delay. If persistent, contact support with the `request_id`.
502	`payer_unavailable`	The payer's system is unreachable or timed out.	Retry after 30-60 seconds. Consider using cached results if available.
503	`service_unavailable`	VeriFi is temporarily unavailable for maintenance.	Retry after the time specified in the `Retry-After` header.

HIPAA Compliance

VeriFi is designed from the ground up for HIPAA-compliant healthcare data processing. Here is how we handle Protected Health Information (PHI):

Data Handling

PHI hashing: All personally identifiable fields (member_id, first_name, last_name, date_of_birth) are hashed using SHA-256 before storage. The original plaintext values are used only for the real-time payer transaction and are never persisted.
No plaintext storage: VeriFi does not store plaintext PHI in any database, log file, or cache. Verification history records contain only hashed identifiers and structured response data.
TLS required: All API traffic must use HTTPS with TLS 1.2 or higher. HTTP requests are rejected, not redirected. This ensures PHI is encrypted in transit.
Encryption at rest: All stored data is encrypted at rest using AES-256-GCM.

Audit Logging

Every API request is logged with a unique request_id, timestamp, API key identifier, and response status.
Audit logs are immutable and retained for 7 years per HIPAA requirements.
Logs never contain plaintext PHI. All patient identifiers in logs are SHA-256 hashed.

Access Controls

API keys are scoped per-application. Each key has independent rate limits and access logs.
Key rotation is available in the dashboard. Revoked keys become invalid within 60 seconds.
There is no cross-account data access. Each API key can only retrieve its own verification history.

✓

BAA Available. VeriFi offers Business Associate Agreements for all plans. Contact us through the Dashboard to request a BAA before transmitting real patient data.

⚠

Do not log full API responses containing PHI in your own systems. If you store eligibility results, hash or redact subscriber names and member IDs. You are responsible for HIPAA compliance within your own application.