Create Customer via Link
curl --request POST \
--url https://api.spherepay.co/v2/customer/kyc-link \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"email": "jane.smith@example.com",
"phone": "+14155550123",
"type": "individual"
}
'import requests
url = "https://api.spherepay.co/v2/customer/kyc-link"
payload = {
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"email": "jane.smith@example.com",
"phone": "+14155550123",
"type": "individual"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
address: {
city: 'Chicago',
country: 'USA',
line1: '233 South Wacker Drive',
line2: 'Suite 4700',
postalCode: '60606',
state: 'IL'
},
email: 'jane.smith@example.com',
phone: '+14155550123',
type: 'individual'
})
};
fetch('https://api.spherepay.co/v2/customer/kyc-link', 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.spherepay.co/v2/customer/kyc-link",
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([
'address' => [
'city' => 'Chicago',
'country' => 'USA',
'line1' => '233 South Wacker Drive',
'line2' => 'Suite 4700',
'postalCode' => '60606',
'state' => 'IL'
],
'email' => 'jane.smith@example.com',
'phone' => '+14155550123',
'type' => 'individual'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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.spherepay.co/v2/customer/kyc-link"
payload := strings.NewReader("{\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.spherepay.co/v2/customer/kyc-link")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.spherepay.co/v2/customer/kyc-link")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\"\n}"
response = http.request(request)
puts response.read_body{
"customerId": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
"expiresAt": "2026-03-09T20:46:31.305Z",
"url": "https://in.sumsub.com/websdk/p/sbx_uq30ag1ov7oHZhmx"
}{
"code": "address/invalid",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Invalid request parameters",
"status": 400
}{
"code": "resource/not-found",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Resource not found",
"status": 404
}{
"code": "validation/failed",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Validation failed",
"errors": [
{
"detail": "Invalid email format",
"pointer": "/email"
},
{
"detail": "Name is required",
"pointer": "/name"
}
],
"status": 422
}Onboarding Links
Create Customer via Link
Create a customer via the hosted onboarding link flow. Returns a KYC link and its expiry.
Create Customer via Link
curl --request POST \
--url https://api.spherepay.co/v2/customer/kyc-link \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"email": "jane.smith@example.com",
"phone": "+14155550123",
"type": "individual"
}
'import requests
url = "https://api.spherepay.co/v2/customer/kyc-link"
payload = {
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"email": "jane.smith@example.com",
"phone": "+14155550123",
"type": "individual"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
address: {
city: 'Chicago',
country: 'USA',
line1: '233 South Wacker Drive',
line2: 'Suite 4700',
postalCode: '60606',
state: 'IL'
},
email: 'jane.smith@example.com',
phone: '+14155550123',
type: 'individual'
})
};
fetch('https://api.spherepay.co/v2/customer/kyc-link', 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.spherepay.co/v2/customer/kyc-link",
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([
'address' => [
'city' => 'Chicago',
'country' => 'USA',
'line1' => '233 South Wacker Drive',
'line2' => 'Suite 4700',
'postalCode' => '60606',
'state' => 'IL'
],
'email' => 'jane.smith@example.com',
'phone' => '+14155550123',
'type' => 'individual'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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.spherepay.co/v2/customer/kyc-link"
payload := strings.NewReader("{\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.spherepay.co/v2/customer/kyc-link")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.spherepay.co/v2/customer/kyc-link")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\"\n}"
response = http.request(request)
puts response.read_body{
"customerId": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
"expiresAt": "2026-03-09T20:46:31.305Z",
"url": "https://in.sumsub.com/websdk/p/sbx_uq30ag1ov7oHZhmx"
}{
"code": "address/invalid",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Invalid request parameters",
"status": 400
}{
"code": "resource/not-found",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Resource not found",
"status": 404
}{
"code": "validation/failed",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Validation failed",
"errors": [
{
"detail": "Invalid email format",
"pointer": "/email"
},
{
"detail": "Name is required",
"pointer": "/name"
}
],
"status": 422
}Use this endpoint to create a customer and generate a hosted KYC link in a single request. Instead of creating the customer first and then requesting a link separately, you provide the customer’s type, email, phone, and address here, and the response returns the new customer’s ID along with a time-limited hosted verification URL. Redirect the customer to this URL to complete their identity checks with the verification provider.
Hosted verification links collect EEA+ KYC and KYB data automatically when it applies. Integrators using hosted links need no API changes for those requirements. See EEA+ region.
Customers created via this onboarding link flow can only be managed with the onboarding link endpoints — they are not compatible with the direct API onboarding flows. Likewise, customers onboarded through the other API flows cannot be used with the onboarding link endpoints.
The returned URL expires at the time indicated by
expiresAt — by default, 4 weeks (28 days) after creation. This default may change without notice, so always rely on expiresAt rather than assuming a fixed duration. If the link expires before the customer completes verification, generate a fresh one with Regenerate KYC Link using the customerId from this response.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
The customer's address. For individual customers this is the residential address; for business customers this is the registered business address.
Show child attributes
Show child attributes
The customer email address.
Maximum string length:
254Example:
"jane.smith@example.com"
The customer phone number in E.164 format.
Pattern:
^\+(?:[0-9]){6,14}[0-9]$Example:
"+14155550123"
The type of customer to onboard.
Available options:
individual, business Example:
"individual"
Response
The ID of the customer the KYC link belongs to
Example:
"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7"
ISO 8601 formatted date and time of the KYC URL expiration. By default, links expire 4 weeks (28 days) after creation, but this default may change without notice - always rely on this field rather than assuming a fixed duration.
Example:
"2026-03-09T20:46:31.305Z"
Hosted KYC URL
Example:
"https://in.sumsub.com/websdk/p/sbx_uq30ag1ov7oHZhmx"
Last modified on August 24, 2026