Skip to main content

Endpoints

tip

Postman API documentation is available at https://api.docs.verified.inc.

Use Sandbox for Development and Testing

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​

Run in Postman

Create a (one time use) session key for the client SDK

MethodPOST
Path/client/1-click
note

This endpoint is only relevant if you're using the SDK integration type.

Request​

POST /client/1-click Request Body
{
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
}
}
PropertyRequired?TypeFormatDefaultDescriptionExample
verificationUuid
Optional
stringVersion 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
stringE.164-User's phone number (in E.164 format)"+12125550010"
email
Optional
stringEmail-User's email address"richard@piedpiper.net"
birthDate
Optional
stringyyyy-MM-dd-User's birth date (in Sandbox, this must be "1989-08-01" to pass validation)"1989-08-01"
ssn4
Optional
string4 digits (0-9)-Last 4 digits of user's Social Security Number (in Sandbox, this must be "6789" to pass validation)"6789"
fullName
Optional
objectObject with keys for one or more child credentials listed below-Full name
{
"firstName": "Richard"
}
↳ fullName.firstName
Optional
but
Required
with fullName
stringcAse inSensiTive-First name"Richard"
↳ fullName.middleName
Optional
stringcAse inSensiTive-Middle name"Harrison"
↳ fullName.lastName
Optional
stringcAse inSensiTive-Last name"Hendricks"
address
Optional
objectObject with keys for one or more child credentials listed below-Address
{
"line1": "5320 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"zipCode": "94303",
"country": "US"
}
↳ address.line1
Optional
stringcAse inSensiTive-Line 1 of address"5320 Newell Rd"
↳ address.line2
Optional
stringcAse inSensiTive-Line 2 of address""
↳ address.city
Optional
stringcAse 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)
  • Full state/territory name (ISO 3166-2 subdivision name)
-State of address
  • "CA"
  • "California"
↳ address.zipCode
Optional
string
  • ZIP Code (5 digits, 0-9)
  • ZIP+4 (5 digits, 0-9 + - + 4 digits, 0-9)
-ZIP Code of address
  • "94303"
  • "94303-2846"
↳ address.country
Optional
string
  • 2 letter abbreviation (ISO 3166-1 alpha-2 code, currently always "US")
  • Full country name (ISO 3166-1 English short name, currently always "United States of America")
-Country of address
  • "US"
  • "United States of America"
tip

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​

POST /client/1-click Response Body
{
sessionKey: string
}
PropertyTypeFormatDescriptionExample
sessionKeystringVersion 4 UUIDSession 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

MethodGET
Path/1-click/verifications/device-ip

Request​

Call:

GET /1-click/verifications/device-ip

client side, from the user's device.

important

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​

GET /1-click/verifications/device-ip Response Body
{
deviceIp: string
}
PropertyTypeFormatDescriptionExample
deviceIpstringIPv6 addressThe IP address of the user's device::121:2555:0010

GET /1-click/verifications/channels​

Check the availability of 1-Click Verify channels

MethodGET
Path/1-click/verifications/channels?deviceIp={deviceIp}

Request​

Call:

GET /1-click/verifications/channels?deviceIp={deviceIp}

Response​

GET /1-click/verifications/channels Response Body
{
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
// }
}
}
PropertyTypeFormatDescriptionExample
channelsobjectObject with keys for all channelsAvailability for all channels-
channels.autofillobjectObject with keys for autofill channelAvailability for the autofill channel
{
"available": boolean, // brandApproved && deviceIpEligible
"brandApproved": boolean,
"deviceIpEligible": boolean
}
channels.autofill.availableboolean-Whether the autofill channel is available (= brandApproved && deviceIpEligible)true
channels.autofill.brandApprovedboolean-Whether your brand is approved for the autofill channeltrue
channels.autofill.deviceIpEligibleboolean-Whether the user's device IP is eligible for the autofill channeltrue
channels.smsobjectObject with keys for SMS channelAvailability for the SMS channel
{
"available": boolean
}
channels.sms.availableboolean-Whether the SMS channel is availabletrue
channels.emailobjectObject with keys for email channelAvailability for the email channel
{
"available": boolean
}
channels.email.availableboolean-Whether the email channel is availabletrue

POST /1-click/verifications​

Begin a verification flow

MethodPOST
Path/1-click/verifications

Request​

POST /1-click/verifications Request Body
{
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
}
PropertyRequired?TypeFormatDefaultDescriptionExample
channel
Required
enum

