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

# Retrieve KYC

This guide covers Meld's **Retrieve KYC Data** product

This product allows you to pull verified KYC data of your users as either raw applicant data + document images, or a KYC provider share token.

This product is helpful for the use case where your user has already KYCed with Meld or one of Meld's onramps, and now you need to verify that user for a separate product using your own KYC provider without asking them to reenter their KYC data.

Meld does not store raw KYC field values or document images. Data is fetched from the KYC provider on export. Logs redact KYC fields entirely; Meld only retains metadata (customer id, timestamps, requesting party). Always obtain user consent before retrieving KYC on their behalf.

## Summary of the steps

1. Look up the Meld `customerId` for a user who has already been KYC-approved
2. Get the user's consent to share their KYC data with the receiving product
3. Call the export endpoint — either a share token or raw data plus documents
4. Pass the result to your own KYC provider integration

## Before you begin

* You have contacted your Meld account manager to enable this product for you
* You have an agreement with the onramps to be able to fetch KYC data from them
* You can store the Meld `customerId` against each of your users
* The Meld `customerId` is tied to the email address of the user, and you have OTPed the user to prove they have access to that email
* You gather end-user consent in your UI before sharing KYC data with Meld, yourself, and your downstream partners

## Flows at a glance

| Flow                         | Endpoint                                           | Content type                        | API Response Contains                  |
| ---------------------------- | -------------------------------------------------- | ----------------------------------- | -------------------------------------- |
| Export as KYC provider token | `POST /accounts/customers/{customerId}/kyc/export` | JSON in / JSON out                  | `applicantId` + `shareToken`           |
| Export as raw data           | `POST /accounts/customers/{customerId}/kyc/export` | JSON in / `multipart/form-data` out | JSON `data` part + document file parts |

Raw-data export returns `multipart/form-data`, not JSON. Parse the response as multipart: a JSON `data` part plus one file part per document image.

For broader Unified KYC context (reusing KYC across onramps), see [Unified KYC](/docs/stablecoins/unified-kyc).

## Step 1: Retrieve Meld customer

Call `POST /accounts/customers` once per user. This will create the Meld customer if they don't exist, or fetch the existing customer if they exist.

#### Request

```json theme={null}
{
  "name": {
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "externalCustomerId": "your-internal-user-id",
  "email": "jane.doe@example.com"
}
```

| Field                | Notes                                                                                         |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `externalCustomerId` | Your internal user id (optional but recommended). Response echoes it as `externalCustomerId`. |

#### Response

```json theme={null}
{
  "id": "WmYumpKThCLWdgdK4fu2oh",
  "accountId": "W932jkkjn2jnjn",
  "name": {
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "externalCustomerId": "your-internal-user-id",
  "email": "jane.doe@example.com"
}
```

Store `id` as the Meld `customerId`. You need it for submit and export.

With `Meld-Version` dated `2023-04-01` or later, the customer response also includes `serviceProviderCustomers` (including KYC status after submit).

## Step 2: Retrieve KYC

Call:

`POST /accounts/customers/{customerId}/kyc/export`

Nothing is persisted during retrieval. The customer must already have been KYCed by Meld or by the onramp; otherwise the API returns `404`. Choose a mode:

*Note that the steps below show the Sumsub as the KYC provider as an example.*

### Mode A — KYC provider share token (`TOKEN`)

Use when the consuming product uses the same KYC provider as the one in your request to Meld and can import via share token. No raw PII or images transit through your retrieval response.

#### **Request**

```json theme={null}
{
  "mode": "TOKEN",
  "kycProvider": "SUMSUB",
  "recipientClientId": "receiving.partner's.client.id"
}
```

| Field               | Required        | Description                        |
| ------------------- | --------------- | ---------------------------------- |
| `mode`              | Yes             | `TOKEN`                            |
| `kycProvider`       | Yes             | KYC provider name                  |
| `recipientClientId` | Yes for `TOKEN` | Receiving KYC provider's client id |

