KYC

All endpoints below require:

X-Application-Id
X-Api-Key

KYC connection object

Endpoints that return a connection use this shape:

{
  "connectionId": "SDKKYC_...",
  "email": "[email protected]",
  "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": "[email protected]",
  "idempotencyKey": "unique-key-123"
}

Response

{
  "success": true,
  "data": {
    "connectionId": "SDKKYC_...",
    "email": "[email protected]",
    "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 [email protected] 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": "[email protected]",
    "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": "[email protected]",
      "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

SDK v1

Campaign management

KYC connection object

`inviteStatus` values

`kycStatus` values

KYC steps

POST /sdk/v1/kyc/invite

Body

Response

Invite allowance

Common errors

POST /sdk/v1/kyc/cancel

Body

Response

Common errors

GET /sdk/v1/kyc/recipients

Query parameters

Response

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

Path parameters

Response

Common errors

​KYC connection object

​inviteStatus values

​kycStatus values

​KYC steps

​POST /sdk/v1/kyc/invite

​Body

​Response

​Invite allowance

​Common errors

​POST /sdk/v1/kyc/cancel

​Body

​Response

​Common errors

​GET /sdk/v1/kyc/recipients

​Query parameters

​Response

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

​Path parameters

​Response

​Common errors

KYC connection object

`inviteStatus` values

`kycStatus` values

KYC steps

POST /sdk/v1/kyc/invite

Body

Response

Invite allowance

Common errors

POST /sdk/v1/kyc/cancel

Body

Response

Common errors

GET /sdk/v1/kyc/recipients

Query parameters

Response

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

Path parameters

Response

Common errors