Possible values:

  • "autofill"
  • "silent"
  • "sms"
  • "email"
    Coming Soon
snake_case-Channel used for verification"autofill"
deviceIp
Optional
but
Required
if channel is "autofill" or "silent"
stringIPv6 address-IP address of user's device"::121:2555:0010"
phone
Optional
but
Required
if channel is "silent" or "sms"
stringE.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.

POST /1-click/verifications Response Body
{
...1ClickVerificationEntity // includes phone and verified status if autofill succeeds (and matches phone input if provided)
}

See 1ClickVerificationEntity.

Here's an example with a verified status from the autofill channel:

POST /1-click/verifications Response Body Example (verified)
{
"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:

POST /1-click/verifications Response Body Example (pending)
{
"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

MethodPOST
Path/1-click/verifications/{uuid}/deliver

Request​

POST /1-click/verifications/{uuid}/deliver Request Body
{
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 the uuid included in the 1ClickVerificationEntity that's included in the response body of every 1-Click Verify endpoint.
PropertyRequired?TypeFormatDefaultDescriptionExample
format
Optional
enum

Possible values:

  • "code"
  • "link"
  • "codeAndLink"
  • "linkAndCode"
camelCase"code"Format used for verification message (see Verification SMS Formats below)"linkAndCode"
redirectUrl
Optional
stringURLDefined by the redirect URL brand setting in the DashboardWhere 1-Click Verify redirects a user to (only relevant if link format is included)"https://hooli.com/verified/1-click/verify"
redirectUserAfter
Optional
enum

Possible values:

  • "phoneVerification" (redirect after 1-Click Verify)
  • "infoConfirmation" (redirect after hosted 1-Click Signup/Health)
camelCaseDefined by the redirect user after brand setting in the DashboardWhen a user is redirected to the redirect URL (only relevant if link format is included)"phoneVerification"
Verification SMS Formats

The content of the verification SMS depends on the format:

FormatformatSMS TemplateSMS Example
Code
Default
code

Enter this code to verify for {Brand Name}: 111111

Enter this code to verify for Hooli: 111111

Linklink

Click this link to verify for {Brand Name}: https://1-click.verified.inc/abcd1234

Click this link to verify for Hooli: https://1-click.verified.inc/abcd1234

Code and LinkcodeAndLink

Enter this code to verify for {Brand Name}: 111111


Or, click this link: https://1-click.verified.inc/abcd1234

Enter this code to verify for Hooli: 111111


Or, click this link: https://1-click.verified.inc/abcd1234

Link and CodelinkAndCode

Click this link to verify for {Brand Name}: https://1-click.verified.inc/abcd1234


Or, enter this code: 111111

Click this link to verify for Hooli: https://1-click.verified.inc/abcd1234


Or, enter this code: 111111

Response​

POST /1-click/verifications/{uuid}/deliver Response Body
{
...1ClickVerificationEntity
}

See 1ClickVerificationEntity. Here's an example:

POST /1-click/verifications/{uuid}/deliver Response Body 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

MethodPOST
Path/1-click/verifications/{uuid}/verify

Request​

POST /1-click/verifications/{uuid}/verify Request Body
{
code: string
}
  • For the {uuid} path parameter, use the value of the uuid included in the 1ClickVerificationEntity that's included in the response body of every 1-Click Verify endpoint.
PropertyRequired?TypeFormatDefaultDescriptionExample
code
Required
string6 digits (0-9)-User submitted verification code"111111"

Response​

POST /1-click/verifications/{uuid}/verify Response Body
{
...1ClickVerificationEntity
}

See 1ClickVerificationEntity. Here's an example:

POST /1-click/verifications/{uuid}/verify Response Body 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

MethodGET
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 verificationUuid included as a URL parameter on the redirect URL.
    • Otherwise, use the value of the uuid included in the 1ClickVerificationEntity that's included in the response body of a relevant 1-Click Verify endpoint.

Response​

GET /1-click/verifications/{uuid} Response Body
{
...1ClickVerificationEntity
}

See 1ClickVerificationEntity. Here's an example:

GET /1-click/verifications Response Body 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​

Run in Postman

Begin a 1-Click Signup flow

MethodPOST
Path/1-click
note

This endpoint is only relevant if you're using the API integration type.

Request​

POST /1-click Request Body
{
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[]
}
PropertyRequired?TypeFormatDefaultDescriptionExample
identityUuid
Optional
stringVersion 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
stringVersion 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
stringE.164-User's phone number (in E.164 format)"+12125550010"
email
Optional
stringEmail-User's email address"richard@piedpiper.net"
deviceIp
Optional
stringIPv6 address-IP address of user's device (which you can get using GET /1-click/verifications/device-ip)"::121:2555:0010"
birthDate
Optional
stringyyyy-MM-dd-Birth date"1989-08-01"
ssn4
Optional
string4 digits (0-9)-Last 4 digits of Social Security Number"6789"
fullName
Optional
objectObject with keys for one or more child credentials listed below-Full name
{
"firstName": "Richard",
"lastName": "Hendricks"
}
↳ fullName.firstName
Optional
stringcAse inSensiTive-First name"Richard"
↳ fullName.middleName
Optional
stringcAse inSensiTive-Middle name"Harrison"
↳ fullName.lastName
Optional
stringcAse inSensiTive-Last name"Hendricks"
address
Optional
objectObject with keys for one or more child credentials listed below-Address
{
"line1": "5320 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"zipCode": "94303",
"country": "US"
}
↳ address.line1
Optional
stringcAse inSensiTive-Line 1 of address"5320 Newell Rd"
↳ address.line2
Optional
stringcAse inSensiTive-Line 2 of address""
↳ address.city
Optional
stringcAse 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)
  • Full state/territory name (ISO 3166-2 subdivision name)
-State of address
  • "CA"
  • "California"
↳ address.zipCode
Optional
string
  • ZIP Code (5 digits, 0-9)
  • ZIP+4 (5 digits, 0-9 + - + 4 digits, 0-9)
-ZIP Code of address
  • "94303"
  • "94303-2846"
↳ address.country
Optional
string
  • 2 letter abbreviation (ISO 3166-1 alpha-2 code, currently always "US")
  • Full country name (ISO 3166-1 English short name, currently always "United States of America")
-Country of address
  • "US"
  • "United States of America"
credentialRequests
Optional
CredentialRequest[]See CredentialRequestDefined by the default credential requests brand setting in the DashboardList of CredentialRequest objects (which encode which credentials you're asking for): an empty array tells us to source only metadata, no credentialsSee 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
Standard Credential Requests
[
{
"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",
}
]
An Empty Array Means Metadata Only

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​

POST /1-click Response Body
{
uuid: string,
identity: 1ClickEntity
}
PropertyTypeFormatDescriptionExample
uuidstringVersion 4 UUIDUnique identifier for the 1ClickEntity that will be returned at the end of the 1-Click Signup flow"535dba63-d4bd-442a-b3f6-21b785260a08"
identity1ClickEntitySee 1ClickEntityA 1ClickEntity object, which contains the user's verified data and metadata about itSee 1ClickEntity example

GET /1-click​

Run in Postman

Get data for a user who has completed a 1-Click Signup flow

MethodGET
Path/1-click/{identityUuid}

Request​

Call:

GET /1-click/{identityUuid}
  • For the {identityUuid} path parameter, use the value of the identityUuid returned by the SDK or included as a URL parameter on the redirect URL.

Response​

GET /1-click Response Body
{
...1ClickEntity
}

See 1ClickEntity.


1-Click Health​

POST /1-click/health​

Run in Postman

Begin a 1-Click Health flow (for autofill, check, or both)

MethodPOST
Path/1-click/health
note

This endpoint is only relevant if you're using the API integration type.

Request​

POST /1-click/health Request Body
{
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[]
}[]
}
}
PropertyRequired?TypeFormatDefaultDescriptionExample
checkAfterAutofill
Optional
boolean-Defined by the Check After Autofill settingWhether to automatically run an eligibility check for an autofilled health insurance plantrue
provider
Optional
objectObject with key listed below-Provider information
{
"npi": "0123456789"
}
↳ provider.npi
Required
(if provider object is included)
string10 digits (0-9)Defined by Providers settingNational Provider Identifier"0123456789"
identityUuid
Optional
stringVersion 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
string1–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
objectObject with keys for one or more child credentials listed below-Full name
{
"firstName": "Richard",
"lastName": "Hendricks"
}
↳ fullName.firstName
Optional
but
Required
if no identityUuid
stringcAse inSensiTive-First name"Richard"
↳ fullName.middleName
Optional
stringcAse inSensiTive-Middle name"Harrison"
↳ fullName.lastName
Optional
but
Required
if no identityUuid
stringcAse inSensiTive-Last name"Hendricks"
birthDate
Optional
but
Required
if no identityUuid
stringyyyy-MM-dd-Birth date"1989-08-01"
address
Optional
objectObject with keys for one or more child credentials listed below-Address
{
"line1": "5320 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"zipCode": "94303",
"country": "US"
}
↳ address.line1
Optional
stringcAse inSensiTive-Line 1 of address"5320 Newell Rd"
↳ address.line2
Optional
stringcAse inSensiTive-Line 2 of address""
↳ address.city
Optional
stringcAse inSensiTive-City of address"Palo Alto"
↳ address.state
Optional
string2 letter abbreviation (last 2 characters of ISO 3166-2 code for US state/territory)-State of address"CA"
↳ address.zipCode
Optional
stringZIP Code (5 digits, 0-9)-ZIP Code of address"94303"
↳ address.country
Optional
string2 letter abbreviation (ISO 3166-1 alpha-2 code, currently always "US")-Country of address"US"
sex
Optional
enum

Possible values:

  • "Male"
  • "Female"
  • "Non-Binary"
Title Case-Sex"Male"
ssn
Optional
string9 digits (0-9)-Social Security Number"000456789"
payer
Optional
objectObject 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
objectObject 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
[
{
"code": "99213",
"qualifier": "HC",
"modifiers": ["25"]
}
]
↳ ↳ procedureCodes[i]
Optional
objectObject with keys described below-National Provider Identifier
{
"code": "99213",
"qualifier": "HC",
"modifiers": ["25"]
}
↳ ↳ ↳ procedureCodes[i].code
Required
(if procedureCodes object is included)
string
  • 5 digits (for CPT code)
  • 1 letter and 4 digits (for HCPCS code)
-CPT or HCPCS procedure code"99213""
↳ ↳ ↳ procedureCodes[i].qualifier
Optional
string enum

Possible values:

  • "AD": American Dental Association Codes)
  • "CJ": Current Procedural Terminology (CPT) Codes
  • "HC": Health Care Financing Administration Common Procedural Coding System (HCPCS) Codes
  • "ID": International Classification of Diseases, 9th Revision, Clinical Modification (ICD-9-CM) - Procedure
  • "IV": Home Infusion EDI Coalition (HIEC) Product/Service Code
  • "N4": National Drug Code in 5-4-2 Format
  • "ZZ": Mutually Defined Code identifying the type/source of the procedureCode. You can set this to AD - , CJ - , HC - , ID - , IV - , N4 - , or ZZ - .
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​

