Customer Identity Verifications

The Customer Identity Verifications API allows you to create and retrieve Know Your Customer (KYC) verification records. This is essential for verifying your customers' identities to comply with regulatory requirements.

A CustomerIdentityVerification object is created to track the status of the verification process. You can monitor its progress using the API or by subscribing to webhook events.

The CustomerIdentityVerification object

Attributes
idstring

Unique identifier for the object.

statusenum

The current status of the identity verification. Possible values: incomplete, pending, verified, failed.

verification_urlnullable string

A secure URL that you can share with your customer to complete the verification process. This URL is typically available when the verification is in an incomplete or pending status and is returned upon creation. It may become null or expire after the process is completed or has been pending for too long.

objectstring

String representing the object's type. Objects of the same type share the same value.

createdtimestamp

Time at which the object was created. Measured in seconds since the Unix epoch.

updatedtimestamp

Time at which the object was last updated. Measured in seconds since the Unix epoch.

pendingnullable timestamp

Time at which the object status was changed to pending. Measured in seconds since the Unix epoch.

verifiednullable timestamp

Time at which the object status was changed to verified. Measured in seconds since the Unix epoch.

failednullable timestamp

Time at which the object status was changed to failed. Measured in seconds since the Unix epoch.

THE CUSTOMER IDENTITY VERIFICATION OBJECT
{
  "id": "d3f44c10-f3c4-4662-9f73-94587a072629",
  "object": "customer_identity_verification",
  "status": "verified",
  "verification_url": "https://app.framepayments.com/customer_identity_verifications/d3f44c10-f3c4-4662-9f73-94587a072629",
  "created": 1713323382,
  "updated": 1713323385,
  "pending": 1713323383,
  "verified": 1713323384,
  "failed": null
}

Create a Customer 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.

Parameters
first_nameREQUIREDstring

The customer's first name.

last_nameREQUIREDstring

The customer's last name.

date_of_birthREQUIREDstring

The customer's date of birth (e.g., "YYYY-MM-DD").

emailstring

The customer's email address. Providing an email can enable additional verification methods.

phone_numberstring

The customer's phone number. Providing a phone number can enable additional verification methods.

addressREQUIREDobject

Physical address information associated with the customer.

citynullable string

City, district, suburb, town, or village.

countrynullable string

Two-letter country code (ISO 3166-1 alpha-2).

statenullable string

State, county, province, or region.

postal_codenullable string

ZIP or postal code.

line_1nullable string

Address line 1 (e.g., street, PO Box, or company name).

line_2nullable string

Address line 2 (e.g., apartment, suite, unit, or building).

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' \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-01-15",
    "email": "john.doe@example.com",
    "phone_number": "555-123-4567",
    "address": {
      "line_1": "123 Main St",
      "line_2": "Apt 4B",
      "city": "Anytown",
      "state_or_province": "CA",
      "postal_code": "90210",
      "country": "US"
    }
  }'
RESPONSE
{
  "id": "d3f44c10-f3c4-4662-9f73-94587a072629",
  "object": "customer_identity_verification",
  "status": "pending",
  "verification_url": "https://app.framepayments.com/customer_identity_verifications/d3f44c10-f3c4-4662-9f73-94587a072629",
  "created": 1713323382,
  "updated": 1713323385,
  "pending": 1713323383,
  "verified": null,
  "failed": null
}

Retrieve a Customer 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.

Parameters

No parameters.

Returns

Returns a CustomerIdentityVerification object.

GET/v1/customer_identity_verifications/:id
curl --request GET \
  --url https://api.framepayments.com/v1/customer_identity_verifications/d3f44c10-f3c4-4662-9f73-94587a072629 \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "d3f44c10-f3c4-4662-9f73-94587a072629",
  "object": "customer_identity_verification",
  "status": "pending",
  "verification_url": "https://app.framepayments.com/customer_identity_verifications/d3f44c10-f3c4-4662-9f73-94587a072629",
  "created": 1713323382,
  "updated": 1713323385,
  "pending": 1713323383,
  "verified": null,
  "failed": null
}