Create a verification request

POST

/requests

• Production

Creates a new verification request. If subjectEmail is provided, the subject receives an email invitation with a link to complete their verification steps.

Authorizations

• ApiKeyAuth

Request Body ^required

object

type

required

Verification type

string

Allowed values: idv kyc share

requirements

required

Ordered list of verification steps to collect

Array<string>

>= 1 items

Allowed values: document person location contact biometric_face business pep_hio financial consent attestation estate

clientId

Link to an existing client record. Subject name/email/phone are loaded from the client if not overridden.

string format: uuid

matterId

Link to a matter

string format: uuid

subjectName

Full name of the subject being verified

string

<= 128 characters

subjectEmail

Email address — used to send the verification invitation

string format: email

subjectPhone

Phone number

string

<= 32 characters

expiresDays

Days until the verification link expires

integer

default: 7 >= 1 <= 90

config

Step-specific configuration overrides

object

key

additional properties

any

thirdParties

Third parties to auto-share the result with on approval

Array<object>

object

name

required

string

<= 128 characters

email

required

string format: email

org

string

<= 128 characters

sharedFields

Array<string>

Examples

Smart IDV with document and biometric

{
  "type": "idv",
  "requirements": [
    "document",
    "person",
    "biometric_face"
  ],
  "subjectName": "Jane Smith",
  "subjectEmail": "jane@example.com",
  "expiresDays": 7
}

KYC linked to existing client

{
  "type": "kyc",
  "requirements": [
    "document",
    "person",
    "financial",
    "pep_hio"
  ],
  "clientId": "clt_01j9abc456"
}

Responses

201

Request created

object

id

string

orgId

string

type

string

Allowed values: idv kyc share

status

string

Allowed values: initiated in_progress submitted pending_review approved rejected canceled expired

requirements

Array<string>

currentStep

string

nullable

subjectName

string

nullable

subjectEmail

string

nullable

subjectPhone

string

nullable

requestorName

string

nullable

requestorEmail

string

nullable

requestorCompany

string

nullable

clientId

string

nullable

matterId

string

nullable

expiresDays

integer

expiresAt

string format: date-time

submittedAt

string format: date-time

nullable

accessToken

Token used in the subject-facing verification URL

string

createdAt

string format: date-time

updatedAt

string format: date-time

401

Missing or invalid API key

object

code

string

message

string

statusCode

integer

Example

{
  "code": "UNAUTHORIZED",
  "message": "Invalid API key.",
  "statusCode": 401
}

402

Subscription inactive

object

code

string

message

string

statusCode

integer

Example

{
  "code": "PAYMENT_REQUIRED",
  "message": "Your subscription is inactive. Please resubscribe to use the API.",
  "statusCode": 402
}

403

Plan does not include API access

object

code

string

message

string

statusCode

integer

Example

{
  "code": "FORBIDDEN",
  "message": "API access requires a Professional, Business, or Enterprise plan.",
  "statusCode": 403
}

422

Request body failed validation

object

code

string

message

string

statusCode

integer

errors

Array<object>

object

field

string

message

string

Example

{
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "statusCode": 422,
  "errors": [
    {
      "field": "type",
      "message": "Required"
    },
    {
      "field": "requirements",
      "message": "Array must contain at least 1 element(s)"
    }
  ]
}

429

Too many requests

object

code

string

message

string

statusCode

integer

Example

{
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "statusCode": 429
}

Headers

Retry-After

integer

Seconds until the rate limit window resets

X-RateLimit-Limit

integer

X-RateLimit-Remaining

integer