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 Customer Identity Verification 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.

Note: This is a premium Frame API endpoint. In order to utilize this endpoint within your project, please contact customer support to get started.

The Customer Identity Verification object

Attributes
idstringoptional

Unique identifier for the object.

statusenumoptional

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

verification_urlnullable stringoptional

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.

objectstringoptional

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

createdtimestampoptional

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

updatedtimestampoptional

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

pendingnullable timestampoptional

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

verifiednullable timestampoptional

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

failednullable timestampoptional

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_namestringrequired

The customer's first name.

last_namestringrequired

The customer's last name.

date_of_birthstringrequired

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

emailstringrequired

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

phone_numberstringrequired

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

ssnstringrequired

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

addressobjectrequired

Physical address information associated with the customer.

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",
    "ssn": "123-45-6789",
    "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
}