Endpoints
Postman API documentation is available at https://api.docs.verified.inc.
Please do all development work and testing against our Sandbox environment, which returns mock data. You can use our Production environment when you're ready to go live.
Client SDK
POST /client/1-click
Create a (one time use) session key for the client SDK
| Method | POST |
|---|---|
| Path | /client/1-click |
This endpoint is only relevant if you're using the SDK integration type.
Request
{
verificationUuid?: string,
phone?: string,
email?: string,
birthDate?: string,
ssn4?: string,
fullName?: {
firstName?: string,
middleName?: string,
lastName?: string
},
address?: {
line1?: string,
line2?: string,
city?: string,
state?: string,
zipCode?: string,
country?: string
}
}
| Property | Required? | Type | Format | Default | Description | Example |
|---|---|---|---|---|---|---|
verificationUuid | Optional | string | Version 4 UUID | - | Unique identifier for a 1ClickVerificationEntity that can be passed to the SDK to skip the phone entry and verification steps | "487246b0-e68c-451d-be8e-45cea0b1c7a2" |
phone | Optional | string | E.164 | - | User's phone number (in E.164 format) | "+12125550010" |
email | Optional | string | - | User's email address | "richard@piedpiper.net" | |
birthDate | Optional | string | yyyy-MM-dd | - | User's birth date (in Sandbox, this must be "1989-08-01" to pass validation) | "1989-08-01" |
ssn4 | Optional | string | 4 digits (0-9) | - | Last 4 digits of user's Social Security Number (in Sandbox, this must be "6789" to pass validation) | "6789" |
fullName | Optional | object | Object with keys for one or more child credentials listed below | - | Full name | |
↳ fullName.firstName | Optional but Required with fullName | string | cAse inSensiTive | - | First name | "Richard" |
↳ fullName.middleName | Optional | string | cAse inSensiTive | - | Middle name | "Harrison" |
↳ fullName.lastName | Optional | string | cAse inSensiTive | - | Last name | "Hendricks" |
address | Optional | object | Object with keys for one or more child credentials listed below | - | Address | |
↳ address.line1 | Optional | string | cAse inSensiTive | - | Line 1 of address | "5320 Newell Rd" |
↳ address.line2 | Optional | string | cAse inSensiTive | - | Line 2 of address | "" |
↳ address.city | Optional | string | cAse inSensiTive | - | City of address | "Palo Alto" |
↳ address.state | Optional | string |
| - | State of address |
|
↳ address.zipCode | Optional | string | - | ZIP Code of address |
| |
↳ address.country | Optional | string |
| - | Country of address |
|
If you don't have a user's phone number yet, call POST /client/1-click with an empty request body, and the SDK will prompt the user to enter their phone number.
Response
{
sessionKey: string
}
| Property | Type | Format | Description | Example |
|---|---|---|---|---|
sessionKey | string | Version 4 UUID | Session key that can be used (one time only) to initialize the SDK | "86227634-bd2e-479d-9541-2c8e7e2e1f6d" |
1-Click Verify
GET /1-click/verifications/device-ip
Get the IP address of a user's device
| Method | GET |
|---|---|
| Path | /1-click/verifications/device-ip |
Request
Call:
GET /1-click/verifications/device-ip
client side, from the user's device.
Unlike most Verified API endpoints, this is a public, unauthenticated endpoint. (Don't use your Verified API key, which you must only use server side.)
You should call this endpoint from the user's device, NOT your server, so that it returns the user's device IP address, which you can use with other endpoints.
Response
{
deviceIp: string
}
| Property | Type | Format | Description | Example |
|---|---|---|---|---|
deviceIp | string | IPv6 address | The IP address of the user's device | ::121:2555:0010 |
GET /1-click/verifications/channels
Check the availability of 1-Click Verify channels
| Method | GET |
|---|---|
| Path | /1-click/verifications/channels?deviceIp={deviceIp} |
Request
Call:
GET /1-click/verifications/channels?deviceIp={deviceIp}
- For the
{deviceIp}query parameter value:- Use the IP address of the user's device returned by
GET /1-click/verifications/device-ip.
- Use the IP address of the user's device returned by
Response
{
channels: {
autofill: {
available: boolean, // = brandApproved && deviceIpEligible
brandApproved: boolean,
deviceIpEligible: boolean
},
silent: {
available: boolean, // = brandApproved && deviceIpEligible
brandApproved: boolean,
deviceIpEligible: boolean
},
sms: {
available: boolean, // = brandApproved, currently
brandApproved: boolean
},
// Coming soon
// email: {
// available: boolean, // = brandApproved, currently
// brandApproved: boolean
// }
}
}
| Property | Type | Format | Description | Example |
|---|---|---|---|---|
channels | object | Object with keys for all channels | Availability for all channels | - |
channels.autofill | object | Object with keys for autofill channel | Availability for the autofill channel | |
channels.autofill.available | boolean | - | Whether the autofill channel is available (= brandApproved && deviceIpEligible) | true |
channels.autofill.brandApproved | boolean | - | Whether your brand is approved for the autofill channel | true |
channels.autofill.deviceIpEligible | boolean | - | Whether the user's device IP is eligible for the autofill channel | true |
channels.sms | object | Object with keys for SMS channel | Availability for the SMS channel | |
channels.sms.available | boolean | - | Whether the SMS channel is available | true |
channels.email | object | Object with keys for email channel | Availability for the email channel | |
channels.email.available | boolean | - | Whether the email channel is available | true |
POST /1-click/verifications
Begin a verification flow
| Method | POST |
|---|---|
| Path | /1-click/verifications |
Request
{
channel: "autofill" | "silent" | "sms", // email coming soon
deviceIp?: string, // required for autofill and silent channels
phone?: string // required for silent and SMS channels, or if wanting to match user input to autofill output
}
| Property | Required? | Type | Format | Default | Description | Example |
|---|---|---|---|---|---|---|
channel | Required |
| snake_case | - | Channel used for verification | "autofill" |
deviceIp | Optional but Required if channel is "autofill" or "silent" | string | IPv6 address | - | IP address of user's device | "::121:2555:0010" |
phone | Optional but Required if channel is "silent" or "sms" | string | E.164 | - | User's phone number (in E.164 format) | "+12125550010" |
Response
When channel is set to autofill or silent, the response will be an HTTP 302 redirect and a Location header with a URL value. You should pass this URL to your client, on the user's device, and handle it as described in the 1-Click Verify API Integration guide, for autofill and for silent. The end result will be as shown below.
Then channel is set to sms, the response body is directly as shown below.
{
...1ClickVerificationEntity // includes phone and verified status if autofill succeeds (and matches phone input if provided)
}
Here's an example with a verified status from the autofill channel:
{
"uuid": "6232bdb2-5b92-405a-bf39-6147aef70ac1",
"phone": "+12125550010",
"channel": "autofill",
"status": "verified",
"verified": true,
"createdAt": 1760053690000,
"expiresAt": 1760053990000,
"attemptsRemaining": 3
}
Here's an example with a pending status from the SMS channel:
{
"uuid": "f5251850-496c-48cf-a4bd-d9d5ace22689",
"phone": "+12125550010",
"channel": "sms",
"format": "linkAndCode",
"status": "pending",
"verified": false,
"createdAt": 1760053695000,
"expiresAt": 1760053995000,
"attemptsRemaining": 3
}
POST /1-click/verifications/{uuid}/deliver
Deliver a verification message
| Method | POST |
|---|---|
| Path | /1-click/verifications/{uuid}/deliver |
Request
{
format?: "code" | "link" | "codeAndLink" | "linkAndCode", // defaults to code
redirectUrl?: string, // only relevant if link format is included
redirectUserAfter?: "phoneVerification" | "infoConfirmation" // only relevant if link format is included
}
- For the
{uuid}path parameter, use the value of theuuidincluded in the1ClickVerificationEntitythat's included in the response body of every 1-Click Verify endpoint.
| Property | Required? | Type | Format | Default | Description | Example |
|---|---|---|---|---|---|---|
format | Optional |
| camelCase | "code" | Format used for verification message (see Verification SMS Formats below) | "linkAndCode" |
redirectUrl | Optional | string | URL | Defined by the redirect URL brand setting in the Dashboard | Where 1-Click Verify redirects a user to (only relevant if link format is included) | "https://hooli.com/verified/1-click/verify" |
redirectUserAfter | Optional |
| camelCase | Defined by the redirect user after brand setting in the Dashboard | When a user is redirected to the redirect URL (only relevant if link format is included) | "phoneVerification" |
The content of the verification SMS depends on the format:
| Format | format | SMS Template | SMS Example |
|---|---|---|---|
| Code Default | code |
|
|
| Link | link |
|
|
| Code and Link | codeAndLink |
|
|
| Link and Code | linkAndCode |
|
|
Response
{
...1ClickVerificationEntity
}
See 1ClickVerificationEntity. Here's an example:
{
"uuid": "f5251850-496c-48cf-a4bd-d9d5ace22689",
"phone": "+12125550010",
"channel": "sms",
"format": "linkAndCode",
"status": "sending",
"verified": false,
"createdAt": 1760053695000,
"expiresAt": 1760053995000,
"attemptsRemaining": 3
}
POST /1-click/verifications/{uuid}/verify
Verify a user submitted verification code
| Method | POST |
|---|---|
| Path | /1-click/verifications/{uuid}/verify |
Request
{
code: string
}
- For the
{uuid}path parameter, use the value of theuuidincluded in the1ClickVerificationEntitythat's included in the response body of every 1-Click Verify endpoint.
| Property | Required? | Type | Format | Default | Description | Example |
|---|---|---|---|---|---|---|
code | Required | string | 6 digits (0-9) | - | User submitted verification code | "111111" |
Response
{
...1ClickVerificationEntity
}
See 1ClickVerificationEntity. Here's an example:
{
"uuid": "f5251850-496c-48cf-a4bd-d9d5ace22689",
"phone": "+12125550010",
"channel": "sms",
"format": "linkAndCode",
"status": "verified",
"verified": true,
"createdAt": 1760053695000,
"expiresAt": 1760053995000,
"deliveredAt": 1760053699054,
"verifiedAt": 1760053705000,
"attemptsRemaining": 2
}
GET /1-click/verifications/{uuid}
Check the status of a verification flow
| Method | GET |
|---|---|
| Path | /1-click/verifications/{uuid} |
Request
Call:
GET /1-click/verifications/{uuid}
- For the
{uuid}path parameter:- If the user comes from a redirect, use the value of the
verificationUuidincluded as a URL parameter on the redirect URL. - Otherwise, use the value of the
uuidincluded in the1ClickVerificationEntitythat's included in the response body of a relevant 1-Click Verify endpoint.
- If the user comes from a redirect, use the value of the
Response
{
...1ClickVerificationEntity
}
See 1ClickVerificationEntity. Here's an example:
{
"uuid": "f5251850-496c-48cf-a4bd-d9d5ace22689",
"phone": "+12125550010",
"channel": "sms",
"format": "link",
"status": "verified",
"createdAt": 1760053695000,
"expiresAt": 1760053995000,
"verifiedAt": 1760053705000
}
1-Click Signup
POST /1-click
Begin a 1-Click Signup flow
| Method | POST |
|---|---|
| Path | /1-click |
This endpoint is only relevant if you're using the API integration type.
Request
{
identityUuid?: string,
verificationUuid?: string,
phone?: string,
email?: string,
deviceIp?: string,
birthDate?: string,
ssn4?: string,
fullName?: {
firstName?: string,
middleName?: string,
lastName?: string
},
address?: {
line1?: string,
line2?: string,
city?: string,
state?: string,
zipCode?: string,
country?: string
},
credentialRequests?: CredentialRequest[]
}
| Property | Required? | Type | Format | Default | Description | Example |
|---|---|---|---|---|---|---|
identityUuid | Optional | string | Version 4 UUID | - | Unique identifier for a 1ClickEntity that can be passed to hydrate data from an existing 1-Click Signup flow | "7a57b225-7abb-499d-9b74-0934d15bc826" |
verificationUuid | Optional but Required if phone is not included | string | Version 4 UUID | - | Unique identifier for a 1ClickVerificationEntity that can be passed to hydrate a verified phone number | "487246b0-e68c-451d-be8e-45cea0b1c7a2" |
phone | Optional but Required if verificationUuid is not included | string | E.164 | - | User's phone number (in E.164 format) | "+12125550010" |
email | Optional | string | - | User's email address | "richard@piedpiper.net" | |
deviceIp | Optional | string | IPv6 address | - | IP address of user's device (which you can get using GET /1-click/verifications/device-ip) | "::121:2555:0010" |
birthDate | Optional | string | yyyy-MM-dd | - | Birth date | "1989-08-01" |
ssn4 | Optional | string | 4 digits (0-9) | - | Last 4 digits of Social Security Number | "6789" |
fullName | Optional | object | Object with keys for one or more child credentials listed below | - | Full name | |
↳ fullName.firstName | Optional | string | cAse inSensiTive | - | First name | "Richard" |
↳ fullName.middleName | Optional | string | cAse inSensiTive | - | Middle name | "Harrison" |
↳ fullName.lastName | Optional | string | cAse inSensiTive | - | Last name | "Hendricks" |
address | Optional | object | Object with keys for one or more child credentials listed below | - | Address | |
↳ address.line1 | Optional | string | cAse inSensiTive | - | Line 1 of address | "5320 Newell Rd" |
↳ address.line2 | Optional | string | cAse inSensiTive | - | Line 2 of address | "" |
↳ address.city | Optional | string | cAse inSensiTive | - | City of address | "Palo Alto" |
↳ address.state | Optional | string |
| - | State of address |
|
↳ address.zipCode | Optional | string | - | ZIP Code of address |
| |
↳ address.country | Optional | string |
| - | Country of address |
|
credentialRequests | Optional | CredentialRequest[] | See CredentialRequest | Defined by the default credential requests brand setting in the Dashboard | List of CredentialRequest objects (which encode which credentials you're asking for): an empty array tells us to source only metadata, no credentials | See CredentialRequest example |
Default Credential Requests
If you don't include credentialRequests in the request body, the default credential requests setting for your brand will apply. For reference, the standard credential requests (see here in the Setup guide) include the core KYC data points, all set to optional:
Standard Credential Requests in Code
[
{
"type": "FullNameCredential",
"children": [
{
"type": "FirstNameCredential"
},
{
"type": "MiddleNameCredential"
},
{
"type": "LastNameCredential"
}
]
},
{
"type": "PhoneCredential"
},
{
"type": "AddressCredential",
"multi": true,
"children": [
{
"type": "Line1Credential"
},
{
"type": "Line2Credential"
},
{
"type": "CityCredential"
},
{
"type": "StateCredential"
},
{
"type": "ZipCodeCredential"
},
{
"type": "CountryCredential"
}
]
},
{
"type": "BirthDateCredential",
},
{
"type": "SsnCredential",
}
]
If you pass an empty array for credentialRequests, we'll source only metadata, not any credentials. This is how you can source metadata only, if that's relevant for your use case. You can do this without verifying the user's phone number, though you must verify their phone number before sourcing any credentials.
Response
{
uuid: string,
identity: 1ClickEntity
}
| Property | Type | Format | Description | Example |
|---|---|---|---|---|
uuid | string | Version 4 UUID | Unique identifier for the 1ClickEntity that will be returned at the end of the 1-Click Signup flow | "535dba63-d4bd-442a-b3f6-21b785260a08" |
identity | 1ClickEntity | See 1ClickEntity | A 1ClickEntity object, which contains the user's verified data and metadata about it | See 1ClickEntity example |
GET /1-click
Get data for a user who has completed a 1-Click Signup flow
| Method | GET |
|---|---|
| Path | /1-click/{identityUuid} |
Request
Call:
GET /1-click/{identityUuid}
- For the
{identityUuid}path parameter, use the value of theidentityUuidreturned by the SDK or included as a URL parameter on the redirect URL.
Response
{
...1ClickEntity
}
See 1ClickEntity.
1-Click Health
POST /1-click/health
Begin a 1-Click Health flow (for autofill, check, or both)
| Method | POST |
|---|---|
| Path | /1-click/health |
This endpoint is only relevant if you're using the API integration type.
Request
{
checkAfterAutofill?: boolean, // default defined by the Check After Autofill brand setting in the Verified Dashboard
provider?: {
npi: string // default defined by the Providers brand setting in the Verified Dashboard
},
identityUuid?: string, // from 1-Click Signup response body
externalReference?: string, // optional: your own reference string, to be included in responses
fullName?: {
firstName?: string, // required if no identityUuid
middleName?: string,
lastName?: string // required if no identityUuid
},
birthDate?: string, // required if no identityUuid
address?: {
line1?: string,
line2?: string,
city?: string,
state?: string,
zipCode?: string,
country?: string
},
sex?: string,
ssn?: string,
payer?: {
id?: string, // specifies payer (or payer group)
name?: string, // searches for payer (or payer group): only use if id is not known
},
memberId?: string,
serviceCodes?: {
serviceTypeCodes?: string[],
procedureCodes?: {
code: string,
qualifier?: string,
modifiers?: string[]
}[]
}
}
| Property | Required? | Type | Format | Default | Description | Example |
|---|---|---|---|---|---|---|
checkAfterAutofill | Optional | boolean | - | Defined by the Check After Autofill setting | Whether to automatically run an eligibility check for an autofilled health insurance plan | true |
provider | Optional | object | Object with key listed below | - | Provider information | |
↳ provider.npi | Required (if provider object is included) | string | 10 digits (0-9) | Defined by Providers setting | National Provider Identifier | "0123456789" |
identityUuid | Optional | string | Version 4 UUID | - | Unique identifier for the 1ClickEntity that will be returned at the end of the 1-Click Signup flow | "535dba63-d4bd-442a-b3f6-21b785260a08" |
externalReference | Optional | string | 1–256 characters | - | Your own reference string, echoed from POST /1-click/health request body if included | "appointment-1042" |
fullName | Optional but Required if no identityUuid | object | Object with keys for one or more child credentials listed below | - | Full name | |
↳ fullName.firstName | Optional but Required if no identityUuid | string | cAse inSensiTive | - | First name | "Richard" |
↳ fullName.middleName | Optional | string | cAse inSensiTive | - | Middle name | "Harrison" |
↳ fullName.lastName | Optional but Required if no identityUuid | string | cAse inSensiTive | - | Last name | "Hendricks" |
birthDate | Optional but Required if no identityUuid | string | yyyy-MM-dd | - | Birth date | "1989-08-01" |
address | Optional | object | Object with keys for one or more child credentials listed below | - | Address | |
↳ address.line1 | Optional | string | cAse inSensiTive | - | Line 1 of address | "5320 Newell Rd" |
↳ address.line2 | Optional | string | cAse inSensiTive | - | Line 2 of address | "" |
↳ address.city | Optional | string | cAse inSensiTive | - | City of address | "Palo Alto" |
↳ address.state | Optional | string | 2 letter abbreviation (last 2 characters of ISO 3166-2 code for US state/territory) | - | State of address | "CA" |
↳ address.zipCode | Optional | string | ZIP Code (5 digits, 0-9) | - | ZIP Code of address | "94303" |
↳ address.country | Optional | string | 2 letter abbreviation (ISO 3166-1 alpha-2 code, currently always "US") | - | Country of address | "US" |
sex | Optional |
| Title Case | - | Sex | "Male" |
ssn | Optional | string | 9 digits (0-9) | - | Social Security Number | "000456789" |
payer | Optional | object | Object with key described below | - | Payer (or payer group) for insurance autofill and/or eligibility check | - |
↳ payer.id | Optional | string | - | - | Payer (or payer group) ID for insurance autofill and/or eligibility check: see supported payers | "VERIFIED_MEDICARE" |
↳ payer.name | Optional | string | - | - | Payer (or payer group) name for insurance autofill and/or eligibility check: see supported payers (only use if payer ID is not known) | "Aetna" |
memberId | Optional | string | - | - | Member ID for eligibility check | "A484069" |
serviceCodes | Optional | object | Object with key described below | - | Service codes for autofill and/or check | - |
↳ serviceTypeCodes | Optional | string[] | Array of strings | ["30"] | List of X12 service type codes for patient service | ["47", "AL", "F6"] |
↳ procedureCodes | Optional | object[] | Array of objects | "30" | National Provider Identifier | |
↳ ↳ procedureCodes[i] | Optional | object | Object with keys described below | - | National Provider Identifier | |
↳ ↳ ↳ procedureCodes[i].code | Required (if procedureCodes object is included) | string |
| - | CPT or HCPCS procedure code | "99213"" |
↳ ↳ ↳ procedureCodes[i].qualifier | Optional |
| 2 letters | "HC" | Type or source of procedure code | "HC" |
↳ ↳ ↳ procedureCodes[i].modifiers | Optional | string[] | Array of strings | - | Array of medical coding modifiers | ["25"] |
Response
{
healthDataUuid: string,
externalReference?: string, // your own reference string, included if passed to POST /1-click/health
status: "PENDING" | "PROCESSING" | "SUCCEEDED" | "FAILED" | "PARTIAL"
}
| Property | Type | Format | Description | Example |
|---|---|---|---|---|
healthDataUuid | string | Version 4 UUID | Unique identifier for the 1ClickHealthEntity that will be returned at the end of the 1-Click Health flow | "9e12fe5b-5bb8-410a-ac6b-6e053e4c7e8d" |
externalReference | string | 1–256 characters | Your own reference string, echoed from POST /1-click/health request body if included | "appointment-1042" |
status |
| UPPER_SNAKE_CASE | Status of the 1-Click Health flow | "PROCESSING" |
GET /1-click/health
Get data for a user who has completed a 1-Click Health flow
| Method | GET |
|---|---|
| Path | /1-click/health/{healthDataUuid} |
Request
Call:
GET /1-click/health/{healthDataUuid}
- For the
{healthDataUuid}path parameter, use the value of thehealthDataUuidreturned by the SDK orPOST /1-click/health.
Response
{
...1ClickHealthEntity
}
See 1ClickHealthEntity.
GET /1-click/health/payers
Get all supported payers for 1-Click Health
| Method | GET |
|---|---|
| Path | /1-click/health/payers |
Request
Call:
GET /1-click/health/payers
You can optionally include query parameters, for example:
GET /1-click/health/payers?$search=aetna&$limit=10&$skip=0&$paginate=true
| Parameter | Required? | Type | Format | Default | Description | Example |
|---|---|---|---|---|---|---|
$search | Optional | string | - | - | Search by payer name or ID | aetna |
$limit | Optional | integer | - | 10 | Number of payers per page | 100 |
$skip | Optional | integer | - | 0 | Number of payers to skip | 25 |
$paginate | Optional | boolean | - | - | Whether to return paginated results | true |
This endpoint is unauthenticated.
Response
Without query parameters, the response body will be unpaginated:
[
...Payer
]
See Payer. This includes all supported payers.
With query parameters, the response body will be paginated:
{
total: integer,
limit: integer,
skip: integer,
data: [
...Payer
],
}
This includes (under data) an array of payer objects for all supported payers that match the query, with keys as described in the table below.
| Property | Type | Format | Description | Example |
|---|---|---|---|---|
total | integer | - | Number of payers | 3460 |
limit | integer | - | Number of payers per page | 100 |
skip | integer | - | Number of payers to skip | 25 |
data | Payer[] | Array of Payers | Payers that match submitted query | - |
data[i] | Payer | See Payer | Payer | See Payer Example |
Settings
These endpoints allow you to manage your settings programmatically (rather than manually through the Dashboard). Settings are defined within an environment, so to configure them in both Sandbox and Production, you need to use the appropriate API key and base URL for each environment.
The path pattern is /settings/{scope}/{product}/{resource}.
Currently, we support the brand scope, health product (for 1-Click Health), and network-rules resource.
Network Rules
Manage the network rules that produce the
networkobjects (ofNetworkDecisiontype) in 1-Click Health results
These endpoints are equivalent to the Network Rules section of the Dashboard: a rule written here and a rule written there are indistinguishable, and the same validation applies to both.
You can keep your payer network mapping (and anything you attach to it in metadata, such as an internal package or plan ID) in your own system and use these endpoints to update the network rules whenever anything changes.
| Method | Path | Description |
|---|---|---|
GET | /settings/brand/health/network-rules | List your brand's network rules |
GET | /settings/brand/health/network-rules/{uuid} | Retrieve one network rule |
POST | /settings/brand/health/network-rules | Create one network rule, or several at once |
POST | /settings/brand/health/network-rules/replace | Replace all of your brand's network rules in one call |
PATCH | /settings/brand/health/network-rules/{uuid} | Update a network rule |
DELETE | /settings/brand/health/network-rules/{uuid} | Delete a network rule |
Rule Object
Every endpoint returns network rules as NetworkRule objects with four additional properties that only the Network Rules endpoints expose:
| Property | Type | Format | Description | Example |
|---|---|---|---|---|
number | integer | Positive integer | Per-brand sequence number in creation order. Assigned by Verified, never changes, never reused. Used for the default name ("Rule 7") | 7 |
enabled | boolean | - | Whether the rule is applied. A disabled rule is stored but never matches | true |
createdAt | integer | Unix epoch, milliseconds | When the rule was created | 1790000000000 |
updatedAt | integer | Unix epoch, milliseconds | When the rule was last updated | 1790000000000 |
Rule Body
POST(create) andPOST .../replacetake rule bodies.PATCHtakes any subset of the same properties.uuid,number,createdAtandupdatedAtare assigned by Verified and are rejected if sent.
| Property | Required? | Type | Format | Default | Description | Example |
|---|---|---|---|---|---|---|
status | Required | enum | "IN_NETWORK" | "OUT_OF_NETWORK" | "INDETERMINATE" | - | Network status the rule returns when it matches a health insurance plan | "IN_NETWORK" |
conditions | Required | object[] | At least one condition; see Conditions | - | Conditions that must all hold (AND) for the rule to match | See Conditions |
name | Optional | string | Non-empty | "Rule {number}" | Name for the rule | "Aetna PPO - INN" |
notes | Optional | string | null | - | null | Free text, returned with the decision so your app can branch on it | "No self pay" |
metadata | Optional | object | Flat object of up to 20 entries; keys up to 64 characters; values string (up to 200 characters), number or boolean | {} | Your own key/value pairs, returned with the decision as network.rules[i].metadata. On PATCH, replaces the whole object | |
enabled | Optional | boolean | - | true | Whether the rule is applied | true |
startDate | Optional | string | null | yyyy-MM-dd | null | Date the rule starts applying (at start of day, UTC, inclusive) | "2026-10-01" |
endDate | Optional | string | null | yyyy-MM-dd, after startDate | null | Date the rule stops applying (at start of day, UTC, exclusive) | "2027-10-01" |
Conditions
- A condition is
{ key, operator, values }. valuesis a non-empty array of strings, and several values amount to an inclusive OR. For example,{ state EQUAL ["MN", "CA"] }matches either Minnesota or California.- All conditions of a rule must hold. When several rules match a plan, the most specific one wins.
key | Type | Allowed operators | Allowed values | Example |
|---|---|---|---|---|
payerId | enum | EQUAL, NOT_EQUAL | Verified payer IDs or payer group IDs from GET /1-click/health/payers. A payer group (for example Verified Blues) matches every payer in the group | ["V404110"] |
payerName | text | EQUAL, NOT_EQUAL, INCLUDE, NOT_INCLUDE | Any text. INCLUDE is a case-insensitive substring match | ["Aetna"] |
state | enum | EQUAL, NOT_EQUAL | Two-letter US state or territory codes (the patient's address state) | ["MA", "NY", "WA"] |
insuranceTypeCodes | enum | INCLUDE, NOT_INCLUDE | X12 EB04 insurance type codes (listed below), plus "NONE" meaning the eligibility response carried no code. About 7 in 10 plans carry none, so INCLUDE ["PR", "NONE"] reads "PPO, or unknown" | ["PR", "PS"] |
planName | text | EQUAL, NOT_EQUAL, INCLUDE, NOT_INCLUDE | Any text | ["PPO"] |
relatedEntities | text | EQUAL, NOT_EQUAL, INCLUDE, NOT_INCLUDE | Any text (names of related entities on the eligibility response, for example a PBM or TPA) | ["OPTUMRX"] |
groupNumber | text | EQUAL, NOT_EQUAL, INCLUDE, NOT_INCLUDE | Any text | ["123456-123-12345"] |
groupName | text | EQUAL, NOT_EQUAL, INCLUDE, NOT_INCLUDE | Any text | ["Pied Piper"] |
Rules describe plans, not people. A text value that looks like a member ID (optional letters followed by six or more digits) or a date is rejected with the PHI_SUSPECTED error code. groupNumber is exempt from the member ID check, since group numbers legitimately look like one.
Insurance type codes (insuranceTypeCodes values)
| Code | Meaning |
|---|---|
NONE | No insurance type code on the eligibility response |
12 | Medicare Secondary Working Aged Beneficiary or Spouse with Employer Group Health Plan |
13 | Medicare Secondary End-Stage Renal Disease Beneficiary in the Mandated Coordination Period |
14 | Medicare Secondary, No-fault Insurance including Auto is Primary |
15 | Medicare Secondary Worker's Compensation |
16 | Medicare Secondary Public Health Service (PHS) or Other Federal Agency |
41 | Medicare Secondary Black Lung |
42 | Medicare Secondary Veteran's Administration |
43 | Medicare Secondary Disabled Beneficiary Under Age 65 with Large Group Health Plan (LGHP) |
47 | Medicare Secondary, Other Liability Insurance is Primary |
AP | Auto Insurance Policy |
C1 | Commercial |
CO | COBRA |
CP | Medicare Conditionally Primary |
D | Disability |
DB | Disability Benefits |
EP | Exclusive Provider Organization (EPO) |
FF | Family or Friends |
GP | Group Policy |
HM | Health Maintenance Organization (HMO) |
HN | HMO - Medicare Risk (Medicare Advantage) |
HS | Special Low Income Medicare Beneficiary |
IN | Indemnity |
IP | Individual Policy |
LC | Long Term Care |
LD | Long Term Policy |
LI | Life Insurance |
LT | Litigation |
MA | Medicare Part A |
MB | Medicare Part B |
MC | Medicaid |
MH | Medigap Part A |
MI | Medigap Part B |
MP | Medicare Primary |
OT | Other |
PE | Property Insurance - Personal |
PL | Personal |
PP | Personal Payment (Cash - No Insurance) |
PR | Preferred Provider Organization (PPO) |
PS | Point of Service (POS) |
QM | Qualified Medicare Beneficiary |
RP | Property Insurance - Real |
SP | Supplemental Policy |
TF | Tax Equity Fiscal Responsibility Act (TEFRA) |
WC | Workers Compensation |
WU | Wrap Up Policy |
Errors
| Status | name | When |
|---|---|---|
400 | BadRequest | The body or query has the wrong shape (message: "validation failed"), or a rule is invalid: message is "Invalid network rule" (or "Invalid network rules" for a batch) and data.errors lists every problem, see below |
401 | NotAuthenticated | Missing or invalid API key, or a key blocked by an IP allowlist |
403 | Forbidden | 1-Click Health is not contracted or is disabled for the brand |
404 | NotFound | No rule with that uuid belongs to your brand |
- Each entry of
data.errorshas a stablecode, a human-readablemessage, and (when it concerns one condition) the condition'sindexplus itskey,operatorand offendingvalue(s). - For a batch (an array sent to
POST) or areplace, each entry also hasruleIndex, the position of the rule in the array you sent. - Every problem is reported at once, so one request tells you everything to fix.
code | Meaning |
|---|---|
UNKNOWN_KEY | key is not one of the condition keys above |
OPERATOR_NOT_ALLOWED_FOR_KEY | operator is not allowed for that key (for example INCLUDE on state) |
VALUE_SHAPE | values is not a non-empty array of non-empty strings |
UNKNOWN_ENUM_VALUE | A value is not a known payer ID, state code or insurance type code |
PHI_SUSPECTED | A text value looks like a member ID or a date |
DUPLICATE_CONDITIONS | Another rule of your brand (its uuid is in value), or another rule in the same request, has exactly these conditions |
DATE_RANGE_INVERTED | startDate is not before endDate |
METADATA_INVALID | metadata exceeds the limits above |
{
"name": "BadRequest",
"message": "Invalid network rule",
"code": 400,
"className": "bad-request",
"data": {
"errors": [
{
"code": "UNKNOWN_ENUM_VALUE",
"index": 1,
"key": "insuranceTypeCodes",
"operator": "INCLUDE",
"value": ["XX"],
"message": "Unknown value(s) for \"insuranceTypeCodes\": XX"
}
]
}
}
GET /settings/brand/health/network-rules
List your brand's network rules
| Method | GET |
|---|---|
| Path | /settings/brand/health/network-rules |
Request
Call:
GET /settings/brand/health/network-rules
You can optionally include query parameters, for example:
GET /settings/brand/health/network-rules?status=IN_NETWORK&metadata[key]=packageId&$limit=50
| Parameter | Required? | Type | Format | Default | Description | Example |
|---|---|---|---|---|---|---|
$limit | Optional | integer | 1 to 100 | 10 | Number of rules per page | 50 |
$skip | Optional | integer | - | 0 | Number of rules to skip | 50 |
$sort[field] | Optional | 1 | -1 | field is number, name, status, enabled, createdAt or updatedAt | createdAt ascending, then number | Sort order | $sort[updatedAt]=-1 |
uuid,number,name,status,enabled,createdAt,updatedAt | Optional | - | Exact value, or an operator object: $in, $nin, $ne, $lt, $lte, $gt, $gte | - | Filter on a rule property | status=OUT_OF_NETWORK, updatedAt[$gt]=1790000000000 |
search | Optional | string | 1 to 120 characters | - | Case-insensitive substring over name and notes | search=self%20pay |
condition[key] | Optional | string | string[] | Condition key(s) | - | Rules that have a condition on any of these keys | condition[key]=state |
condition[payerId],condition[state],condition[insuranceTypeCodes] | Optional | string | string[] | One code or several | - | Rules whose condition on that key includes the code (exact match) | condition[payerId]=V404110 |
condition[payerName],condition[planName],condition[relatedEntities],condition[groupNumber],condition[groupName] | Optional | object | { value, operator? } with operator one of contains (default), equals, startsWith, endsWith | - | Rules whose condition on that key matches the text | condition[planName][value]=PPO |
metadata[key] | Optional | string | string[] | Metadata key(s) | - | Rules whose metadata has any of these keys | metadata[key]=packageId |
metadata[value] | Optional | object | { key, value, operator? }, same text operators as above | - | Rules whose metadata[key] matches the text | metadata[value][key]=packageId&metadata[value][value]=4471 |
All filters combine with AND.
Response
{
total: integer,
limit: integer,
skip: integer,
data: [
...NetworkRule // with number, enabled, createdAt, updatedAt
],
}
data holds the rules that match the query, oldest first unless sorted otherwise, each as described under Rule Object.
GET /settings/brand/health/network-rules/{uuid}
Retrieve one network rule
| Method | GET |
|---|---|
| Path | /settings/brand/health/network-rules/{uuid} |
Request
Call:
GET /settings/brand/health/network-rules/ab280ee0-5f66-4076-9d1b-255d5f0024e3
Response
200 with the rule as described under Rule Object, or 404 if no rule with that uuid belongs to your brand.
POST /settings/brand/health/network-rules
Create one network rule, or several at once
| Method | POST |
|---|---|
| Path | /settings/brand/health/network-rules |
Request
Send one rule body, or an array of 1 to 100 rule bodies to create several rules at once.
{
"name": "Aetna PPO - INN",
"status": "IN_NETWORK",
"metadata": { "packageId": "4471" },
"conditions": [
{ "key": "payerId", "operator": "EQUAL", "values": ["V404110"] },
{ "key": "insuranceTypeCodes", "operator": "INCLUDE", "values": ["PR"] }
]
}
[
{
"status": "IN_NETWORK",
"metadata": { "packageId": "4471" },
"conditions": [{ "key": "payerId", "operator": "EQUAL", "values": ["V404110"] }]
},
{
"status": "OUT_OF_NETWORK",
"notes": "No self pay",
"metadata": { "packageId": "0000", "selfPay": false },
"conditions": [{ "key": "insuranceTypeCodes", "operator": "INCLUDE", "values": ["MC"] }]
}
]
A rule whose conditions exactly match another rule of your brand (regardless of order or letter case) is rejected with DUPLICATE_CONDITIONS, so retrying a create you are unsure about is safe.
An array is all or nothing: every rule is validated against your existing rules and against the others in the array, and if any is invalid nothing is written and each error carries its ruleIndex. Rules are numbered consecutively in the order sent.
Response
201 with the created rule as described under Rule Object, or an array of them in the order sent.
{
"uuid": "ab280ee0-5f66-4076-9d1b-255d5f0024e3",
"number": 7,
"name": "Aetna PPO - INN",
"status": "IN_NETWORK",
"notes": null,
"metadata": { "packageId": "4471" },
"enabled": true,
"startDate": null,
"endDate": null,
"conditions": [
{ "key": "payerId", "operator": "EQUAL", "values": ["V404110"] },
{ "key": "insuranceTypeCodes", "operator": "INCLUDE", "values": ["PR"] }
],
"createdAt": 1790000000000,
"updatedAt": 1790000000000
}
From the next eligibility check that matches this rule, the result carries network.status: "IN_NETWORK" and network.rules[0].metadata.packageId: "4471"; see NetworkDecision.
POST /settings/brand/health/network-rules/replace
Replace all of your brand's network rules in one call
| Method | POST |
|---|---|
| Path | /settings/brand/health/network-rules/replace |
Use this when your rules live in your own system and you push the whole list on every change, instead of diffing against ours rule by rule. Every rule you send is validated first (including duplicates within the list). Then, in a single transaction, all of your brand's existing rules are deleted and the new ones inserted, numbered from 1 in the order sent. If anything is invalid, nothing is written.
Rules get new uuids on every replace. If your system needs to refer back to a rule, key on something you put in metadata, not on uuid.
Request
| Property | Required? | Type | Format | Default | Description | Example |
|---|---|---|---|---|---|---|
rules | Required | object[] | Array of rule bodies. An empty array removes all of your rules | - | The complete new set of rules | See below |
dryRun | Optional | boolean | - | false | Validate and report what would happen without writing anything. Call with true first, check the result, then call again without it | true |
{
"dryRun": true,
"rules": [
{
"name": "Aetna PPO - INN",
"status": "IN_NETWORK",
"metadata": { "packageId": "4471" },
"conditions": [
{ "key": "payerId", "operator": "EQUAL", "values": ["V404110"] },
{ "key": "insuranceTypeCodes", "operator": "INCLUDE", "values": ["PR"] }
]
},
{
"name": "Medicaid - self pay",
"status": "OUT_OF_NETWORK",
"notes": "No self pay",
"metadata": { "packageId": "0000", "selfPay": false },
"conditions": [{ "key": "insuranceTypeCodes", "operator": "INCLUDE", "values": ["MC"] }]
}
]
}
Response
{
dryRun: boolean, // echoes the request
removed: integer, // rules your brand had before (all of them)
created: integer // rules in the new set
}
{
"dryRun": true,
"removed": 12,
"created": 2
}
On a validation failure the response is a 400 whose data.errors entries each carry ruleIndex; see Errors.
PATCH /settings/brand/health/network-rules/{uuid}
Update a network rule
| Method | PATCH |
|---|---|
| Path | /settings/brand/health/network-rules/{uuid} |
Request
Send any subset of the rule body properties. The whole rule, as it would be after the update, is validated again. metadata and conditions replace the stored value rather than merging into it.
{
"metadata": { "packageId": "4472" },
"enabled": false
}
Response
200 with the updated rule as described under Rule Object (updatedAt changes), or 404 if no rule with that uuid belongs to your brand.
DELETE /settings/brand/health/network-rules/{uuid}
Delete a network rule
| Method | DELETE |
|---|---|
| Path | /settings/brand/health/network-rules/{uuid} |
Request
Call:
DELETE /settings/brand/health/network-rules/ab280ee0-5f66-4076-9d1b-255d5f0024e3
Response
200 with the deleted rule, or 404 if no rule with that uuid belongs to your brand. Rule numbers are not reused.