> ## 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.

# Customer

> A customer and their KYC standing

Returned by the [Customer API](/platform/guides/customer-api) endpoints. The `kyc` object tells you whether the customer can transact, what's outstanding, and how to submit it.

## Properties

| Property             | Type          | Required | Description                                                                                                               |
| -------------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `id`                 | string (uuid) | Yes      | The customer's unique MoonPay identifier                                                                                  |
| `externalCustomerId` | string        | Yes      | Your identifier for this customer, if one was supplied. `null` when the customer connected without an external identifier |
| `kyc`                | object        | Yes      | KYC details for the customer                                                                                              |

## KYC

| Property       | Type   | Required | Description                                                                                             |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
| `status`       | string | Yes      | The customer's KYC standing with you. See [KYC status](#kyc-status)                                     |
| `requirements` | object | Yes      | Outstanding and completed KYC requirements, keyed by category. See [Requirements](#requirements)        |
| `challenge`    | object | No       | Hosted challenge you must surface to the customer to complete verification. See [Challenge](#challenge) |

## KYC status

| Value         | Description                                                                                     |
| ------------- | ----------------------------------------------------------------------------------------------- |
| `not_created` | No KYC session exists yet for this customer with your account.                                  |
| `collecting`  | The customer has outstanding requirements to submit.                                            |
| `verifying`   | MoonPay is processing the submitted data. No action is needed from you or the customer.         |
| `active`      | KYC is complete. The customer is in good standing.                                              |
| `unavailable` | KYC cannot proceed for this customer (for example, an unsupported region, or a closed account). |

## Requirements

Each key is a requirement category. Only categories that apply to the customer are present. Each entry has the same shape:

| Property         | Type   | Required | Description                                                                                                                                    |
| ---------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`         | string | Yes      | `incomplete` or `complete`                                                                                                                     |
| `requiredFields` | array  | No       | When `status` is `incomplete`, the outstanding fields the customer must provide. Omitted when the category does not surface field-level detail |

| Category             | Description                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------- |
| `basicDetails`       | The customer's basic personal details (first name, last name, date of birth, nationality) |
| `residentialAddress` | The customer's residential address                                                        |
| `identityDocuments`  | Identity document submission (passport, driver's license, residence permit)               |
| `selfie`             | Selfie photo submission                                                                   |
| `taxIdentifiers`     | Tax identifier submission (SSN, CPF, TIN)                                                 |
| `proofOfAddress`     | Proof-of-address document submission                                                      |
| `phoneNumber`        | The customer's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format        |
| `questionnaires`     | Due-diligence questionnaires the customer must complete                                   |

For the fields and documents each country requires, see [KYC data requirements](/platform/guides/kyc-data-requirements).

## Challenge

| Property    | Type               | Required | Description                                                                            |
| ----------- | ------------------ | -------- | -------------------------------------------------------------------------------------- |
| `url`       | string             | Yes      | Fully-formed challenge URL. Render it directly; the URL embeds the challenge token     |
| `expiresAt` | string (date-time) | Yes      | When the challenge URL expires. Surface the challenge to the customer before this time |

## Example

```json theme={null}
{
  "id": "c1a2b3c4-0000-4000-8000-000000000000",
  "externalCustomerId": "your_user_id",
  "kyc": {
    "status": "collecting",
    "requirements": {
      "basicDetails": { "status": "complete" },
      "residentialAddress": {
        "status": "incomplete",
        "requiredFields": ["street", "locality", "postalCode"]
      },
      "identityDocuments": { "status": "incomplete" }
    }
  }
}
```