curl --request POST \
--url https://api-sb.meld.io/accounts/customers/{customerId}/kyc/initiate \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '{}'import requests
url = "https://api-sb.meld.io/accounts/customers/{customerId}/kyc/initiate"
payload = {}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://api-sb.meld.io/accounts/customers/{customerId}/kyc/initiate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sb.meld.io/accounts/customers/{customerId}/kyc/initiate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sb.meld.io/accounts/customers/{customerId}/kyc/initiate"
payload := strings.NewReader("{}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sb.meld.io/accounts/customers/{customerId}/kyc/initiate")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sb.meld.io/accounts/customers/{customerId}/kyc/initiate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{}"
response = http.request(request)
puts response.read_body{
"approvedLevel": "LEVEL_1",
"customerId": "<string>",
"expiresAt": "2026-11-04T15:30:00Z",
"level": "LEVEL_1",
"serviceProvider": "SUMSUB",
"status": "PENDING",
"url": "<string>"
}{
"code": "BAD_REQUEST",
"message": "Bad request",
"requestId": "01JB2K7C9XQZ4M8N2P5R6T3V",
"timestamp": "2026-08-14T09:41:22.482+00:00",
"errors": [
"[Meld-Version] is invalid"
]
}{
"code": "UNAUTHORIZED",
"message": "Access denied",
"requestId": "01JB2K7C9XQZ4M8N2P5R6T3V",
"timestamp": "2026-08-14T09:41:22.482+00:00"
}{
"code": "FORBIDDEN",
"message": "Access denied",
"requestId": "01JB2K7C9XQZ4M8N2P5R6T3V",
"timestamp": "2026-08-14T09:41:22.482+00:00"
}{
"code": "NOT_FOUND",
"message": "Resource not found",
"requestId": "01JB2K7C9XQZ4M8N2P5R6T3V",
"timestamp": "2026-08-14T09:41:22.482+00:00"
}{
"code": "CONFLICT",
"message": "Conflict",
"requestId": "01JB2K7C9XQZ4M8N2P5R6T3V",
"timestamp": "2026-08-14T09:41:22.482+00:00"
}{
"code": "KYC_SHARE_PREREQUISITES_MISSING",
"message": "Customer is not compliant to share KYC with provider=UPHOLD, missing=[EMAIL, TERMS]",
"errors": [
"UPHOLD:EMAIL",
"UPHOLD:TERMS"
],
"requestId": "01JB2K7C9XQZ4M8N2P5R6T3V",
"timestamp": "2026-08-14T09:41:22.482+00:00"
}{
"code": "UNEXPECTED_ERROR",
"message": "Unexpected error",
"requestId": "01JB2K7C9XQZ4M8N2P5R6T3V",
"timestamp": "2026-08-14T09:41:22.482+00:00"
}Initiate customer KYC
Retrieve a url that when launched displays a UI that commences KYC for your user. With a targetServiceProvider or order, Meld picks the KYC level: an applicant approved at that level gets APPROVED with no url, and a lower one is moved up and gets a url at the new level.
curl --request POST \
--url https://api-sb.meld.io/accounts/customers/{customerId}/kyc/initiate \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '{}'import requests
url = "https://api-sb.meld.io/accounts/customers/{customerId}/kyc/initiate"
payload = {}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://api-sb.meld.io/accounts/customers/{customerId}/kyc/initiate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sb.meld.io/accounts/customers/{customerId}/kyc/initiate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sb.meld.io/accounts/customers/{customerId}/kyc/initiate"
payload := strings.NewReader("{}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sb.meld.io/accounts/customers/{customerId}/kyc/initiate")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sb.meld.io/accounts/customers/{customerId}/kyc/initiate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{}"
response = http.request(request)
puts response.read_body{
"approvedLevel": "LEVEL_1",
"customerId": "<string>",
"expiresAt": "2026-11-04T15:30:00Z",
"level": "LEVEL_1",
"serviceProvider": "SUMSUB",
"status": "PENDING",
"url": "<string>"
}{
"code": "BAD_REQUEST",
"message": "Bad request",
"requestId": "01JB2K7C9XQZ4M8N2P5R6T3V",
"timestamp": "2026-08-14T09:41:22.482+00:00",
"errors": [
"[Meld-Version] is invalid"
]
}{
"code": "UNAUTHORIZED",
"message": "Access denied",
"requestId": "01JB2K7C9XQZ4M8N2P5R6T3V",
"timestamp": "2026-08-14T09:41:22.482+00:00"
}{
"code": "FORBIDDEN",
"message": "Access denied",
"requestId": "01JB2K7C9XQZ4M8N2P5R6T3V",
"timestamp": "2026-08-14T09:41:22.482+00:00"
}{
"code": "NOT_FOUND",
"message": "Resource not found",
"requestId": "01JB2K7C9XQZ4M8N2P5R6T3V",
"timestamp": "2026-08-14T09:41:22.482+00:00"
}{
"code": "CONFLICT",
"message": "Conflict",
"requestId": "01JB2K7C9XQZ4M8N2P5R6T3V",
"timestamp": "2026-08-14T09:41:22.482+00:00"
}{
"code": "KYC_SHARE_PREREQUISITES_MISSING",
"message": "Customer is not compliant to share KYC with provider=UPHOLD, missing=[EMAIL, TERMS]",
"errors": [
"UPHOLD:EMAIL",
"UPHOLD:TERMS"
],
"requestId": "01JB2K7C9XQZ4M8N2P5R6T3V",
"timestamp": "2026-08-14T09:41:22.482+00:00"
}{
"code": "UNEXPECTED_ERROR",
"message": "Unexpected error",
"requestId": "01JB2K7C9XQZ4M8N2P5R6T3V",
"timestamp": "2026-08-14T09:41:22.482+00:00"
}Headers
Body
Request to initiate KYC for a customer with a given provider
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
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 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
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.