Docs

API reference / KYC

Start or resume identity verification

POST/v1/users/{id}/kyc-sessions

API key requiredSupports Idempotency-Key

Starts the identity verification (KYC) onboarding of a user, or resumes it, and returns a session with a url to send the end user to and its expires_at. Calling it again while verification is in progress returns the current session (idempotent); a user whose KYC is rejected can start again. In sandbox, the session is simulated locally (url is null, the status becomes pending); complete it with POST /v1/sandbox/users/{id}/simulate. In live, the final result is delivered by the kyc.approved / kyc.rejected events. Live sessions must be enabled for the platform, otherwise 409 feature_unavailable. Accepts Idempotency-Key.

Authentication#

Send a secret API key as Authorization: Bearer <key>. Both tp_test_… and tp_live_… keys work; the key decides which environment you read and write. See Authentication.

Parameters#

Path

Path parameters
NameTypeDescription
idrequiredstringIdentifier of the user.Pattern ^\d{1,9}$

Headers

Header parameters
NameTypeDescription
Idempotency-KeystringIdempotency key (1 to 255 characters, UUID v4 recommended). Responses are replayed for 24 h.

See Idempotency.

Responses#

200The verification session.

Headers

  • X-Request-Id Request identifier.
  • X-RateLimit-Limit Quota of the current window.
  • X-RateLimit-Remaining Requests remaining in the window.
  • X-RateLimit-Reset Seconds before the quota renews.

Body

  • objectstringrequired

    always "kyc_session"

    Example "kyc_session"

  • idstringrequired

    Opaque identifier of the session.

    Example "ks_5b1f0c2e7a4d9e3f8a6b1c0d"

  • user_idstringrequired

    User concerned.

    Example "4821"

  • statusstringrequired

    KYC status of the user when the session was returned.

    One ofnonependingapprovedrejected

    Example "pending"

  • urlstring | nullrequired

    Link to send the end user to, to complete identity verification. null in sandbox (simulated session) or when a session is already in progress and no new link is available.

    Example "https://verify.example.com/session/abc123"

  • expires_atstring | nullrequired

    Moment the link stops being valid.

    format: date-time

    Example "2026-10-09T09:30:00.000Z"

  • livemodebooleanrequired

    true for a live key, false for a sandbox key.

    Example false

Example 200 response
{
  "object": "kyc_session",
  "id": "ks_5b1f0c2e7a4d9e3f8a6b1c0d",
  "user_id": "4821",
  "status": "pending",
  "url": "https://verify.example.com/session/abc123",
  "expires_at": "2026-10-09T09:30:00.000Z",
  "livemode": false
}
400Invalid request (malformed JSON, unknown cursor, invalid Idempotency-Key header).

Example: invalid_cursor

Example 400 response
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_cursor",
    "message": "starting_after: unknown cursor",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}
401Missing, invalid or revoked API key.

Example: missing_api_key

Example 401 response
{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Provide your API key as \"Authorization: Bearer <key>\"",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Example: invalid_api_key

Example 401 response
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key is invalid",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Example: api_key_revoked

Example 401 response
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_revoked",
    "message": "This API key has been revoked",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}
403Organization suspended, live access not enabled, or sandbox-only route.

Example: organization_suspended

Example 403 response
{
  "error": {
    "type": "permission_error",
    "code": "organization_suspended",
    "message": "Your organization is suspended. Contact Tilt Pay support.",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Example: live_not_enabled

Example 403 response
{
  "error": {
    "type": "permission_error",
    "code": "live_not_enabled",
    "message": "Live access has not been enabled for your organization yet",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Example: sandbox_only

Example 403 response
{
  "error": {
    "type": "permission_error",
    "code": "sandbox_only",
    "message": "This route is only available with a sandbox API key",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}
404Resource not found (or belonging to another project or environment).

Example: user_not_found

Example 404 response
{
  "error": {
    "type": "invalid_request_error",
    "code": "user_not_found",
    "message": "User not found",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}
409Conflict with the state of the resource, or the original idempotent request is still in progress.

Example: user_already_exists

Example 409 response
{
  "error": {
    "type": "invalid_request_error",
    "code": "user_already_exists",
    "message": "A user with this phone number already exists",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}
422Invalid parameter, or Idempotency-Key reused with a different body.

Example: validation_error

Example 422 response
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "phone: has an invalid format",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Example: idempotency_key_reuse

Example 422 response
{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reuse",
    "message": "This Idempotency-Key was already used with a different request",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}
429Rate limit exceeded. Retry after the Retry-After delay (seconds).

Example: rate_limit_exceeded

Example 429 response
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry after the delay in Retry-After.",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}
500Internal error. Retry; give request_id to support if it persists.

Example: internal_error

Example 500 response
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Headers on every response

  • X-Request-Id Identifier of the request, also present in error bodies. Give it to support.
  • X-API-Version Version of the API that answered.
  • X-RateLimit-Limit / -Remaining / -Reset Quota of your key for the current window. See Rate limits.

Errors#

Errors share one format, described in Errors. Branch your code on error.code.

Errors this route can return
StatusCodeMeaning
400invalid_cursorInvalid request (malformed JSON, unknown cursor, invalid Idempotency-Key header).
401missing_api_keyMissing, invalid or revoked API key.
401invalid_api_keyMissing, invalid or revoked API key.
401api_key_revokedMissing, invalid or revoked API key.
403organization_suspendedOrganization suspended, live access not enabled, or sandbox-only route.
403live_not_enabledOrganization suspended, live access not enabled, or sandbox-only route.
403sandbox_onlyOrganization suspended, live access not enabled, or sandbox-only route.
404user_not_foundUnknown user (or belonging to another project or environment).
409user_already_existsConflict with the state of the resource, or the original idempotent request is still in progress.
409invalid_stateKYC is already approved for this user.
409user_suspendedThe user is suspended.
409feature_unavailableLive identity verification sessions are not enabled yet.
422validation_errorInvalid parameter, or Idempotency-Key reused with a different body.
422idempotency_key_reuseInvalid parameter, or Idempotency-Key reused with a different body.
429rate_limit_exceededRate limit exceeded. Retry after the Retry-After delay (seconds).
500internal_errorInternal error. Retry; give request_id to support if it persists.