Documentation / SDK v1

KYC

Invite recipients to complete KYC verification, manage invites, and list recipients via /sdk/v1.

kyc · json
{
  "connectionId": "SDKKYC_...",
  "email": "recipient@example.com",
  "inviteStatus": "sent",
  "inviteExpiresAt": "2026-03-01T00:00:00.000Z",
  "inviteSentAt": "2026-02-22T00:00:00.000Z",
  "inviteAcceptedAt": null,
  "kycStatus": "invited",
  "kycCurrentStep": null,
  "kycCompletedSteps": [],
  "updatedAt": "2026-02-22T00:00:00.000Z"
}
All documentation

All endpoints below require:

  • X-Application-Id
  • X-Api-Key

KYC connection object

Endpoints that return a connection use this shape:

{
  "connectionId": "SDKKYC_...",
  "email": "recipient@example.com",
  "inviteStatus": "sent",
  "inviteExpiresAt": "2026-03-01T00:00:00.000Z",
  "inviteSentAt": "2026-02-22T00:00:00.000Z",
  "inviteAcceptedAt": null,
  "kycStatus": "invited",
  "kycCurrentStep": null,
  "kycCompletedSteps": [],
  "updatedAt": "2026-02-22T00:00:00.000Z"
}

inviteStatus values

Value Meaning
none No invite sent yet
sent Invite email dispatched
canceled Invite was canceled before acceptance
accepted Recipient accepted the invite
expired Invite expired before acceptance

kycStatus values

Value Meaning
invited Waiting for the recipient to begin
email_verified Recipient verified their email
flow_started KYC flow initiated
in_progress Recipient is completing KYC steps, including while verification is under review or being resubmitted
complete KYC finished successfully (both steps are done)
canceled KYC was canceled
deleted Connection was deleted
error Verification was declined, or something went wrong during the flow

KYC steps

kycCurrentStep and kycCompletedSteps use these step names:

Value Meaning
id-verification Identity verification
compliance Tax details
redirect Return to your app after verification (some accounts only)

The order of the steps can differ by account, so do not rely on it. kycStatus is complete once id-verification and compliance are done.

POST /sdk/v1/kyc/invite

Send a KYC invite to a recipient. If the recipient already has a pending invite, the invite is refreshed.

The link in the invite email opens Grade's hosted verification. Depending on your account, that is Grade's KYC page or the Grade creator app. The API, fields, and statuses are the same either way.

If the recipient already completed verification with Grade, the response can come back with kycStatus complete right away, and no email is sent.

Body

  • email (required; valid email address)
  • idempotencyKey (optional; max 128 characters)
{
  "email": "recipient@example.com",
  "idempotencyKey": "unique-key-123"
}

Response

{
  "success": true,
  "data": {
    "connectionId": "SDKKYC_...",
    "email": "recipient@example.com",
    "inviteStatus": "sent",
    "inviteExpiresAt": "2026-03-01T00:00:00.000Z",
    "inviteSentAt": "2026-02-22T00:00:00.000Z",
    "inviteAcceptedAt": null,
    "kycStatus": "invited",
    "kycCurrentStep": null,
    "kycCompletedSteps": [],
    "updatedAt": "2026-02-22T00:00:00.000Z"
  }
}

Invite allowance

Each agency has a lifetime allowance of new KYC invites, 10 by default, shared by all of its applications.

  • Each new recipient email uses one invite.
  • Resending an invite to an existing connection is free, including after you cancel it.
  • Deleting a connection does not give its invite back, so inviting the same email again later uses a new one.

When the allowance is used up, inviting a new recipient email returns 429 with code KYC_INVITE_ALLOWANCE_EXCEEDED and no Retry-After header. Resending to existing connections keeps working. Contact support@usegrade.com to raise the allowance.

Common errors

  • 400: missing or invalid email
  • 400: idempotencyKey exceeds 128 characters
  • 401: missing or invalid SDK headers
  • 409: the connection for this email is already complete (KYC_ALREADY_COMPLETE)
  • 429: invite cooldown active; check the Retry-After response header (KYC_INVITE_COOLDOWN)
  • 429: invite allowance used up; there is no Retry-After header, see Invite allowance (KYC_INVITE_ALLOWANCE_EXCEEDED)

Use the code field to tell the two 429 responses apart. Only KYC_INVITE_COOLDOWN can succeed by waiting and retrying.

POST /sdk/v1/kyc/cancel

Cancel a pending KYC invite. Provide either connectionId or email to identify the invite.

Canceling stops tracking on the API side only. A recipient who already has the link may still finish verification with Grade, but the connection keeps reporting canceled.

Body

  • connectionId (required if email is omitted)
  • email (required if connectionId is omitted)
{
  "connectionId": "SDKKYC_..."
}

Response

{
  "success": true,
  "data": {
    "connectionId": "SDKKYC_...",
    "email": "recipient@example.com",
    "inviteStatus": "canceled",
    "inviteExpiresAt": "2026-03-01T00:00:00.000Z",
    "inviteSentAt": "2026-02-22T00:00:00.000Z",
    "inviteAcceptedAt": null,
    "kycStatus": "canceled",
    "kycCurrentStep": null,
    "kycCompletedSteps": [],
    "updatedAt": "2026-02-22T12:00:00.000Z"
  }
}

Common errors

  • 400: neither connectionId nor email provided
  • 401: missing or invalid SDK headers
  • 409: invite is not in a cancelable state (KYC_INVITE_NOT_CANCELABLE)

GET /sdk/v1/kyc/recipients

List KYC connections for your application.

Query parameters

  • page (default 1)
  • limit (default 50)

Response

{
  "success": true,
  "data": [
    {
      "connectionId": "SDKKYC_...",
      "email": "recipient@example.com",
      "inviteStatus": "accepted",
      "inviteExpiresAt": "2026-03-01T00:00:00.000Z",
      "inviteSentAt": "2026-02-22T00:00:00.000Z",
      "inviteAcceptedAt": "2026-02-23T10:00:00.000Z",
      "kycStatus": "complete",
      "kycCurrentStep": null,
      "kycCompletedSteps": ["id-verification", "compliance"],
      "updatedAt": "2026-02-23T11:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "totalPages": 1, "totalItems": 1, "hasMore": false }
}

DELETE /sdk/v1/kyc/recipients/:connectionId

Permanently delete a KYC connection.

Deleting stops tracking on the API side only. A recipient who already has the link may still finish verification with Grade, but the connection no longer appears in GET /sdk/v1/kyc/recipients. Deleting does not give the invite back to your invite allowance.

Path parameters

  • connectionId (required)

Response

{
  "success": true
}

Common errors

  • 400: missing connectionId
  • 401: missing or invalid SDK headers

Describe your program.

Grade turns it into a program it can track and pay.