Create a Business Representative
curl --request POST \
--url https://api.spherepay.co/v2/business-representative \
--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"
},
"customerId": "customer_2f283221a9d44ada800ac7f11f640402",
"email": "james.wilson@acmecorp.example.com",
"personalInformation": {
"taxIdentificationNumber": "123456789",
"taxIdentificationNumberCountry": "USA",
"taxIdentificationNumberType": "ssn",
"accountPurpose": "receive_salary",
"accountPurposeDescription": "<string>",
"actingAsIntermediary": false,
"countryOfBirth": "USA",
"employmentStatus": "employed",
"expectedMonthlyPayments": "5000_9999",
"gender": "male",
"nationality": "USA",
"occupationSocCode": "151252",
"residencyCountry": "USA",
"sourceOfFunds": "salary",
"stateOfBirth": "JAL",
"taxIdentificationNumberDescription": "<string>"
},
"phone": "+13125559876",
"representationDetails": {
"isControlPerson": true,
"isSigner": true,
"ownershipPercentage": "50",
"relationshipEstablishedAt": "2020-03-15",
"roles": [
"ubo"
],
"title": "CEO"
},
"type": "individual",
"dateOfBirth": "1990-01-15",
"firstName": "Carlos",
"lastName": "Souza",
"middleName": "Carlos"
}
'import requests
url = "https://api.spherepay.co/v2/business-representative"
payload = {
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"customerId": "customer_2f283221a9d44ada800ac7f11f640402",
"email": "james.wilson@acmecorp.example.com",
"personalInformation": {
"taxIdentificationNumber": "123456789",
"taxIdentificationNumberCountry": "USA",
"taxIdentificationNumberType": "ssn",
"accountPurpose": "receive_salary",
"accountPurposeDescription": "<string>",
"actingAsIntermediary": False,
"countryOfBirth": "USA",
"employmentStatus": "employed",
"expectedMonthlyPayments": "5000_9999",
"gender": "male",
"nationality": "USA",
"occupationSocCode": "151252",
"residencyCountry": "USA",
"sourceOfFunds": "salary",
"stateOfBirth": "JAL",
"taxIdentificationNumberDescription": "<string>"
},
"phone": "+13125559876",
"representationDetails": {
"isControlPerson": True,
"isSigner": True,
"ownershipPercentage": "50",
"relationshipEstablishedAt": "2020-03-15",
"roles": ["ubo"],
"title": "CEO"
},
"type": "individual",
"dateOfBirth": "1990-01-15",
"firstName": "Carlos",
"lastName": "Souza",
"middleName": "Carlos"
}
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'
},
customerId: 'customer_2f283221a9d44ada800ac7f11f640402',
email: 'james.wilson@acmecorp.example.com',
personalInformation: {
taxIdentificationNumber: '123456789',
taxIdentificationNumberCountry: 'USA',
taxIdentificationNumberType: 'ssn',
accountPurpose: 'receive_salary',
accountPurposeDescription: '<string>',
actingAsIntermediary: false,
countryOfBirth: 'USA',
employmentStatus: 'employed',
expectedMonthlyPayments: '5000_9999',
gender: 'male',
nationality: 'USA',
occupationSocCode: '151252',
residencyCountry: 'USA',
sourceOfFunds: 'salary',
stateOfBirth: 'JAL',
taxIdentificationNumberDescription: '<string>'
},
phone: '+13125559876',
representationDetails: {
isControlPerson: true,
isSigner: true,
ownershipPercentage: '50',
relationshipEstablishedAt: '2020-03-15',
roles: ['ubo'],
title: 'CEO'
},
type: 'individual',
dateOfBirth: '1990-01-15',
firstName: 'Carlos',
lastName: 'Souza',
middleName: 'Carlos'
})
};
fetch('https://api.spherepay.co/v2/business-representative', 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/business-representative",
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'
],
'customerId' => 'customer_2f283221a9d44ada800ac7f11f640402',
'email' => 'james.wilson@acmecorp.example.com',
'personalInformation' => [
'taxIdentificationNumber' => '123456789',
'taxIdentificationNumberCountry' => 'USA',
'taxIdentificationNumberType' => 'ssn',
'accountPurpose' => 'receive_salary',
'accountPurposeDescription' => '<string>',
'actingAsIntermediary' => false,
'countryOfBirth' => 'USA',
'employmentStatus' => 'employed',
'expectedMonthlyPayments' => '5000_9999',
'gender' => 'male',
'nationality' => 'USA',
'occupationSocCode' => '151252',
'residencyCountry' => 'USA',
'sourceOfFunds' => 'salary',
'stateOfBirth' => 'JAL',
'taxIdentificationNumberDescription' => '<string>'
],
'phone' => '+13125559876',
'representationDetails' => [
'isControlPerson' => true,
'isSigner' => true,
'ownershipPercentage' => '50',
'relationshipEstablishedAt' => '2020-03-15',
'roles' => [
'ubo'
],
'title' => 'CEO'
],
'type' => 'individual',
'dateOfBirth' => '1990-01-15',
'firstName' => 'Carlos',
'lastName' => 'Souza',
'middleName' => 'Carlos'
]),
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/business-representative"
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 \"customerId\": \"customer_2f283221a9d44ada800ac7f11f640402\",\n \"email\": \"james.wilson@acmecorp.example.com\",\n \"personalInformation\": {\n \"taxIdentificationNumber\": \"123456789\",\n \"taxIdentificationNumberCountry\": \"USA\",\n \"taxIdentificationNumberType\": \"ssn\",\n \"accountPurpose\": \"receive_salary\",\n \"accountPurposeDescription\": \"<string>\",\n \"actingAsIntermediary\": false,\n \"countryOfBirth\": \"USA\",\n \"employmentStatus\": \"employed\",\n \"expectedMonthlyPayments\": \"5000_9999\",\n \"gender\": \"male\",\n \"nationality\": \"USA\",\n \"occupationSocCode\": \"151252\",\n \"residencyCountry\": \"USA\",\n \"sourceOfFunds\": \"salary\",\n \"stateOfBirth\": \"JAL\",\n \"taxIdentificationNumberDescription\": \"<string>\"\n },\n \"phone\": \"+13125559876\",\n \"representationDetails\": {\n \"isControlPerson\": true,\n \"isSigner\": true,\n \"ownershipPercentage\": \"50\",\n \"relationshipEstablishedAt\": \"2020-03-15\",\n \"roles\": [\n \"ubo\"\n ],\n \"title\": \"CEO\"\n },\n \"type\": \"individual\",\n \"dateOfBirth\": \"1990-01-15\",\n \"firstName\": \"Carlos\",\n \"lastName\": \"Souza\",\n \"middleName\": \"Carlos\"\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/business-representative")
.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 \"customerId\": \"customer_2f283221a9d44ada800ac7f11f640402\",\n \"email\": \"james.wilson@acmecorp.example.com\",\n \"personalInformation\": {\n \"taxIdentificationNumber\": \"123456789\",\n \"taxIdentificationNumberCountry\": \"USA\",\n \"taxIdentificationNumberType\": \"ssn\",\n \"accountPurpose\": \"receive_salary\",\n \"accountPurposeDescription\": \"<string>\",\n \"actingAsIntermediary\": false,\n \"countryOfBirth\": \"USA\",\n \"employmentStatus\": \"employed\",\n \"expectedMonthlyPayments\": \"5000_9999\",\n \"gender\": \"male\",\n \"nationality\": \"USA\",\n \"occupationSocCode\": \"151252\",\n \"residencyCountry\": \"USA\",\n \"sourceOfFunds\": \"salary\",\n \"stateOfBirth\": \"JAL\",\n \"taxIdentificationNumberDescription\": \"<string>\"\n },\n \"phone\": \"+13125559876\",\n \"representationDetails\": {\n \"isControlPerson\": true,\n \"isSigner\": true,\n \"ownershipPercentage\": \"50\",\n \"relationshipEstablishedAt\": \"2020-03-15\",\n \"roles\": [\n \"ubo\"\n ],\n \"title\": \"CEO\"\n },\n \"type\": \"individual\",\n \"dateOfBirth\": \"1990-01-15\",\n \"firstName\": \"Carlos\",\n \"lastName\": \"Souza\",\n \"middleName\": \"Carlos\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.spherepay.co/v2/business-representative")
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 \"customerId\": \"customer_2f283221a9d44ada800ac7f11f640402\",\n \"email\": \"james.wilson@acmecorp.example.com\",\n \"personalInformation\": {\n \"taxIdentificationNumber\": \"123456789\",\n \"taxIdentificationNumberCountry\": \"USA\",\n \"taxIdentificationNumberType\": \"ssn\",\n \"accountPurpose\": \"receive_salary\",\n \"accountPurposeDescription\": \"<string>\",\n \"actingAsIntermediary\": false,\n \"countryOfBirth\": \"USA\",\n \"employmentStatus\": \"employed\",\n \"expectedMonthlyPayments\": \"5000_9999\",\n \"gender\": \"male\",\n \"nationality\": \"USA\",\n \"occupationSocCode\": \"151252\",\n \"residencyCountry\": \"USA\",\n \"sourceOfFunds\": \"salary\",\n \"stateOfBirth\": \"JAL\",\n \"taxIdentificationNumberDescription\": \"<string>\"\n },\n \"phone\": \"+13125559876\",\n \"representationDetails\": {\n \"isControlPerson\": true,\n \"isSigner\": true,\n \"ownershipPercentage\": \"50\",\n \"relationshipEstablishedAt\": \"2020-03-15\",\n \"roles\": [\n \"ubo\"\n ],\n \"title\": \"CEO\"\n },\n \"type\": \"individual\",\n \"dateOfBirth\": \"1990-01-15\",\n \"firstName\": \"Carlos\",\n \"lastName\": \"Souza\",\n \"middleName\": \"Carlos\"\n}"
response = http.request(request)
puts response.read_body{
"createdAt": "2026-03-10T00:00:08.986Z",
"customerId": "customer_2f283221a9d44ada800ac7f11f640402",
"id": "associatedPerson_d972d2f70b9f4d3c8d7cfb32593f395b",
"type": "individual",
"updatedAt": "2026-03-10T00:00:08.986Z",
"verificationProfiles": [
{
"criteria": {
"complete": [
"email_address",
"phone_number",
"residential_address",
"tax_identification_number",
"ownership_percentage",
"is_control_person",
"is_signer",
"relationship_established_at",
"title"
],
"errors": [],
"pending": [],
"required": [
"identity_document",
"liveness_report_document",
"proof_of_address_document"
]
},
"name": "ubo_kyc_profile_a",
"status": "incomplete"
}
],
"address": {
"city": "<string>",
"country": "<string>",
"line1": "<string>",
"line2": "<string>",
"postalCode": "<string>",
"state": "<string>"
},
"dateOfBirth": "1985-03-12",
"email": "james.wilson@acmecorp.example.com",
"firstName": "James",
"lastName": "Wilson",
"phone": "+13125559876",
"representationDetails": {
"roles": [
"ubo"
],
"ownershipPercentage": "50",
"relationshipEstablishedAt": "2020-03-15",
"title": "CEO"
}
}{
"code": "address/invalid",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Invalid request parameters",
"status": 400
}{
"code": "resource/not-found",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Resource not found",
"status": 404
}{
"code": "customer/onboarding-v3-managed",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "This customer cannot be used with this route.",
"status": 409
}{
"code": "validation/failed",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Validation failed",
"errors": [
{
"detail": "Invalid email format",
"pointer": "/email"
},
{
"detail": "Name is required",
"pointer": "/name"
}
],
"status": 422
}Business Representatives
Register a Business UBO for KYB Verification
Create a new business representative for a customer.
Create a Business Representative
curl --request POST \
--url https://api.spherepay.co/v2/business-representative \
--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"
},
"customerId": "customer_2f283221a9d44ada800ac7f11f640402",
"email": "james.wilson@acmecorp.example.com",
"personalInformation": {
"taxIdentificationNumber": "123456789",
"taxIdentificationNumberCountry": "USA",
"taxIdentificationNumberType": "ssn",
"accountPurpose": "receive_salary",
"accountPurposeDescription": "<string>",
"actingAsIntermediary": false,
"countryOfBirth": "USA",
"employmentStatus": "employed",
"expectedMonthlyPayments": "5000_9999",
"gender": "male",
"nationality": "USA",
"occupationSocCode": "151252",
"residencyCountry": "USA",
"sourceOfFunds": "salary",
"stateOfBirth": "JAL",
"taxIdentificationNumberDescription": "<string>"
},
"phone": "+13125559876",
"representationDetails": {
"isControlPerson": true,
"isSigner": true,
"ownershipPercentage": "50",
"relationshipEstablishedAt": "2020-03-15",
"roles": [
"ubo"
],
"title": "CEO"
},
"type": "individual",
"dateOfBirth": "1990-01-15",
"firstName": "Carlos",
"lastName": "Souza",
"middleName": "Carlos"
}
'import requests
url = "https://api.spherepay.co/v2/business-representative"
payload = {
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"customerId": "customer_2f283221a9d44ada800ac7f11f640402",
"email": "james.wilson@acmecorp.example.com",
"personalInformation": {
"taxIdentificationNumber": "123456789",
"taxIdentificationNumberCountry": "USA",
"taxIdentificationNumberType": "ssn",
"accountPurpose": "receive_salary",
"accountPurposeDescription": "<string>",
"actingAsIntermediary": False,
"countryOfBirth": "USA",
"employmentStatus": "employed",
"expectedMonthlyPayments": "5000_9999",
"gender": "male",
"nationality": "USA",
"occupationSocCode": "151252",
"residencyCountry": "USA",
"sourceOfFunds": "salary",
"stateOfBirth": "JAL",
"taxIdentificationNumberDescription": "<string>"
},
"phone": "+13125559876",
"representationDetails": {
"isControlPerson": True,
"isSigner": True,
"ownershipPercentage": "50",
"relationshipEstablishedAt": "2020-03-15",
"roles": ["ubo"],
"title": "CEO"
},
"type": "individual",
"dateOfBirth": "1990-01-15",
"firstName": "Carlos",
"lastName": "Souza",
"middleName": "Carlos"
}
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'
},
customerId: 'customer_2f283221a9d44ada800ac7f11f640402',
email: 'james.wilson@acmecorp.example.com',
personalInformation: {
taxIdentificationNumber: '123456789',
taxIdentificationNumberCountry: 'USA',
taxIdentificationNumberType: 'ssn',
accountPurpose: 'receive_salary',
accountPurposeDescription: '<string>',
actingAsIntermediary: false,
countryOfBirth: 'USA',
employmentStatus: 'employed',
expectedMonthlyPayments: '5000_9999',
gender: 'male',
nationality: 'USA',
occupationSocCode: '151252',
residencyCountry: 'USA',
sourceOfFunds: 'salary',
stateOfBirth: 'JAL',
taxIdentificationNumberDescription: '<string>'
},
phone: '+13125559876',
representationDetails: {
isControlPerson: true,
isSigner: true,
ownershipPercentage: '50',
relationshipEstablishedAt: '2020-03-15',
roles: ['ubo'],
title: 'CEO'
},
type: 'individual',
dateOfBirth: '1990-01-15',
firstName: 'Carlos',
lastName: 'Souza',
middleName: 'Carlos'
})
};
fetch('https://api.spherepay.co/v2/business-representative', 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/business-representative",
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'
],
'customerId' => 'customer_2f283221a9d44ada800ac7f11f640402',
'email' => 'james.wilson@acmecorp.example.com',
'personalInformation' => [
'taxIdentificationNumber' => '123456789',
'taxIdentificationNumberCountry' => 'USA',
'taxIdentificationNumberType' => 'ssn',
'accountPurpose' => 'receive_salary',
'accountPurposeDescription' => '<string>',
'actingAsIntermediary' => false,
'countryOfBirth' => 'USA',
'employmentStatus' => 'employed',
'expectedMonthlyPayments' => '5000_9999',
'gender' => 'male',
'nationality' => 'USA',
'occupationSocCode' => '151252',
'residencyCountry' => 'USA',
'sourceOfFunds' => 'salary',
'stateOfBirth' => 'JAL',
'taxIdentificationNumberDescription' => '<string>'
],
'phone' => '+13125559876',
'representationDetails' => [
'isControlPerson' => true,
'isSigner' => true,
'ownershipPercentage' => '50',
'relationshipEstablishedAt' => '2020-03-15',
'roles' => [
'ubo'
],
'title' => 'CEO'
],
'type' => 'individual',
'dateOfBirth' => '1990-01-15',
'firstName' => 'Carlos',
'lastName' => 'Souza',
'middleName' => 'Carlos'
]),
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/business-representative"
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 \"customerId\": \"customer_2f283221a9d44ada800ac7f11f640402\",\n \"email\": \"james.wilson@acmecorp.example.com\",\n \"personalInformation\": {\n \"taxIdentificationNumber\": \"123456789\",\n \"taxIdentificationNumberCountry\": \"USA\",\n \"taxIdentificationNumberType\": \"ssn\",\n \"accountPurpose\": \"receive_salary\",\n \"accountPurposeDescription\": \"<string>\",\n \"actingAsIntermediary\": false,\n \"countryOfBirth\": \"USA\",\n \"employmentStatus\": \"employed\",\n \"expectedMonthlyPayments\": \"5000_9999\",\n \"gender\": \"male\",\n \"nationality\": \"USA\",\n \"occupationSocCode\": \"151252\",\n \"residencyCountry\": \"USA\",\n \"sourceOfFunds\": \"salary\",\n \"stateOfBirth\": \"JAL\",\n \"taxIdentificationNumberDescription\": \"<string>\"\n },\n \"phone\": \"+13125559876\",\n \"representationDetails\": {\n \"isControlPerson\": true,\n \"isSigner\": true,\n \"ownershipPercentage\": \"50\",\n \"relationshipEstablishedAt\": \"2020-03-15\",\n \"roles\": [\n \"ubo\"\n ],\n \"title\": \"CEO\"\n },\n \"type\": \"individual\",\n \"dateOfBirth\": \"1990-01-15\",\n \"firstName\": \"Carlos\",\n \"lastName\": \"Souza\",\n \"middleName\": \"Carlos\"\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/business-representative")
.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 \"customerId\": \"customer_2f283221a9d44ada800ac7f11f640402\",\n \"email\": \"james.wilson@acmecorp.example.com\",\n \"personalInformation\": {\n \"taxIdentificationNumber\": \"123456789\",\n \"taxIdentificationNumberCountry\": \"USA\",\n \"taxIdentificationNumberType\": \"ssn\",\n \"accountPurpose\": \"receive_salary\",\n \"accountPurposeDescription\": \"<string>\",\n \"actingAsIntermediary\": false,\n \"countryOfBirth\": \"USA\",\n \"employmentStatus\": \"employed\",\n \"expectedMonthlyPayments\": \"5000_9999\",\n \"gender\": \"male\",\n \"nationality\": \"USA\",\n \"occupationSocCode\": \"151252\",\n \"residencyCountry\": \"USA\",\n \"sourceOfFunds\": \"salary\",\n \"stateOfBirth\": \"JAL\",\n \"taxIdentificationNumberDescription\": \"<string>\"\n },\n \"phone\": \"+13125559876\",\n \"representationDetails\": {\n \"isControlPerson\": true,\n \"isSigner\": true,\n \"ownershipPercentage\": \"50\",\n \"relationshipEstablishedAt\": \"2020-03-15\",\n \"roles\": [\n \"ubo\"\n ],\n \"title\": \"CEO\"\n },\n \"type\": \"individual\",\n \"dateOfBirth\": \"1990-01-15\",\n \"firstName\": \"Carlos\",\n \"lastName\": \"Souza\",\n \"middleName\": \"Carlos\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.spherepay.co/v2/business-representative")
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 \"customerId\": \"customer_2f283221a9d44ada800ac7f11f640402\",\n \"email\": \"james.wilson@acmecorp.example.com\",\n \"personalInformation\": {\n \"taxIdentificationNumber\": \"123456789\",\n \"taxIdentificationNumberCountry\": \"USA\",\n \"taxIdentificationNumberType\": \"ssn\",\n \"accountPurpose\": \"receive_salary\",\n \"accountPurposeDescription\": \"<string>\",\n \"actingAsIntermediary\": false,\n \"countryOfBirth\": \"USA\",\n \"employmentStatus\": \"employed\",\n \"expectedMonthlyPayments\": \"5000_9999\",\n \"gender\": \"male\",\n \"nationality\": \"USA\",\n \"occupationSocCode\": \"151252\",\n \"residencyCountry\": \"USA\",\n \"sourceOfFunds\": \"salary\",\n \"stateOfBirth\": \"JAL\",\n \"taxIdentificationNumberDescription\": \"<string>\"\n },\n \"phone\": \"+13125559876\",\n \"representationDetails\": {\n \"isControlPerson\": true,\n \"isSigner\": true,\n \"ownershipPercentage\": \"50\",\n \"relationshipEstablishedAt\": \"2020-03-15\",\n \"roles\": [\n \"ubo\"\n ],\n \"title\": \"CEO\"\n },\n \"type\": \"individual\",\n \"dateOfBirth\": \"1990-01-15\",\n \"firstName\": \"Carlos\",\n \"lastName\": \"Souza\",\n \"middleName\": \"Carlos\"\n}"
response = http.request(request)
puts response.read_body{
"createdAt": "2026-03-10T00:00:08.986Z",
"customerId": "customer_2f283221a9d44ada800ac7f11f640402",
"id": "associatedPerson_d972d2f70b9f4d3c8d7cfb32593f395b",
"type": "individual",
"updatedAt": "2026-03-10T00:00:08.986Z",
"verificationProfiles": [
{
"criteria": {
"complete": [
"email_address",
"phone_number",
"residential_address",
"tax_identification_number",
"ownership_percentage",
"is_control_person",
"is_signer",
"relationship_established_at",
"title"
],
"errors": [],
"pending": [],
"required": [
"identity_document",
"liveness_report_document",
"proof_of_address_document"
]
},
"name": "ubo_kyc_profile_a",
"status": "incomplete"
}
],
"address": {
"city": "<string>",
"country": "<string>",
"line1": "<string>",
"line2": "<string>",
"postalCode": "<string>",
"state": "<string>"
},
"dateOfBirth": "1985-03-12",
"email": "james.wilson@acmecorp.example.com",
"firstName": "James",
"lastName": "Wilson",
"phone": "+13125559876",
"representationDetails": {
"roles": [
"ubo"
],
"ownershipPercentage": "50",
"relationshipEstablishedAt": "2020-03-15",
"title": "CEO"
}
}{
"code": "address/invalid",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Invalid request parameters",
"status": 400
}{
"code": "resource/not-found",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Resource not found",
"status": 404
}{
"code": "customer/onboarding-v3-managed",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "This customer cannot be used with this route.",
"status": 409
}{
"code": "validation/failed",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Validation failed",
"errors": [
{
"detail": "Invalid email format",
"pointer": "/email"
},
{
"detail": "Name is required",
"pointer": "/name"
}
],
"status": 422
}Register a business representative — an Ultimate Beneficial Owner (UBO), director, control person, or authorized signer — for a business customer. Each individual who directly or indirectly owns 25% or more of the business must be registered with the
ubo role before the business can be approved for transfers. You can also register directors, control persons, and authorized signers who do not meet the ownership threshold. After registration, complete the representative’s KYC by uploading their identity documents and, if using the Sphere-Managed model, generating a face verification link.
Any individual with an ownership stake of 25% or greater must be registered with the
ubo role. If no single person meets this threshold, register the individual with the highest ownership stake or the person with significant management control. ownershipPercentage accepts 0–100; the ubo role still requires ≥ 25. A representative without the ubo role (for example, director-only) may hold 0–24. EEA+ businesses must also register directors, control persons, and signers — see EEA+ businesses.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
The address of the business representative.
Show child attributes
Show child attributes
The ID of the business customer this representative belongs to.
Minimum string length:
1Example:
"customer_2f283221a9d44ada800ac7f11f640402"
The email address of the business representative.
Maximum string length:
254Example:
"james.wilson@acmecorp.example.com"
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
The phone number of the business representative.
Pattern:
^\+(?:[0-9]){6,14}[0-9]$Example:
"+13125559876"
The representation details of the business representative.
Show child attributes
Show child attributes
Example:
{
"isControlPerson": true,
"isSigner": true,
"ownershipPercentage": "50",
"relationshipEstablishedAt": "2020-03-15",
"roles": ["ubo"],
"title": "CEO"
}
The type of the business representative. Must be "individual".
Available options:
individual Example:
"individual"
The business representative's date of birth in YYYY-MM-DD format.
Example:
"1990-01-15"
The business representative's legal first name.
Required string length:
1 - 100Example:
"Carlos"
The business representative's legal last name.
Required string length:
1 - 100Example:
"Souza"
The business representative's legal middle name.
Required string length:
1 - 100Example:
"Carlos"
Response
The date and time the business representative was created.
Example:
"2026-03-10T00:00:08.986Z"
Customer ID
Example:
"customer_2f283221a9d44ada800ac7f11f640402"
Business Representative ID
Example:
"associatedPerson_d972d2f70b9f4d3c8d7cfb32593f395b"
Customer type
Available options:
individual Example:
"individual"
The date and time the business representative was last updated.
Example:
"2026-03-10T00:00:08.986Z"
Array of verification profiles for the business representative.
Show child attributes
Show child attributes
Example:
[
{
"criteria": {
"complete": [
"email_address",
"phone_number",
"residential_address",
"tax_identification_number",
"ownership_percentage",
"is_control_person",
"is_signer",
"relationship_established_at",
"title"
],
"errors": [],
"pending": [],
"required": [
"identity_document",
"liveness_report_document",
"proof_of_address_document"
]
},
"name": "ubo_kyc_profile_a",
"status": "incomplete"
}
]
The business representative's residential address.
Show child attributes
Show child attributes
The business representative's date of birth in YYYY-MM-DD format.
Example:
"1985-03-12"
Email address
Example:
"james.wilson@acmecorp.example.com"
The business representative's legal first name.
Example:
"James"
The business representative's legal last name.
Example:
"Wilson"
Phone number
Example:
"+13125559876"
Representation details
Show child attributes
Show child attributes
Last modified on August 24, 2026