POST /1-click/health Response Body
{
healthDataUuid: string,
externalReference?: string, // your own reference string, included if passed to POST /1-click/health
status: "PENDING" | "PROCESSING" | "SUCCEEDED" | "FAILED" | "PARTIAL"
}
PropertyTypeFormatDescriptionExample
healthDataUuidstringVersion 4 UUIDUnique identifier for the 1ClickHealthEntity that will be returned at the end of the 1-Click Health flow"9e12fe5b-5bb8-410a-ac6b-6e053e4c7e8d"
externalReferencestring1–256 charactersYour own reference string, echoed from POST /1-click/health request body if included"appointment-1042"
status
enum

Possible values:

  • "PENDING"
  • "PROCESSING"
  • "SUCCEEDED"
  • "FAILED"
  • "PARTIAL"
UPPER_SNAKE_CASEStatus of the 1-Click Health flow"PROCESSING"

GET /1-click/health​

Run in Postman

Get data for a user who has completed a 1-Click Health flow

MethodGET
Path/1-click/health/{healthDataUuid}

Request​

Call:

GET /1-click/health/{healthDataUuid}
  • For the {healthDataUuid} path parameter, use the value of the healthDataUuid returned by the SDK or POST /1-click/health.

Response​

GET /1-click/health Response Body
{
...1ClickHealthEntity
}

