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

Look up the Meld customerId for a user who has already been KYC-approved
Get the user’s consent to share their KYC data with the receiving product
Call the export endpoint — either a share token or raw data plus documents
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.

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

{
  "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

{
  "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. 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

{
  "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`)

{
  "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

{
  "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

{
  "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

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

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`

Welcome

AI Toolkit

Meld API

Stablecoins & Digital Assets

Bank Linking

Retrieve KYC

Summary of the steps

Before you begin

Flows at a glance

Step 1: Retrieve Meld customer

Request

Response

Step 2: Retrieve KYC

Request

Response (`application/json`)

Mode B — Raw applicant data (`RAW_DATA`)

Request

Response (`multipart/form-data`)

Example `data` part

Example (curl) — token export

Example (curl) — raw export

Error cases

​Summary of the steps

​Before you begin

​Flows at a glance

​Step 1: Retrieve Meld customer

​Request

​Response

​Step 2: Retrieve KYC

​Mode A — KYC provider share token (TOKEN)

​Request

​Response (application/json)

​Mode B — Raw applicant data (RAW_DATA)

​Request

​Response (multipart/form-data)

​Example data part

​Example (curl) — token export

​Example (curl) — raw export

​Error cases

Summary of the steps

Before you begin

Flows at a glance

Step 1: Retrieve Meld customer

Request

Response

Step 2: Retrieve KYC

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

Request

Response (`application/json`)

Mode B — Raw applicant data (`RAW_DATA`)

Request

Response (`multipart/form-data`)

Example `data` part

Example (curl) — token export

Example (curl) — raw export

Error cases