Skip to main content
POST
Initiate customer KYC

Authorizations

Authorization
string
header
default:BASIC <Meld API Key>
required

Headers

Meld-Version
string

Dated API version to use for this request, e.g. 2026-02-03.

Example:

"2023-12-19"

Path Parameters

customerId
string
required

Customer id

Body

application/json

Request to initiate KYC for a customer with a given provider

kycShareProviders
enum<string>[]

Additional KYC providers to share the result with. Each is checked up front, and one missing a share prerequisite fails the call with 422 KYC_SHARE_PREREQUISITES_MISSING

Available options:
ACROSS,
AEROPAY,
AKOYA,
ALCHEMYPAY,
APPLEPAY,
AUTHORIZENET,
BANXA,
BILIRA,
BINANCECONNECT,
BINANCEPAY,
BLOCKCHAINDOTCOM,
BOOMFI,
BRAINTREE,
BRALE,
BTCDIRECT,
CASHAPP,
CHECKOUT,
CIRCLE,
COINBASEPAY,
COINFLOW,
DUENETWORK,
ELDORADO,
FINICITY,
FLASHNET,
FONBNK,
GUARDARIAN,
HARBOUR,
KOYWE,
KRYPTONIM,
MERCURYO,
MESH,
MESO,
MOONPAY,
MOOV,
MX,
NMI,
NOAH,
ONMETA,
ONRAMPMONEY,
PAYBIS,
PAYPAL,
PLAID,
RAMP,
REVOLUT,
ROBINHOOD,
ROUTERPROTOCOL,
SALTEDGE,
SALTEDGEPARTNERS,
SARDINE,
SHIFT4,
SHOPIFY,
SIMPLEX,
SKRILLCRYPTO,
SQUARE,
STRIPE,
SUMSUB,
SWAPPED,
TANGOCARD,
TELLER,
TOPPER,
TRANSAK,
TREMENDOUS,
TRANSFI,
UNLIMIT,
UPHOLD,
WYRE,
XANPOOL,
YELLOWCARD,
YODLEE
mode
enum<string>

KYC initiation mode. Optional on POST, where it defaults to HOSTED_URL; required on PATCH

Available options:
HOSTED_URL,
TOKEN_IMPORT
order
object

POST only: the order the customer is about to place

serviceProvider
enum<string>

KYC provider to use (currently only SUMSUB is supported). Optional on POST, where it defaults to SUMSUB; required on PATCH

Available options:
SUMSUB
Minimum string length: 1
serviceProviderDetails
SumsubTokenImportKycDetails · object

Provider-specific details required for the selected mode. Required when mode is TOKEN_IMPORT, null for HOSTED_URL

targetServiceProvider
enum<string>

POST only: the provider the customer is heading to. Meld verifies the customer at the level that provider needs, steps an existing applicant up to it, and shares the result when the provider takes a KYC share. The provider's share prerequisites (its terms, an email, a name or an address) never fail the call: Meld shares once they are met

Available options:
ACROSS,
AEROPAY,
AKOYA,
ALCHEMYPAY,
APPLEPAY,
AUTHORIZENET,
BANXA,
BILIRA,
BINANCECONNECT,
BINANCEPAY,
BLOCKCHAINDOTCOM,
BOOMFI,
BRAINTREE,
BRALE,
BTCDIRECT,
CASHAPP,
CHECKOUT,
CIRCLE,
COINBASEPAY,
COINFLOW,
DUENETWORK,
ELDORADO,
FINICITY,
FLASHNET,
FONBNK,
GUARDARIAN,
HARBOUR,
KOYWE,
KRYPTONIM,
MERCURYO,
MESH,
MESO,
MOONPAY,
MOOV,
MX,
NMI,
NOAH,
ONMETA,
ONRAMPMONEY,
PAYBIS,
PAYPAL,
PLAID,
RAMP,
REVOLUT,
ROBINHOOD,
ROUTERPROTOCOL,
SALTEDGE,
SALTEDGEPARTNERS,
SARDINE,
SHIFT4,
SHOPIFY,
SIMPLEX,
SKRILLCRYPTO,
SQUARE,
STRIPE,
SUMSUB,
SWAPPED,
TANGOCARD,
TELLER,
TOPPER,
TRANSAK,
TREMENDOUS,
TRANSFI,
UNLIMIT,
UPHOLD,
WYRE,
XANPOOL,
YELLOWCARD,
YODLEE

Response

OK

Response after initiating KYC: customer/provider/status. Token is obtained via getToken once KYC is complete.

approvedLevel
enum<string>

Highest Meld KYC level the customer is approved at; absent when nothing is approved

Available options:
LEVEL_1,
LEVEL_2,
LEVEL_3
customerId
string

Customer id (Meld)

expiresAt
string

When url stops opening (ISO-8601 UTC); present only with url

Example:

"2026-11-04T15:30:00Z"

level
enum<string>

Meld KYC level the url verifies; absent when unknown

Available options:
LEVEL_1,
LEVEL_2,
LEVEL_3
serviceProvider
enum<string>

KYC provider

Available options:
SUMSUB
status
enum<string>

Current KYC status

Available options:
PENDING,
APPROVED,
REJECTED,
EXPIRED,
UNKNOWN
url
string

URL to start the KYC flow (e.g. Sumsub WebSDK), if applicable.