Business Verifications

Run and inspect KYB verifications for US business accounts. Runs conclude asynchronously and emit account.business_verification.* webhook events; public results expose provider-neutral failure and remediation buckets.

ENDPOINTS

GET/v1/accounts/{account_id}/business_verifications POST/v1/accounts/{account_id}/business_verifications GET/v1/accounts/{account_id}/business_verifications/{id}

The Business Verification object

Attributes

idstring

Unique identifier for the business verification.

objectstring

Object type identifier. Always business_verification.

statusenum

Current run status. One of pending, approved, failed, errored, or incomplete.

failure_typeenum

Provider-neutral failure. One of verification_rejected, review_pending, provider_error, incomplete, or unclassified; null before a failure.

retriablenullable boolean

Whether another attempt may succeed. null before a failure.

categoryenum

Remediation class. One of retriable_with_new_data, terminal, review, transient, or unclassified.

accountstring

ID of the business account this run belongs to.

livemodeboolean

true in live mode and false in test mode.

createdinteger

Unix timestamp when the run was created.

completednullable integer

Unix timestamp when the run reached a terminal status.

review_openednullable integer

Unix timestamp when manual review opened.

review_resolvednullable integer

Unix timestamp when manual review resolved.

THE BUSINESS VERIFICATION OBJECT

{
  "id": "d5e6f7a8-b9c0-4123-8456-789abcdef012",
  "object": "business_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 business verifications

Returns this account's KYB runs in reverse chronological order with standard pagination metadata. Optional status and provider filters narrow the history, although provider identity is never serialized in a result.

Path parameters

account_idstringrequired

The ID of the business account.

Query parameters

statusenumoptional

Only return runs with this status. One of pending, approved, failed, errored, or incomplete.

providerstringoptional

Only return runs from this provider.

Returns

A paginated collection of business-verification runs.

GET/v1/accounts/{account_id}/business_verifications

curl --request GET \
  --url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/business_verifications \
  --header 'Authorization: Bearer API_KEY'

RESPONSE

{
  "meta": {
    "page": 1,
    "url": "/v1/accounts/00000000-0000-4000-8000-000000000001/business_verifications?status=&provider=",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000002",
      "object": "business_verification",
      "status": "pending",
      "failure_type": "unclassified",
      "retriable": false,
      "category": "unclassified",
      "account": "00000000-0000-4000-8000-000000000001",
      "livemode": false,
      "created": 1745107200,
      "completed": null,
      "review_opened": null,
      "review_resolved": null
    }
  ]
}

Create a business verification

Runs KYB asynchronously against the US business profile and owner roster already stored on the account. Update those resources before creating a run; the request body is intentionally empty.

The business collection requirements and every owner or controller's KYC must be complete. Poll the returned run or listen for account.business_verification.* webhooks; parallel runs are refused and five answered attempts are allowed per rolling 30-day window.

Path parameters

account_idstringrequired

The ID of the US business account to verify.

Returns

The newly created pending business-verification run.

POST/v1/accounts/{account_id}/business_verifications

curl --request POST \
  --url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/business_verifications \
  --header 'Authorization: Bearer API_KEY'

RESPONSE

{
  "id": "00000000-0000-4000-8000-000000000001",
  "object": "business_verification",
  "status": "pending",
  "failure_type": "unclassified",
  "retriable": false,
  "category": "unclassified",
  "account": "00000000-0000-4000-8000-000000000002",
  "livemode": false,
  "created": 1745107200,
  "completed": null,
  "review_opened": null,
  "review_resolved": null
}

Retrieve a business verification

Returns one KYB run belonging to the scoped business account. Failure fields describe a provider-neutral remediation class; raw provider statuses, results, and vendor identifiers are never returned.

Path parameters

account_idstringrequired

The ID of the business account.

idstringrequired

The ID of the business verification.

Returns

The business-verification run.

GET/v1/accounts/{account_id}/business_verifications/{id}

curl --request GET \
  --url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/business_verifications/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'

RESPONSE

{
  "id": "00000000-0000-4000-8000-000000000001",
  "object": "business_verification",
  "status": "failed",
  "failure_type": "verification_rejected",
  "retriable": false,
  "category": "terminal",
  "account": "00000000-0000-4000-8000-000000000002",
  "livemode": false,
  "created": 1745107200,
  "completed": 1745107200,
  "review_opened": null,
  "review_resolved": null
}