#### **Response** (`application/json`)

```json theme={null}
{
  "mode": "TOKEN",
  "applicantId": "65f3a9c1f0b3a12d34e56789",
  "shareToken": "_act-sbx-jwt-…"
}
```

Pass `shareToken` (and `applicantId` if needed) to your own KYC provider integration.

### Mode B — Raw applicant data (`RAW_DATA`)

Use when the consuming product needs PII and document images directly.

#### **Request**

```json theme={null}
{
  "mode": "RAW_DATA",
  "kycProvider": "SUMSUB"
}
```

#### **Response** (`multipart/form-data`)

| Part                  | Type | Description                                                                                       |
| --------------------- | ---- | ------------------------------------------------------------------------------------------------- |
| `data`                | JSON | Applicant metadata in the same schema shape as raw submit `data` (`mode` is `RAW_DATA_IMPORT`)    |
| One part per document | File | Image bytes. Part names are **generated on export** (see below), not the names you used on submit |

#### Example `data` part

```json theme={null}
{
  "serviceProvider": "SUMSUB",
  "mode": "RAW_DATA_IMPORT",
  "applicantData": {
    "firstName": "Jane",
    "lastName": "Doe",
    "dob": "1990-01-15",
    "nationality": "USA",
    "phone": "+15551234567",
    "email": "jane.doe@example.com",
    "tin": "123-45-6789",
    "taxResidenceCountry": "USA",
    "address": {
      "country": "USA",
      "street": "1 Main St",
      "town": "Springfield",
      "state": "US-IL",
      "postCode": "62704"
    },
    "documents": [
      {
        "part": "ID_CARD_FRONT_SIDE_abc123",
        "idDocType": "ID_CARD",
        "idDocSubType": "FRONT_SIDE",
        "country": "USA"
      },
      {
        "part": "ID_CARD_BACK_SIDE_def456",
        "idDocType": "ID_CARD",
        "idDocSubType": "BACK_SIDE",
        "country": "USA"
      },
      {
        "part": "SELFIE_ghi789",
        "idDocType": "SELFIE",
        "country": "USA"
      }
    ]
  }
}
```

Notes on the raw export response:

* Document part names follow `{idDocType}_{idDocSubType}_{imageId}` (or `{idDocType}_{imageId}` when there is no subtype). Use `applicantData.documents[].part` to match each file part.
* `idDocType` / `idDocSubType` are passed through as returned by the KYC provider (strings, not necessarily limited to Meld's submit enums).
* Fields not available from the provider may be `null`.
* Address `state` may be an ISO 3166-2 code (e.g. `US-CA`) when the KYC provider provides `stateCode`.

### Example (curl) — token export

```bash theme={null}
curl -X POST "https://api.meld.io/accounts/customers/{customerId}/kyc/export" \
  -u "{apiKey}:{apiSecret}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "TOKEN",
    "kycProvider": "SUMSUB",
    "recipientClientId": "your.partner.client.id"
  }'
```

### Example (curl) — raw export

```bash theme={null}
curl -X POST "https://api.meld.io/accounts/customers/{customerId}/kyc/export" \
  -u "{apiKey}:{apiSecret}" \
  -H "Content-Type: application/json" \
  -H "Accept: multipart/form-data" \
  -d '{
    "mode": "RAW_DATA",
    "kycProvider": "SUMSUB"
  }' \
  --output kyc-export.multipart
```

Parse `kyc-export.multipart` as multipart: read the `data` JSON part, then each document file part named in `documents[].part`.

## Error cases

| Situation                                  | Typical result                                     |
| ------------------------------------------ | -------------------------------------------------- |
| Customer has no KYC provider applicant yet | `404` — no KYC applicant for customer and provider |
| `TOKEN` export without `recipientClientId` | `400` — `recipientClientId` is required            |
| `kycProvider` missing or invalid           | `400`                                              |