See 1ClickHealthEntity.


GET /1-click/health/payers​

Run in Postman

Get all supported payers for 1-Click Health

MethodGET
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
ParameterRequired?TypeFormatDefaultDescriptionExample
$search
Optional
string--Search by payer name or IDaetna
$limit
Optional
integer-10Number of payers per page100
$skip
Optional
integer-0Number of payers to skip25
$paginate
Optional
boolean--Whether to return paginated resultstrue
note

This endpoint is unauthenticated.

Response​

Without query parameters, the response body will be unpaginated:

GET /1-click/health/payers Response Body (unpaginated)
[
...Payer
]

See Payer. This includes all supported payers.

With query parameters, the response body will be paginated:

GET /1-click/health/payers?... Response Body (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.

PropertyTypeFormatDescriptionExample
totalinteger-Number of payers3460
limitinteger-Number of payers per page100
skipinteger-Number of payers to skip25
dataPayer[]Array of PayersPayers that match submitted query-
data[i]PayerSee PayerPayerSee 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.

info

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 network objects (of NetworkDecision type) 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.

Example Use

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.

MethodPathDescription
GET/settings/brand/health/network-rulesList your brand's network rules
GET/settings/brand/health/network-rules/{uuid}Retrieve one network rule
POST/settings/brand/health/network-rulesCreate one network rule, or several at once
POST/settings/brand/health/network-rules/replaceReplace 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:

PropertyTypeFormatDescriptionExample
numberintegerPositive integerPer-brand sequence number in creation order. Assigned by Verified, never changes, never reused. Used for the default name ("Rule 7")7
enabledboolean-Whether the rule is applied. A disabled rule is stored but never matchestrue
createdAtintegerUnix epoch, millisecondsWhen the rule was created1790000000000
updatedAtintegerUnix epoch, millisecondsWhen the rule was last updated1790000000000

Rule Body​

  • POST (create) and POST .../replace take rule bodies.
  • PATCH takes any subset of the same properties.
  • uuid, number, createdAt and updatedAt are assigned by Verified and are rejected if sent.
PropertyRequired?TypeFormatDefaultDescriptionExample
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 matchSee Conditions
name
Optional
stringNon-empty"Rule {number}"Name for the rule"Aetna PPO - INN"
notes
Optional
string | null-nullFree text, returned with the decision so your app can branch on it"No self pay"
metadata
Optional
objectFlat 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
{ "packageId": "4471", "selfPay": false }
enabled
Optional
boolean-trueWhether the rule is appliedtrue
startDate
Optional
string | nullyyyy-MM-ddnullDate the rule starts applying (at start of day, UTC, inclusive)"2026-10-01"
endDate
Optional
string | nullyyyy-MM-dd, after startDatenullDate the rule stops applying (at start of day, UTC, exclusive)"2027-10-01"

Conditions​

  • A condition is { key, operator, values }.
  • values is 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.
keyTypeAllowed operatorsAllowed valuesExample
payerIdenumEQUAL, NOT_EQUALVerified 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"]
payerNametextEQUAL, NOT_EQUAL, INCLUDE, NOT_INCLUDEAny text. INCLUDE is a case-insensitive substring match["Aetna"]
stateenumEQUAL, NOT_EQUALTwo-letter US state or territory codes (the patient's address state)["MA", "NY", "WA"]
insuranceTypeCodesenumINCLUDE, NOT_INCLUDEX12 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"]
planNametextEQUAL, NOT_EQUAL, INCLUDE, NOT_INCLUDEAny text["PPO"]
relatedEntitiestextEQUAL, NOT_EQUAL, INCLUDE, NOT_INCLUDEAny text (names of related entities on the eligibility response, for example a PBM or TPA)["OPTUMRX"]
groupNumbertextEQUAL, NOT_EQUAL, INCLUDE, NOT_INCLUDEAny text["123456-123-12345"]
groupNametextEQUAL, NOT_EQUAL, INCLUDE, NOT_INCLUDEAny text["Pied Piper"]
No PHI in rules

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)
CodeMeaning
NONENo insurance type code on the eligibility response
12Medicare Secondary Working Aged Beneficiary or Spouse with Employer Group Health Plan
13Medicare Secondary End-Stage Renal Disease Beneficiary in the Mandated Coordination Period
14Medicare Secondary, No-fault Insurance including Auto is Primary
15Medicare Secondary Worker's Compensation
16Medicare Secondary Public Health Service (PHS) or Other Federal Agency
41Medicare Secondary Black Lung
42Medicare Secondary Veteran's Administration
43Medicare Secondary Disabled Beneficiary Under Age 65 with Large Group Health Plan (LGHP)
47Medicare Secondary, Other Liability Insurance is Primary
APAuto Insurance Policy
C1Commercial
COCOBRA
CPMedicare Conditionally Primary
DDisability
DBDisability Benefits
EPExclusive Provider Organization (EPO)
FFFamily or Friends
GPGroup Policy
HMHealth Maintenance Organization (HMO)
HNHMO - Medicare Risk (Medicare Advantage)
HSSpecial Low Income Medicare Beneficiary
INIndemnity
IPIndividual Policy
LCLong Term Care
LDLong Term Policy
LILife Insurance
LTLitigation
MAMedicare Part A
MBMedicare Part B
MCMedicaid
MHMedigap Part A
MIMedigap Part B
MPMedicare Primary
OTOther
PEProperty Insurance - Personal
PLPersonal
PPPersonal Payment (Cash - No Insurance)
PRPreferred Provider Organization (PPO)
PSPoint of Service (POS)
QMQualified Medicare Beneficiary
RPProperty Insurance - Real
SPSupplemental Policy
TFTax Equity Fiscal Responsibility Act (TEFRA)
WCWorkers Compensation
WUWrap Up Policy

Errors​

StatusnameWhen
400BadRequestThe 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
401NotAuthenticatedMissing or invalid API key, or a key blocked by an IP allowlist
403Forbidden1-Click Health is not contracted or is disabled for the brand
404NotFoundNo rule with that uuid belongs to your brand
  • Each entry of data.errors has a stable code, a human-readable message, and (when it concerns one condition) the condition's index plus its key, operator and offending value(s).
  • For a batch (an array sent to POST) or a replace, each entry also has ruleIndex, the position of the rule in the array you sent.
  • Every problem is reported at once, so one request tells you everything to fix.
codeMeaning
UNKNOWN_KEYkey is not one of the condition keys above
OPERATOR_NOT_ALLOWED_FOR_KEYoperator is not allowed for that key (for example INCLUDE on state)
VALUE_SHAPEvalues is not a non-empty array of non-empty strings
UNKNOWN_ENUM_VALUEA value is not a known payer ID, state code or insurance type code
PHI_SUSPECTEDA text value looks like a member ID or a date
DUPLICATE_CONDITIONSAnother rule of your brand (its uuid is in value), or another rule in the same request, has exactly these conditions
DATE_RANGE_INVERTEDstartDate is not before endDate
METADATA_INVALIDmetadata exceeds the limits above
400 Response Body Example
{
"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

MethodGET
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
ParameterRequired?TypeFormatDefaultDescriptionExample
$limit
Optional
integer1 to 10010Number of rules per page50
$skip
Optional
integer-0Number of rules to skip50
$sort[field]
Optional
1 | -1field is number, name, status, enabled, createdAt or updatedAtcreatedAt ascending, then numberSort 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 propertystatus=OUT_OF_NETWORK, updatedAt[$gt]=1790000000000
search
Optional
string1 to 120 characters-Case-insensitive substring over name and notessearch=self%20pay
condition[key]
Optional
string | string[]Condition key(s)-Rules that have a condition on any of these keyscondition[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 textcondition[planName][value]=PPO
metadata[key]
Optional
string | string[]Metadata key(s)-Rules whose metadata has any of these keysmetadata[key]=packageId
metadata[value]
Optional
object{ key, value, operator? }, same text operators as above-Rules whose metadata[key] matches the textmetadata[value][key]=packageId&metadata[value][value]=4471

All filters combine with AND.

Response​

GET /settings/brand/health/network-rules Response Body
{
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

MethodGET
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

MethodPOST
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.

POST /settings/brand/health/network-rules Request Body (one rule)
{
"name": "Aetna PPO - INN",
"status": "IN_NETWORK",
"metadata": { "packageId": "4471" },
"conditions": [
{ "key": "payerId", "operator": "EQUAL", "values": ["V404110"] },
{ "key": "insuranceTypeCodes", "operator": "INCLUDE", "values": ["PR"] }
]
}
POST /settings/brand/health/network-rules Request Body (several rules)
[
{
"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.

POST /settings/brand/health/network-rules Response Body (one rule)
{
"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

MethodPOST
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.

warning

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​

PropertyRequired?TypeFormatDefaultDescriptionExample
rules
Required
object[]Array of rule bodies. An empty array removes all of your rules-The complete new set of rulesSee below
dryRun
Optional
boolean-falseValidate and report what would happen without writing anything. Call with true first, check the result, then call again without ittrue
POST /settings/brand/health/network-rules/replace Request Body
{
"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​

POST /settings/brand/health/network-rules/replace Response Body
{
dryRun: boolean, // echoes the request
removed: integer, // rules your brand had before (all of them)
created: integer // rules in the new set
}
POST /settings/brand/health/network-rules/replace Response Body Example
{
"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

MethodPATCH
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.

PATCH /settings/brand/health/network-rules/{uuid} Request Body
{
"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

MethodDELETE
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.