Create a Customer
curl --request POST \
--url https://api.spherepay.co/v2/customer \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"email": "jane.smith@example.com",
"phone": "+14155550123",
"type": "individual",
"addresses": [
{
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"type": "residential"
}
],
"dateOfBirth": "2026-01-01",
"enabledVerificationProfiles": [
"a",
"c"
],
"firstName": "Jane",
"ipAddress": "203.0.113.4",
"lastName": "Smith",
"meta": {},
"middleName": "Anne",
"personalExpectedActivity": {
"expectedCounterpartyTypes": [
"domestic_individual",
"foreign_business"
],
"expectedGeographies": [
"MEX",
"USA"
],
"expectedMonthlyTransactionCount": "16_50",
"transactionFrequency": "monthly"
}
}
'import requests
url = "https://api.spherepay.co/v2/customer"
payload = {
"email": "jane.smith@example.com",
"phone": "+14155550123",
"type": "individual",
"addresses": [
{
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"type": "residential"
}
],
"dateOfBirth": "2026-01-01",
"enabledVerificationProfiles": ["a", "c"],
"firstName": "Jane",
"ipAddress": "203.0.113.4",
"lastName": "Smith",
"meta": {},
"middleName": "Anne",
"personalExpectedActivity": {
"expectedCounterpartyTypes": ["domestic_individual", "foreign_business"],
"expectedGeographies": ["MEX", "USA"],
"expectedMonthlyTransactionCount": "16_50",
"transactionFrequency": "monthly"
}
}
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({
email: 'jane.smith@example.com',
phone: '+14155550123',
type: 'individual',
addresses: [
{
address: {
city: 'Chicago',
country: 'USA',
line1: '233 South Wacker Drive',
line2: 'Suite 4700',
postalCode: '60606',
state: 'IL'
},
type: 'residential'
}
],
dateOfBirth: '2026-01-01',
enabledVerificationProfiles: ['a', 'c'],
firstName: 'Jane',
ipAddress: '203.0.113.4',
lastName: 'Smith',
meta: {},
middleName: 'Anne',
personalExpectedActivity: {
expectedCounterpartyTypes: ['domestic_individual', 'foreign_business'],
expectedGeographies: ['MEX', 'USA'],
expectedMonthlyTransactionCount: '16_50',
transactionFrequency: 'monthly'
}
})
};
fetch('https://api.spherepay.co/v2/customer', 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",
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([
'email' => 'jane.smith@example.com',
'phone' => '+14155550123',
'type' => 'individual',
'addresses' => [
[
'address' => [
'city' => 'Chicago',
'country' => 'USA',
'line1' => '233 South Wacker Drive',
'line2' => 'Suite 4700',
'postalCode' => '60606',
'state' => 'IL'
],
'type' => 'residential'
]
],
'dateOfBirth' => '2026-01-01',
'enabledVerificationProfiles' => [
'a',
'c'
],
'firstName' => 'Jane',
'ipAddress' => '203.0.113.4',
'lastName' => 'Smith',
'meta' => [
],
'middleName' => 'Anne',
'personalExpectedActivity' => [
'expectedCounterpartyTypes' => [
'domestic_individual',
'foreign_business'
],
'expectedGeographies' => [
'MEX',
'USA'
],
'expectedMonthlyTransactionCount' => '16_50',
'transactionFrequency' => 'monthly'
]
]),
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"
payload := strings.NewReader("{\n \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\",\n \"addresses\": [\n {\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 \"type\": \"residential\"\n }\n ],\n \"dateOfBirth\": \"2026-01-01\",\n \"enabledVerificationProfiles\": [\n \"a\",\n \"c\"\n ],\n \"firstName\": \"Jane\",\n \"ipAddress\": \"203.0.113.4\",\n \"lastName\": \"Smith\",\n \"meta\": {},\n \"middleName\": \"Anne\",\n \"personalExpectedActivity\": {\n \"expectedCounterpartyTypes\": [\n \"domestic_individual\",\n \"foreign_business\"\n ],\n \"expectedGeographies\": [\n \"MEX\",\n \"USA\"\n ],\n \"expectedMonthlyTransactionCount\": \"16_50\",\n \"transactionFrequency\": \"monthly\"\n }\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")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\",\n \"addresses\": [\n {\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 \"type\": \"residential\"\n }\n ],\n \"dateOfBirth\": \"2026-01-01\",\n \"enabledVerificationProfiles\": [\n \"a\",\n \"c\"\n ],\n \"firstName\": \"Jane\",\n \"ipAddress\": \"203.0.113.4\",\n \"lastName\": \"Smith\",\n \"meta\": {},\n \"middleName\": \"Anne\",\n \"personalExpectedActivity\": {\n \"expectedCounterpartyTypes\": [\n \"domestic_individual\",\n \"foreign_business\"\n ],\n \"expectedGeographies\": [\n \"MEX\",\n \"USA\"\n ],\n \"expectedMonthlyTransactionCount\": \"16_50\",\n \"transactionFrequency\": \"monthly\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.spherepay.co/v2/customer")
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 \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\",\n \"addresses\": [\n {\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 \"type\": \"residential\"\n }\n ],\n \"dateOfBirth\": \"2026-01-01\",\n \"enabledVerificationProfiles\": [\n \"a\",\n \"c\"\n ],\n \"firstName\": \"Jane\",\n \"ipAddress\": \"203.0.113.4\",\n \"lastName\": \"Smith\",\n \"meta\": {},\n \"middleName\": \"Anne\",\n \"personalExpectedActivity\": {\n \"expectedCounterpartyTypes\": [\n \"domestic_individual\",\n \"foreign_business\"\n ],\n \"expectedGeographies\": [\n \"MEX\",\n \"USA\"\n ],\n \"expectedMonthlyTransactionCount\": \"16_50\",\n \"transactionFrequency\": \"monthly\"\n }\n}"
response = http.request(request)
puts response.read_body{
"createdAt": "2026-03-09T20:46:31.305Z",
"enabledVerificationProfiles": [
"a",
"c"
],
"id": "customer_f31121c389624d3697cbf3ea8830b7a4",
"tosStatus": "incomplete",
"type": "individual",
"updatedAt": "2026-03-09T20:46:31.305Z",
"verificationProfiles": [
{
"criteria": {
"complete": [
"email_address",
"phone_number",
"residential_address",
"tax_identification_number"
],
"errors": [],
"pending": [],
"required": [
"identity_document",
"liveness_report_document"
]
},
"name": "kyc_profile_a",
"status": "incomplete"
}
],
"dateOfBirth": "1990-01-15",
"email": "jane.smith@example.com",
"firstName": "Jane",
"lastName": "Smith",
"meta": {},
"personalInformation": {
"accountPurpose": "<string>",
"accountPurposeDescription": "<string>",
"actingAsIntermediary": false,
"countryOfBirth": "USA",
"employmentStatus": "<string>",
"expectedMonthlyPayments": "<string>",
"gender": "<string>",
"middleName": "James",
"nationality": "USA",
"occupationSocCode": "151252",
"residencyCountry": "USA",
"sourceOfFunds": "<string>",
"stateOfBirth": "JAL",
"taxIdentificationNumberCountry": "USA",
"taxIdentificationNumberDescription": "<string>",
"taxIdentificationNumberType": "ssn"
},
"phone": "+14155550123",
"statusDetails": {
"message": "Please re-upload a clear photo of the front and back of the director's ID and correct the tax ID number.",
"reasons": [
{
"externalReason": "Cannot validate ID — upload a photo of the ID that is clear",
"reasonCode": "poor_image_quality",
"verificationProfiles": [
"kyb_profile_a"
]
},
{
"externalReason": "The tax identification number is not in a valid format for the selected country and ID type.",
"reasonCode": "invalid_tax_identification_number",
"verificationProfiles": [
"kyb_profile_a"
]
}
],
"updatedAt": "2026-07-16T21:04:00Z"
}
}{
"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
}Customers
Create an Individual or Business Customer
Create a new customer.
Create a Customer
curl --request POST \
--url https://api.spherepay.co/v2/customer \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"email": "jane.smith@example.com",
"phone": "+14155550123",
"type": "individual",
"addresses": [
{
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"type": "residential"
}
],
"dateOfBirth": "2026-01-01",
"enabledVerificationProfiles": [
"a",
"c"
],
"firstName": "Jane",
"ipAddress": "203.0.113.4",
"lastName": "Smith",
"meta": {},
"middleName": "Anne",
"personalExpectedActivity": {
"expectedCounterpartyTypes": [
"domestic_individual",
"foreign_business"
],
"expectedGeographies": [
"MEX",
"USA"
],
"expectedMonthlyTransactionCount": "16_50",
"transactionFrequency": "monthly"
}
}
'import requests
url = "https://api.spherepay.co/v2/customer"
payload = {
"email": "jane.smith@example.com",
"phone": "+14155550123",
"type": "individual",
"addresses": [
{
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"type": "residential"
}
],
"dateOfBirth": "2026-01-01",
"enabledVerificationProfiles": ["a", "c"],
"firstName": "Jane",
"ipAddress": "203.0.113.4",
"lastName": "Smith",
"meta": {},
"middleName": "Anne",
"personalExpectedActivity": {
"expectedCounterpartyTypes": ["domestic_individual", "foreign_business"],
"expectedGeographies": ["MEX", "USA"],
"expectedMonthlyTransactionCount": "16_50",
"transactionFrequency": "monthly"
}
}
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({
email: 'jane.smith@example.com',
phone: '+14155550123',
type: 'individual',
addresses: [
{
address: {
city: 'Chicago',
country: 'USA',
line1: '233 South Wacker Drive',
line2: 'Suite 4700',
postalCode: '60606',
state: 'IL'
},
type: 'residential'
}
],
dateOfBirth: '2026-01-01',
enabledVerificationProfiles: ['a', 'c'],
firstName: 'Jane',
ipAddress: '203.0.113.4',
lastName: 'Smith',
meta: {},
middleName: 'Anne',
personalExpectedActivity: {
expectedCounterpartyTypes: ['domestic_individual', 'foreign_business'],
expectedGeographies: ['MEX', 'USA'],
expectedMonthlyTransactionCount: '16_50',
transactionFrequency: 'monthly'
}
})
};
fetch('https://api.spherepay.co/v2/customer', 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",
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([
'email' => 'jane.smith@example.com',
'phone' => '+14155550123',
'type' => 'individual',
'addresses' => [
[
'address' => [
'city' => 'Chicago',
'country' => 'USA',
'line1' => '233 South Wacker Drive',
'line2' => 'Suite 4700',
'postalCode' => '60606',
'state' => 'IL'
],
'type' => 'residential'
]
],
'dateOfBirth' => '2026-01-01',
'enabledVerificationProfiles' => [
'a',
'c'
],
'firstName' => 'Jane',
'ipAddress' => '203.0.113.4',
'lastName' => 'Smith',
'meta' => [
],
'middleName' => 'Anne',
'personalExpectedActivity' => [
'expectedCounterpartyTypes' => [
'domestic_individual',
'foreign_business'
],
'expectedGeographies' => [
'MEX',
'USA'
],
'expectedMonthlyTransactionCount' => '16_50',
'transactionFrequency' => 'monthly'
]
]),
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"
payload := strings.NewReader("{\n \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\",\n \"addresses\": [\n {\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 \"type\": \"residential\"\n }\n ],\n \"dateOfBirth\": \"2026-01-01\",\n \"enabledVerificationProfiles\": [\n \"a\",\n \"c\"\n ],\n \"firstName\": \"Jane\",\n \"ipAddress\": \"203.0.113.4\",\n \"lastName\": \"Smith\",\n \"meta\": {},\n \"middleName\": \"Anne\",\n \"personalExpectedActivity\": {\n \"expectedCounterpartyTypes\": [\n \"domestic_individual\",\n \"foreign_business\"\n ],\n \"expectedGeographies\": [\n \"MEX\",\n \"USA\"\n ],\n \"expectedMonthlyTransactionCount\": \"16_50\",\n \"transactionFrequency\": \"monthly\"\n }\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")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\",\n \"addresses\": [\n {\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 \"type\": \"residential\"\n }\n ],\n \"dateOfBirth\": \"2026-01-01\",\n \"enabledVerificationProfiles\": [\n \"a\",\n \"c\"\n ],\n \"firstName\": \"Jane\",\n \"ipAddress\": \"203.0.113.4\",\n \"lastName\": \"Smith\",\n \"meta\": {},\n \"middleName\": \"Anne\",\n \"personalExpectedActivity\": {\n \"expectedCounterpartyTypes\": [\n \"domestic_individual\",\n \"foreign_business\"\n ],\n \"expectedGeographies\": [\n \"MEX\",\n \"USA\"\n ],\n \"expectedMonthlyTransactionCount\": \"16_50\",\n \"transactionFrequency\": \"monthly\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.spherepay.co/v2/customer")
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 \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\",\n \"addresses\": [\n {\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 \"type\": \"residential\"\n }\n ],\n \"dateOfBirth\": \"2026-01-01\",\n \"enabledVerificationProfiles\": [\n \"a\",\n \"c\"\n ],\n \"firstName\": \"Jane\",\n \"ipAddress\": \"203.0.113.4\",\n \"lastName\": \"Smith\",\n \"meta\": {},\n \"middleName\": \"Anne\",\n \"personalExpectedActivity\": {\n \"expectedCounterpartyTypes\": [\n \"domestic_individual\",\n \"foreign_business\"\n ],\n \"expectedGeographies\": [\n \"MEX\",\n \"USA\"\n ],\n \"expectedMonthlyTransactionCount\": \"16_50\",\n \"transactionFrequency\": \"monthly\"\n }\n}"
response = http.request(request)
puts response.read_body{
"createdAt": "2026-03-09T20:46:31.305Z",
"enabledVerificationProfiles": [
"a",
"c"
],
"id": "customer_f31121c389624d3697cbf3ea8830b7a4",
"tosStatus": "incomplete",
"type": "individual",
"updatedAt": "2026-03-09T20:46:31.305Z",
"verificationProfiles": [
{
"criteria": {
"complete": [
"email_address",
"phone_number",
"residential_address",
"tax_identification_number"
],
"errors": [],
"pending": [],
"required": [
"identity_document",
"liveness_report_document"
]
},
"name": "kyc_profile_a",
"status": "incomplete"
}
],
"dateOfBirth": "1990-01-15",
"email": "jane.smith@example.com",
"firstName": "Jane",
"lastName": "Smith",
"meta": {},
"personalInformation": {
"accountPurpose": "<string>",
"accountPurposeDescription": "<string>",
"actingAsIntermediary": false,
"countryOfBirth": "USA",
"employmentStatus": "<string>",
"expectedMonthlyPayments": "<string>",
"gender": "<string>",
"middleName": "James",
"nationality": "USA",
"occupationSocCode": "151252",
"residencyCountry": "USA",
"sourceOfFunds": "<string>",
"stateOfBirth": "JAL",
"taxIdentificationNumberCountry": "USA",
"taxIdentificationNumberDescription": "<string>",
"taxIdentificationNumberType": "ssn"
},
"phone": "+14155550123",
"statusDetails": {
"message": "Please re-upload a clear photo of the front and back of the director's ID and correct the tax ID number.",
"reasons": [
{
"externalReason": "Cannot validate ID — upload a photo of the ID that is clear",
"reasonCode": "poor_image_quality",
"verificationProfiles": [
"kyb_profile_a"
]
},
{
"externalReason": "The tax identification number is not in a valid format for the selected country and ID type.",
"reasonCode": "invalid_tax_identification_number",
"verificationProfiles": [
"kyb_profile_a"
]
}
],
"updatedAt": "2026-07-16T21:04:00Z"
}
}{
"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
}Before you can initiate any transfer, you must create a customer record in SpherePay. This endpoint registers either an individual or a business customer and returns a customer object with a unique ID and a
verificationProfiles array that tracks KYC/KYB completion status. You must specify type upfront — it cannot be changed after creation.
Individual customers resident in the EEA+ region and EEA+ incorporated businesses have additional fields that must be present before verification. Those fields are optional at creation. See EEA+ residents and EEA+ businesses.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
- Individual Customer Create
- Business Customer Create
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"
Available options:
individual The customer's address. Deprecated — prefer addresses.
Show child attributes
Show child attributes
The customer's addresses. Individual customers support exactly one residential address. Provide either this field or the deprecated address field, not both.
Show child attributes
Show child attributes
Example:
[
{
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"type": "residential"
}
]
The date string in YYYY-MM-DD format
Example:
"2026-01-01"
Restricts which verification profile families this customer may onboard through. Must be a subset of the families enabled on your application; supplying one that is not enabled is rejected with a 422. Omit the field to inherit the application's setting.
Minimum array length:
1Available options:
a, b, c, d Example:
["a", "c"]
The customer's legal first name.
Required string length:
1 - 100Example:
"Jane"
The IP address the customer used to sign up. Required by some verification providers.
Example:
"203.0.113.4"
The customer's legal last name.
Required string length:
1 - 100Example:
"Smith"
Additional metadata associated with the customer
Show child attributes
Show child attributes
The customer's legal middle name.
Required string length:
1 - 100Example:
"Anne"
The individual customer's expected transaction activity. Only accepted on individual customers.
Show child attributes
Show child attributes
Personal information including tax identification details for individual customers. When any tax identification field is provided, all tax identification fields (number, type, country) and address are required. Please refer to the Individual Verification Criteria for the full list of reference.
Show child attributes
Show child attributes
Response
- Individual
- Business
Response containing information about an individual customer.
ISO 8601 formatted customer creation timestamp
Example:
"2026-03-09T20:46:31.305Z"
Which verification profile families this customer may onboard through. Set explicitly at creation — from the request when supplied, otherwise a snapshot of the application's families at that moment — and thereafter changed only by an explicit update, so it does not follow later changes to the application. Always a subset of the application's families. Distinct from verificationProfiles, which reports the evaluated profiles and their statuses.
Available options:
a, b, c, d Example:
["a", "c"]
Customer ID
Example:
"customer_f31121c389624d3697cbf3ea8830b7a4"
Customer Terms of Service acceptance status (incomplete | pending | approved).
Available options:
incomplete, pending, approved Example:
"incomplete"
Customer type
Available options:
individual Example:
"individual"
ISO 8601 formatted customer update timestamp
Example:
"2026-03-09T20:46:31.305Z"
The evaluated verification profiles for this customer and their statuses — what the customer is being assessed against right now, as opposed to enabledVerificationProfiles, which says which families they are permitted to use. Array of verification profiles. For individual customers, this will include kyc_profile_a. For business customers, this will include kyb_profile_a. See KYC Flow for individuals or KYB Flow for businesses. See Verification Profile for individual status definitions and criteria breakdown or Verification Profile for business status definitions and criteria breakdown.
Show child attributes
Show child attributes
Example:
[
{
"criteria": {
"complete": [
"email_address",
"phone_number",
"residential_address",
"tax_identification_number"
],
"errors": [],
"pending": [],
"required": [
"identity_document",
"liveness_report_document"
]
},
"name": "kyc_profile_a",
"status": "incomplete"
}
]
The customer's date of birth in YYYY-MM-DD format (individual customers only).
Example:
"1990-01-15"
Customer email address
Example:
"jane.smith@example.com"
Customer first name (individual customers only)
Example:
"Jane"
Customer last name (individual customers only)
Example:
"Smith"
Show child attributes
Show child attributes
Personal information for an individual customer, echoed back from the most recent submission. The tax identification number is omitted from responses for privacy.
Show child attributes
Show child attributes
Customer phone number
Example:
"+14155550123"
Additional context on why the customer's verification reached its current status.
Show child attributes
Show child attributes
Example:
{
"message": "Please re-upload a clear photo of the front and back of the director's ID and correct the tax ID number.",
"reasons": [
{
"externalReason": "Cannot validate ID — upload a photo of the ID that is clear",
"reasonCode": "poor_image_quality",
"verificationProfiles": ["kyb_profile_a"]
},
{
"externalReason": "The tax identification number is not in a valid format for the selected country and ID type.",
"reasonCode": "invalid_tax_identification_number",
"verificationProfiles": ["kyb_profile_a"]
}
],
"updatedAt": "2026-07-16T21:04:00Z"
}
Last modified on August 24, 2026