Get customer's verification status

curl --request GET \
  --url https://api.paystack.com/v1/customers/{customerId}/verifications \
  --header 'Authorization: Bearer <token>'

{
  "status": true,
  "message": "Verification session fetched successfully",
  "code": "ok",
  "data": {
    "id": "kyc_01HXYZABC1234567890ABCDEFG",
    "customer_id": "cust_01HXYZABC1234567890ABCDEFG",
    "status": "pending",
    "tier_requested": "tier_1",
    "tier_current": "tier_0",
    "hosted_url": "http://localhost:3000/_mock/verify/kyc_01HXYZABC1234567890ABCDEFG",
    "hosted_url_expires_at": "2026-04-22T03:00:00.000Z",
    "created_at": "2026-04-22T02:00:00.000Z",
    "updated_at": "2026-04-22T02:00:00.000Z"
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Customers

Get customer's verification status

Return the current or most recent verification session for the customer.

The response includes hosted_url — the hosted verification URL the customer must open to complete verification — alongside hosted_url_expires_at. Callers can reuse the URL while the session is still pending and the expiry is in the future; once it expires, start a fresh session via POST /v1/customers/{customer_id}/verifications.

If no session exists yet, the response is a 404 not_found whose meta.next_steps points the caller at POST /v1/customers/{customer_id}/verifications to create one.

Path

customer_id — required. The cust_… external id of an existing customer that belongs to the calling integration.

404 cases

Customer does not exist or belongs to a different integration.
Customer has never had a verification session created — meta.next_steps.action guides the caller to start one via POST /v1/customers/{customer_id}/verifications.

Example

GET /v1/customers/cust_01HXYZ/verifications

GET

customers

{customerId}

verifications

Get customer's verification status

curl --request GET \
  --url https://api.paystack.com/v1/customers/{customerId}/verifications \
  --header 'Authorization: Bearer <token>'

{
  "status": true,
  "message": "Verification session fetched successfully",
  "code": "ok",
  "data": {
    "id": "kyc_01HXYZABC1234567890ABCDEFG",
    "customer_id": "cust_01HXYZABC1234567890ABCDEFG",
    "status": "pending",
    "tier_requested": "tier_1",
    "tier_current": "tier_0",
    "hosted_url": "http://localhost:3000/_mock/verify/kyc_01HXYZABC1234567890ABCDEFG",
    "hosted_url_expires_at": "2026-04-22T03:00:00.000Z",
    "created_at": "2026-04-22T02:00:00.000Z",
    "updated_at": "2026-04-22T02:00:00.000Z"
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Authorizations

Authorization

string

header

required

API key issued during merchant onboarding.

Path Parameters

customerId

string

required

Pattern: [^\/#\?]+?

Response

Verification session fetched successfully

status

enum<boolean>

required

Available options:

true

Example:

true

message

string

required

Human-readable summary

Example:

"Verification session fetched successfully"

code

enum<string>

required

Available options:

ok

Example:

"ok"

data

object

required

Show child attributes