Customer Identity Verifications

Initiates a new customer identity verification process by submitting the customer's information.

A successful request creates a new CustomerIdentityVerification object and returns a verification_url that you can provide to your customer to complete the identity check.

The Customer Identity Verification object

Attributes
idstring
statusenum

Lifecycle status. Transitions: incomplete → pending → verified or failed. One of incomplete, pending, verified, or failed.

verification_urlstring

Secure URL for the customer to complete the identity verification process. May expire after completion.

createdinteger

Unix timestamp

updatedinteger

Unix timestamp

pendinginteger

Unix timestamp when status moved to pending (0 if not yet pending)

verifiedinteger

Unix timestamp when identity was verified (0 if not yet verified)

failedinteger

Unix timestamp when verification failed (0 if not yet failed)

THE CUSTOMER IDENTITY VERIFICATION OBJECT
{
  "id": null,
  "status": "incomplete",
  "verification_url": null,
  "created": 0,
  "updated": 0,
  "pending": 0,
  "verified": 0,
  "failed": 0
}

Create an identity verification

Initiates a new customer identity verification process by submitting the customer's information.

A successful request creates a new CustomerIdentityVerification object and returns a verification_url that you can provide to your customer to complete the identity check.

Query parameters
first_namestringoptional

The customer's first name.

last_namestringoptional

The customer's last name.

date_of_birthstringoptional

The customer's date of birth in YYYY-MM-DD format.

emailstringoptional

The customer's email address. Must be a valid email format.

phone_numberstringoptional

The customer's phone number. Must be 10-11 digits (non-numeric characters are stripped).

ssnstringoptional

The customer's Social Security Number in XXX-XX-XXXX or XXXXXXXXXX format.

customer_idstringoptional

Existing customer ID (mutually exclusive with profile fields)

Returns

Returns a CustomerIdentityVerification object.

POST/v1/customer_identity_verifications
curl --request POST \
  --url https://api.framepayments.com/v1/customer_identity_verifications \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "e1293644-208d-4c63-8c1e-0f062f36517b",
  "created": 1781115872,
  "updated": 1781115872,
  "pending": 0,
  "verified": 0,
  "failed": 0,
  "status": "incomplete",
  "verification_url": "https://app.framepayments.test/customer_identity_verifications/test-id"
}

Retrieve an identity verification

Retrieves the details of an existing customer identity verification, including its current status and relevant timestamps.

This endpoint allows you to check the status of a verification process at any time.

Path parameters
idstringrequired

Identity verification ID

Returns

Returns a CustomerIdentityVerification object.

GET/v1/customer_identity_verifications/{id}
curl --request GET \
  --url https://api.framepayments.com/v1/customer_identity_verifications/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "1bb2cbe4-41af-4433-8354-4a852c1c4c6a",
  "created": 1781115872,
  "updated": 1781115872,
  "pending": 0,
  "verified": 0,
  "failed": 0,
  "status": "incomplete",
  "verification_url": "https://app.framepayments.test/customer_identity_verifications/test-id"
}

Upload identity documents

Uploads supporting documents for an identity verification (e.g. front/back of ID, selfie). Accepts multipart/form-data.

Path parameters
idstringrequired

Identity verification ID

Returns

Documents uploaded

POST/v1/customer_identity_verifications/{id}/upload_documents
curl --request POST \
  --url https://api.framepayments.com/v1/customer_identity_verifications/a70cd72f-e74a-40f2-96a2-3f60714aac4a/upload_documents \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "9e94c4cc-a6bc-4ec0-90b9-f1c4ba959923",
  "created": 1781115872,
  "updated": 1781115872,
  "pending": 0,
  "verified": 0,
  "failed": 0,
  "status": "incomplete",
  "verification_url": "https://app.framepayments.test/customer_identity_verifications/test-id"
}

Create identity verification for existing customer

Creates an identity verification for an existing customer by customer ID. Equivalent to calling the create endpoint with customer_id.

Path parameters
customer_idstringrequired

Customer ID

Returns

Identity verification created

POST/v1/customer_identity_verifications/{customer_id}
curl --request POST \
  --url https://api.framepayments.com/v1/customer_identity_verifications/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "aeb0609f-cbe1-4510-8c7f-43ceb48b99bf",
  "created": 1781115872,
  "updated": 1781115872,
  "pending": 0,
  "verified": 0,
  "failed": 0,
  "status": "incomplete",
  "verification_url": "https://app.framepayments.test/customer_identity_verifications/test-id"
}