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

# Identity methods

> Create, update, and verify a customer identity, and upload identity documents, for Identity API integrations.

Use the identity methods to run KYC for Identity API integrations: capture the
required customer data in your own UI, submit it through the SDK, and bring the
customer to a verified state. The client handles authentication for you — no
raw access token is required.

The six methods wrap the Identity API endpoints and follow the same `Result`
pattern as the rest of the client:

| Method                                                  | Endpoint                                             | Purpose                                         |
| ------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------- |
| [`createIdentity()`](#clientcreateidentity)             | `POST /platform/v1/identities`                       | Create an identity for the connected customer.  |
| [`getIdentity()`](#clientgetidentity)                   | `GET /platform/v1/identities/{id}`                   | Fetch the identity, including its requirements. |
| [`updateIdentity()`](#clientupdateidentity)             | `PATCH /platform/v1/identities/{id}`                 | Submit one or more outstanding requirements.    |
| [`verifyIdentity()`](#clientverifyidentity)             | `POST /platform/v1/identities/{id}/verifications`    | Submit the identity for verification.           |
| [`getIdentityUploadUrl()`](#clientgetidentityuploadurl) | `POST /platform/v1/identities/{id}/files/upload-url` | Issue a presigned URL for a document upload.    |
| [`submitIdentityFiles()`](#clientsubmitidentityfiles)   | `POST /platform/v1/identities/{id}/files`            | Confirm previously uploaded documents.          |

<Callout icon="circle-info" iconType="regular">
  The identity methods require an authenticated client. Run
  [`client.getConnection()`](/platform/sdk-reference/web/get-connection) with
  `skipKyc: true` first, and authenticate the customer with
  [`client.setupAuth()`](/platform/sdk-reference/web/setup-auth) when the status
  is `"connectionRequired"`.
</Callout>

For the field and document requirements by country, see [What to
capture](/platform/guides/identity/what-to-capture).

## `client.createIdentity()`

Create an identity for the connected customer. The response lists the
requirements you need to fulfil before verification.

```ts Create an identity theme={null}
const result = await client.createIdentity({
  residentialAddress: { country: "USA" },
  capabilities: [{ product: "ramps" }],
});

if (!result.ok) {
  // Handle error
  console.error(result.error.code, result.error.message);
  return;
}

if (result.value.data === null) {
  // The customer is already onboarded — no outstanding requirements.
  return;
}

console.log(result.value.data.id, result.value.data.requirements);
```

### `createIdentity()` parameters

| Field                        | Type                     | Required | Description                                                                               |
| ---------------------------- | ------------------------ | -------- | ----------------------------------------------------------------------------------------- |
| `residentialAddress.country` | `string`                 | ✅        | The customer's country of residence as an ISO 3166-1 alpha-3 code (for example, `"USA"`). |
| `capabilities`               | `{ product: "ramps" }[]` | ✅        | The capabilities to unlock for the customer. Must contain at least one entry.             |

### `createIdentity()` result

Returns a `Result<{ data: `[`Identity`](#identity)` | null }, DevPlatformApiError>`.
`data` is `null` (HTTP 204) when the customer has no outstanding requirements —
they are already onboarded.

## `client.getIdentity()`

Fetch the identity, including the current status and requirement states.

```ts Get an identity theme={null}
const result = await client.getIdentity(identityId);

if (result.ok) {
  console.log(result.value.data.status, result.value.data.requirements);
}
```

### `getIdentity()` parameters

| Field | Type     | Required | Description              |
| ----- | -------- | -------- | ------------------------ |
| `id`  | `string` | ✅        | The identity identifier. |

### `getIdentity()` result

Returns a `Result<{ data: `[`Identity`](#identity)` }, DevPlatformApiError>`.

## `client.updateIdentity()`

Submit one or more outstanding requirements on the identity. Each top-level
field maps to a requirement category — submit the categories listed as
`incomplete` in [`requirements`](#requirements).

```ts Update an identity theme={null}
const result = await client.updateIdentity(identityId, {
  basicDetails: {
    firstName: "Ada",
    lastName: "Lovelace",
    dateOfBirth: "1990-12-10",
  },
  residentialAddress: {
    street: "123 Main St",
    locality: "San Francisco",
    administrativeArea: "CA",
    postalCode: "94105",
    country: "USA",
  },
  phoneNumber: { number: "+12025550143" },
});
```

### `updateIdentity()` parameters

| Field                | Type     | Required | Description                                                                              |
| -------------------- | -------- | -------- | ---------------------------------------------------------------------------------------- |
| `id`                 | `string` | ✅        | The identity identifier.                                                                 |
| `basicDetails`       | `object` |          | The customer's name, nationality, and date of birth (`YYYY-MM-DD`).                      |
| `residentialAddress` | `object` |          | The customer's residential address. Country codes are ISO 3166-1 alpha-3.                |
| `phoneNumber`        | `object` |          | The customer's phone number in E.164 format (for example, `"+12025550143"`).             |
| `taxIdentifiers`     | `array`  |          | Tax identifiers: `{ type: "ssn" \| "cpf", value }` or `{ type: "tin", country, value }`. |

### `updateIdentity()` result

Returns a `Result<{ data: `[`Identity`](#identity)` }, DevPlatformApiError>`
reflecting the updated requirement states.

## `client.verifyIdentity()`

Submit the identity for verification once all requirements are complete.

```ts Verify an identity theme={null}
const result = await client.verifyIdentity(identityId);

if (!result.ok) {
  // requirements_incomplete: submit the missing requirements first.
  console.error(result.error.code, result.error.message);
  return;
}

switch (result.value.data.status) {
  case "approved":
    // The customer is verified.
    break;
  case "processing":
    // Verification is running — poll getIdentity() for the outcome.
    break;
  case "challengeRequired":
    // Render the challenge frame with setupChallenge().
    console.log(result.value.data.challenge.url);
    break;
}
```

When the status is `"challengeRequired"`, pass `challenge.url` to
[`client.setupChallenge()`](/platform/sdk-reference/web/setup-challenge). The
challenge completes with `flow: "identity"` and the `identityId`.

### `verifyIdentity()` parameters

| Field | Type     | Required | Description              |
| ----- | -------- | -------- | ------------------------ |
| `id`  | `string` | ✅        | The identity identifier. |

### `verifyIdentity()` result

Returns a `Result<{ data: IdentityVerificationResponse }, DevPlatformApiError>`.

| Field       | Type                                                    | Required | Description                                                                       |
| ----------- | ------------------------------------------------------- | -------- | --------------------------------------------------------------------------------- |
| `status`    | `"approved"` \| `"processing"` \| `"challengeRequired"` | ✅        | The verification outcome.                                                         |
| `challenge` | `{ url: string; expiresAt: string }`                    |          | Present when `status` is `"challengeRequired"`. Pass `url` to `setupChallenge()`. |

## `client.getIdentityUploadUrl()`

Issue a presigned URL to upload an identity document. Upload the file with an
HTTP `PUT` to the returned `url`, sending the returned `headers`.

```ts Upload a document theme={null}
const urlResult = await client.getIdentityUploadUrl(identityId, {
  fileType: "passport",
  mimeType: "image/jpeg",
});

if (!urlResult.ok) return;

const { uploadId, url, headers } = urlResult.value.data;

await fetch(url, {
  method: "PUT",
  headers,
  body: passportImageBlob,
});
```

### `getIdentityUploadUrl()` parameters

| Field      | Type     | Required | Description                                                                                                                            |
| ---------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `id`       | `string` | ✅        | The identity identifier.                                                                                                               |
| `fileType` | `string` | ✅        | One of `"drivingLicence"`, `"nationalIdentityCard"`, `"passport"`, `"residencePermit"`, `"selfie"`, `"proofOfAddress"`.                |
| `side`     | `string` |          | `"front"` or `"back"`. Required for two-sided documents (`drivingLicence`, `nationalIdentityCard`, `residencePermit`); omit otherwise. |
| `mimeType` | `string` | ✅        | `"image/jpeg"`, `"image/png"`, or `"application/pdf"`. Must match the `Content-Type` header you send on the upload request.            |

### `getIdentityUploadUrl()` result

Returns a `Result<{ data: IdentityFileUploadUrl }, DevPlatformApiError>`.

| Field       | Type     | Required | Description                                                    |
| ----------- | -------- | -------- | -------------------------------------------------------------- |
| `uploadId`  | `string` | ✅        | The upload identifier to confirm with `submitIdentityFiles()`. |
| `url`       | `string` | ✅        | The presigned upload URL.                                      |
| `expiresAt` | `string` | ✅        | An ISO 8601 timestamp for when the URL expires.                |
| `headers`   | `object` | ✅        | Headers to send on the upload request (`Content-Type`).        |

## `client.submitIdentityFiles()`

Confirm one or more uploaded documents so MoonPay processes them against the
identity's requirements.

```ts Submit uploaded documents theme={null}
const result = await client.submitIdentityFiles(identityId, {
  files: [{ uploadId, fileType: "passport" }],
});

if (result.ok) {
  console.log(result.value.data.requirements);
}
```

### `submitIdentityFiles()` parameters

| Field   | Type     | Required | Description                                                                               |
| ------- | -------- | -------- | ----------------------------------------------------------------------------------------- |
| `id`    | `string` | ✅        | The identity identifier.                                                                  |
| `files` | `array`  | ✅        | The uploads to confirm: `{ uploadId, fileType, side? }`, matching the issued upload URLs. |

### `submitIdentityFiles()` result

Returns a `Result<{ data: `[`Identity`](#identity)` }, DevPlatformApiError>`
reflecting the updated requirement states.

## Shared types

### `Identity`

| Field          | Type                                 | Required | Description                                                                            |
| -------------- | ------------------------------------ | -------- | -------------------------------------------------------------------------------------- |
| `id`           | `string`                             | ✅        | The identity identifier.                                                               |
| `status`       | [`IdentityStatus`](#identitystatus)  | ✅        | The identity's place in the KYC lifecycle.                                             |
| `capabilities` | `{ product: "ramps" }[]`             | ✅        | The capabilities requested for the customer.                                           |
| `requirements` | [`Requirements`](#requirements)      | ✅        | Outstanding and completed requirements, keyed by category.                             |
| `challenge`    | `{ url: string; expiresAt: string }` |          | Present only when `status` is `"challengeRequired"`. Pass `url` to `setupChallenge()`. |
| `createdAt`    | `string`                             | ✅        | An ISO 8601 creation timestamp.                                                        |
| `updatedAt`    | `string`                             | ✅        | An ISO 8601 last-update timestamp.                                                     |

### `IdentityStatus`

`"created"`, `"collecting"`, `"verifying"`, `"challengeRequired"`,
`"approved"`, `"rejected"`, `"manualReview"`, or `"blocked"`.

### `Requirements`

Each category is present when it applies to the customer's jurisdiction, with a
`status` of `"incomplete"` or `"complete"` and, for field-based categories, the
`requiredFields` still outstanding.

| Category             | Fulfilled by                                       |
| -------------------- | -------------------------------------------------- |
| `basicDetails`       | `updateIdentity()`                                 |
| `residentialAddress` | `updateIdentity()`                                 |
| `phoneNumber`        | `updateIdentity()`                                 |
| `taxIdentifiers`     | `updateIdentity()`                                 |
| `identityDocuments`  | `getIdentityUploadUrl()` + `submitIdentityFiles()` |
| `selfie`             | `getIdentityUploadUrl()` + `submitIdentityFiles()` |
| `proofOfAddress`     | `getIdentityUploadUrl()` + `submitIdentityFiles()` |

### Errors

All identity methods return the standard MoonPay Platform API error shape,
`DevPlatformApiError`, with `code`, `message`, and optional field-level
`errors`. Notable codes: `"requirements_incomplete"` when verifying too early,
`"verification_rejected"` on a terminal rejection, and `"country_mismatch"`
when submitted data conflicts with the declared country.