GET /customers/:id/kyc/state

The current verification state for one customer, where they stand in KYC (individuals) or KYB (businesses), what's missing, what hosted link (if any) is outstanding. The response is a polymorphic envelope: a type discriminator plus a nested state sub-object. The state's field set differs only in the kyc_status / kyb_status and kyc_link / kyb_link names, the rest is identical.

This endpoint does not hit any external system, it returns the cached state, updated on submit, on webhook receipt, and on explicit POST /customers/:id/kyc/resync calls. last_synced_at reflects the freshness.

If the customer hasn't been submitted yet, the endpoint still returns 200 with a draft state (status draft, no link).

Response 200

A CustomerState. Example: an individual under review.

{
  "type": "individual",
  "state": {
    "kyc_status": "under_review",
    "kyc_link": {
      "url": "https://onboarding.example.com/...",
      "expires_at": "2026-05-05T11:00:00.000Z"
    },
    "missing_fields": [
      "identity.date_of_birth"
    ],
    "last_synced_at": "2026-05-04T08:00:00.000Z",
    "rejection_reason": null,
    "pending_rfi": false,
    "last_submitted_at": "2026-05-04T07:55:00.000Z",
    "resubmit_available": false
  }
}

For businesses the response carries state.kyb_status and state.kyb_link in place of the kyc_* names, the rest is identical.

Errors

• 404: unknown customer id (or the customer belongs to a different org).

Example

curl "$SEISMIC_ORCHESTRATION_URL/v0/customers/$CUSTOMER_ID/kyc/state" \
  -H "Api-Key: $SEISMIC_ORCHESTRATION_API_KEY"