All documentation
Documentation
All endpoints below require:
X-Application-IdX-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 invalidemail400:idempotencyKeyexceeds 128 characters401: missing or invalid SDK headers409: the connection for this email is already complete (KYC_ALREADY_COMPLETE)429: invite cooldown active; check theRetry-Afterresponse header (KYC_INVITE_COOLDOWN)429: invite allowance used up; there is noRetry-Afterheader, 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 ifemailis omitted)email(required ifconnectionIdis 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: neitherconnectionIdnoremailprovided401: missing or invalid SDK headers409: 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(default1)limit(default50)
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: missingconnectionId401: missing or invalid SDK headers
