Identity Verifications
Run and inspect KYC identity verifications for an account. Creating a verification runs KYC against the account's current identity data; the run starts pending and concludes asynchronously — poll it or listen for the account.identity_verification.* webhook events. Failure details are provider-neutral buckets (failure_type, retriable, category), never raw vendor codes.
The Identity Verification object
Attributes
Unique identifier for the identity verification.
Object type identifier. Always identity_verification.
Current status. One of pending, approved, failed, errored, or incomplete. An errored run reached no judgement of the identity and does not count against the account's attempt allowance.
Why the verification failed, as a provider-neutral bucket. One of identity_mismatch, identity_not_found, verification_rejected, review_pending, provider_error, signals_unavailable, or unclassified. null while the run is pending or once it is approved.
Whether retrying can change the outcome — true when correcting the account's identity data (or waiting out a transient fault) can succeed. null when failure_type is null.
The remediation class behind retriable. One of retriable_with_new_data, step_up, terminal, review, transient, or unclassified. null when failure_type is null.
ID of the account this verification belongs to.
true if live mode, false if test mode.
Unix timestamp of when the run was created.
Unix timestamp of when the run reached a terminal status. null while pending.
Unix timestamp of when the provider opened a manual review of this run. null when no review was opened.
Unix timestamp of when the provider review resolved. null while the review is open or when no review was opened.
{
"id": "c4f1a2b3-d5e6-7890-abcd-ef1234567892",
"object": "identity_verification",
"status": "pending",
"failure_type": null,
"retriable": null,
"category": null,
"account": "99c6b0da-2570-42a7-838a-5eaa318b07df",
"livemode": false,
"created": 1721010605,
"completed": null,
"review_opened": null,
"review_resolved": null
}
List identity verifications
Returns the account's identity-verification runs, most recent first. Filter with the status and provider query parameters, and page through with the standard page / per_page parameters.
Path parameters
The ID of the account.
Query parameters
Only return runs with this status (e.g. pending, approved, failed).
Only return runs from this provider.
Page number (default 1).
Items per page (default 10, max 100).
Returns
A dictionary with a data array of identity-verification runs, most recent first, and pagination meta.
curl --request GET \
--url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/identity_verifications \
--header 'Authorization: Bearer API_KEY'
{
"meta": {
"page": 1,
"url": "/v1/accounts/00000000-0000-4000-8000-000000000001/identity_verifications?status=&provider=&page=&per_page=",
"has_more": false,
"prev": null,
"next": null
},
"data": [
{
"id": "00000000-0000-4000-8000-000000000002",
"object": "identity_verification",
"status": "pending",
"failure_type": null,
"retriable": null,
"category": null,
"account": "00000000-0000-4000-8000-000000000001",
"livemode": true,
"created": 1745107200,
"completed": null,
"review_opened": null,
"review_resolved": null
},
{
"id": "00000000-0000-4000-8000-000000000003",
"object": "identity_verification",
"status": "failed",
"failure_type": "identity_mismatch",
"retriable": true,
"category": "retriable_with_new_data",
"account": "00000000-0000-4000-8000-000000000001",
"livemode": true,
"created": 1744934400,
"completed": 1745020800,
"review_opened": null,
"review_resolved": null
}
]
}
Create an identity verification
Runs KYC against the account's current identity data. The request body is empty by design — to correct identity fields first, update the account, then create the verification. Returns 201 with the new run in pending status; the run concludes asynchronously, so poll it with the retrieve endpoint or listen for the account.identity_verification.approved / account.identity_verification.failed webhook events.
While a run is open the endpoint returns 409 (verification_in_progress) with the open run's ID in details rather than starting a parallel run. Once the account has spent its verification attempt allowance it returns 429 (attempt_limit_reached). If the account's kyc capability has been disabled it returns 422 (capability_disabled) — re-request the capability first. Data verification runs are available for US accounts only; a non-US account returns 422 (kyc_not_available) and verifies via the idv document flow instead.
Path parameters
The ID of the account to verify.
Returns
The pending identity-verification run.
curl --request POST \
--url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/identity_verifications \
--header 'Authorization: Bearer API_KEY'
{
"id": "00000000-0000-4000-8000-000000000001",
"object": "identity_verification",
"status": "pending",
"failure_type": null,
"retriable": null,
"category": null,
"account": "00000000-0000-4000-8000-000000000002",
"livemode": true,
"created": 1745107200,
"completed": null,
"review_opened": null,
"review_resolved": null
}
Retrieve an identity verification
Returns a single identity-verification run. A concluded failure carries provider-neutral buckets: failure_type names what went wrong, retriable says whether another attempt can change the outcome, and category names the remediation class (correct the data, complete a document step-up, or wait for review). Raw vendor reason codes are never exposed.
Path parameters
The ID of the account.
The ID of the identity verification.
Returns
The identity-verification run.
curl --request GET \
--url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/identity_verifications/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "00000000-0000-4000-8000-000000000001",
"object": "identity_verification",
"status": "failed",
"failure_type": "identity_mismatch",
"retriable": true,
"category": "retriable_with_new_data",
"account": "00000000-0000-4000-8000-000000000002",
"livemode": true,
"created": 1745100000,
"completed": 1745103600,
"review_opened": null,
"review_resolved": null
}