> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.usegrade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# KYC

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

All endpoints below require:

* `X-Application-Id`
* `X-Api-Key`

## KYC connection object

Endpoints that return a connection use this shape:

```json theme={null}
{
  "connectionId": "conn_...",
  "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    |
| `complete`       | KYC finished successfully            |
| `canceled`       | KYC was canceled                     |
| `deleted`        | Connection was deleted               |
| `error`          | Something went wrong during the flow |

## POST /sdk/v1/kyc/invite

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

### Body

* `email` (required; valid email address)
* `idempotencyKey` (optional; max 128 characters)

```json theme={null}
{
  "email": "recipient@example.com",
  "idempotencyKey": "unique-key-123"
}
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "connectionId": "conn_...",
    "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"
  }
}
```

### Common errors

* `400`: missing or invalid `email`
* `400`: `idempotencyKey` exceeds 128 characters
* `401`: missing or invalid SDK headers
* `409`: invite already completed (`KYC_INVITE_ALREADY_COMPLETE`)
* `429`: invite cooldown active; check the `Retry-After` response header (`KYC_INVITE_COOLDOWN`)

## POST /sdk/v1/kyc/cancel

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

### Body

* `connectionId` (required if `email` is omitted)
* `email` (required if `connectionId` is omitted)

```json theme={null}
{
  "connectionId": "conn_..."
}
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "connectionId": "conn_...",
    "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

```json theme={null}
{
  "success": true,
  "data": [
    {
      "connectionId": "conn_...",
      "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": ["identity", "address", "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.

### Path parameters

* `connectionId` (required)

### Response

```json theme={null}
{
  "success": true
}
```

### Common errors

* `400`: missing `connectionId`
* `401`: missing or invalid SDK headers