Create a customer
curl --request POST \
--url https://sandbox-api.polygon.technology/v0.12/customers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"type": "individual",
"firstName": "Jane",
"middleName": "<string>",
"lastName": "Smith",
"email": "jane@example.com",
"phone": "+12125551234",
"birthDate": "1990-05-15",
"nationality": "US",
"ipAddress": "<string>",
"externalId": "usr_12345",
"signedAgreement": false,
"residentialAddress": {
"line1": "123 Main St",
"line2": "<string>",
"city": "New York",
"state": "NY",
"country": "US",
"zipCode": "10001"
},
"identifyingInformation": [
{
"type": "ssn",
"issuingCountry": "US",
"number": "123456789"
}
],
"endorsements": [],
"metadata": {}
}
'import requests
url = "https://sandbox-api.polygon.technology/v0.12/customers"
payload = {
"type": "individual",
"firstName": "Jane",
"middleName": "<string>",
"lastName": "Smith",
"email": "jane@example.com",
"phone": "+12125551234",
"birthDate": "1990-05-15",
"nationality": "US",
"ipAddress": "<string>",
"externalId": "usr_12345",
"signedAgreement": False,
"residentialAddress": {
"line1": "123 Main St",
"line2": "<string>",
"city": "New York",
"state": "NY",
"country": "US",
"zipCode": "10001"
},
"identifyingInformation": [
{
"type": "ssn",
"issuingCountry": "US",
"number": "123456789"
}
],
"endorsements": [],
"metadata": {}
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
type: 'individual',
firstName: 'Jane',
middleName: '<string>',
lastName: 'Smith',
email: 'jane@example.com',
phone: '+12125551234',
birthDate: '1990-05-15',
nationality: 'US',
ipAddress: '<string>',
externalId: 'usr_12345',
signedAgreement: false,
residentialAddress: {
line1: '123 Main St',
line2: '<string>',
city: 'New York',
state: 'NY',
country: 'US',
zipCode: '10001'
},
identifyingInformation: [{type: 'ssn', issuingCountry: 'US', number: '123456789'}],
endorsements: [],
metadata: {}
})
};
fetch('https://sandbox-api.polygon.technology/v0.12/customers', 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://sandbox-api.polygon.technology/v0.12/customers",
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([
'type' => 'individual',
'firstName' => 'Jane',
'middleName' => '<string>',
'lastName' => 'Smith',
'email' => 'jane@example.com',
'phone' => '+12125551234',
'birthDate' => '1990-05-15',
'nationality' => 'US',
'ipAddress' => '<string>',
'externalId' => 'usr_12345',
'signedAgreement' => false,
'residentialAddress' => [
'line1' => '123 Main St',
'line2' => '<string>',
'city' => 'New York',
'state' => 'NY',
'country' => 'US',
'zipCode' => '10001'
],
'identifyingInformation' => [
[
'type' => 'ssn',
'issuingCountry' => 'US',
'number' => '123456789'
]
],
'endorsements' => [
],
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$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://sandbox-api.polygon.technology/v0.12/customers"
payload := strings.NewReader("{\n \"type\": \"individual\",\n \"firstName\": \"Jane\",\n \"middleName\": \"<string>\",\n \"lastName\": \"Smith\",\n \"email\": \"jane@example.com\",\n \"phone\": \"+12125551234\",\n \"birthDate\": \"1990-05-15\",\n \"nationality\": \"US\",\n \"ipAddress\": \"<string>\",\n \"externalId\": \"usr_12345\",\n \"signedAgreement\": false,\n \"residentialAddress\": {\n \"line1\": \"123 Main St\",\n \"line2\": \"<string>\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"country\": \"US\",\n \"zipCode\": \"10001\"\n },\n \"identifyingInformation\": [\n {\n \"type\": \"ssn\",\n \"issuingCountry\": \"US\",\n \"number\": \"123456789\"\n }\n ],\n \"endorsements\": [],\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
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://sandbox-api.polygon.technology/v0.12/customers")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"type\": \"individual\",\n \"firstName\": \"Jane\",\n \"middleName\": \"<string>\",\n \"lastName\": \"Smith\",\n \"email\": \"jane@example.com\",\n \"phone\": \"+12125551234\",\n \"birthDate\": \"1990-05-15\",\n \"nationality\": \"US\",\n \"ipAddress\": \"<string>\",\n \"externalId\": \"usr_12345\",\n \"signedAgreement\": false,\n \"residentialAddress\": {\n \"line1\": \"123 Main St\",\n \"line2\": \"<string>\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"country\": \"US\",\n \"zipCode\": \"10001\"\n },\n \"identifyingInformation\": [\n {\n \"type\": \"ssn\",\n \"issuingCountry\": \"US\",\n \"number\": \"123456789\"\n }\n ],\n \"endorsements\": [],\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox-api.polygon.technology/v0.12/customers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"type\": \"individual\",\n \"firstName\": \"Jane\",\n \"middleName\": \"<string>\",\n \"lastName\": \"Smith\",\n \"email\": \"jane@example.com\",\n \"phone\": \"+12125551234\",\n \"birthDate\": \"1990-05-15\",\n \"nationality\": \"US\",\n \"ipAddress\": \"<string>\",\n \"externalId\": \"usr_12345\",\n \"signedAgreement\": false,\n \"residentialAddress\": {\n \"line1\": \"123 Main St\",\n \"line2\": \"<string>\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"country\": \"US\",\n \"zipCode\": \"10001\"\n },\n \"identifyingInformation\": [\n {\n \"type\": \"ssn\",\n \"issuingCountry\": \"US\",\n \"number\": \"123456789\"\n }\n ],\n \"endorsements\": [],\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"id": "cst_01H9Xa8F5dN6mP3q",
"object": "customer",
"type": "individual",
"firstName": "Jane",
"middleName": null,
"lastName": "Smith",
"email": "jane@example.com",
"phone": "+12125551234",
"nationality": "US",
"externalId": "usr_12345",
"status": "active",
"signedAgreement": true,
"signedAgreementAt": "2026-03-20T14:15:22Z",
"wallets": [
{
"id": "wlt_01H9Xb3K7nM2pQ4r",
"type": "custodial",
"address": "0x7B3a9F2c4D1eA8bF6390cE5d2B7fA104C8e3D9b1",
"network": "polygon",
"asset": "usdc",
"balance": "1234.56",
"estimatedValueUsd": "1234.56",
"createdAt": "2023-11-07T05:31:56Z"
}
],
"endorsements": [
{
"name": "basic",
"status": "INACTIVE",
"rejectionReasons": [
{
"developerReason": "<string>",
"reason": "<string>"
}
],
"requirements": {
"complete": [
"<string>"
],
"pending": [
"<string>"
],
"missing": [
"<string>"
],
"issues": [
"<string>"
]
}
}
],
"metadata": {},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}{
"error": "Unauthorized",
"code": 1000,
"msg": "unauthorized access",
"status": 401,
"cause": "signature"
}{
"error": "Unauthorized",
"code": 1000,
"msg": "unauthorized access",
"status": 401,
"cause": "signature"
}Customers
Create a customer
POST
/
customers
Create a customer
curl --request POST \
--url https://sandbox-api.polygon.technology/v0.12/customers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"type": "individual",
"firstName": "Jane",
"middleName": "<string>",
"lastName": "Smith",
"email": "jane@example.com",
"phone": "+12125551234",
"birthDate": "1990-05-15",
"nationality": "US",
"ipAddress": "<string>",
"externalId": "usr_12345",
"signedAgreement": false,
"residentialAddress": {
"line1": "123 Main St",
"line2": "<string>",
"city": "New York",
"state": "NY",
"country": "US",
"zipCode": "10001"
},
"identifyingInformation": [
{
"type": "ssn",
"issuingCountry": "US",
"number": "123456789"
}
],
"endorsements": [],
"metadata": {}
}
'import requests
url = "https://sandbox-api.polygon.technology/v0.12/customers"
payload = {
"type": "individual",
"firstName": "Jane",
"middleName": "<string>",
"lastName": "Smith",
"email": "jane@example.com",
"phone": "+12125551234",
"birthDate": "1990-05-15",
"nationality": "US",
"ipAddress": "<string>",
"externalId": "usr_12345",
"signedAgreement": False,
"residentialAddress": {
"line1": "123 Main St",
"line2": "<string>",
"city": "New York",
"state": "NY",
"country": "US",
"zipCode": "10001"
},
"identifyingInformation": [
{
"type": "ssn",
"issuingCountry": "US",
"number": "123456789"
}
],
"endorsements": [],
"metadata": {}
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
type: 'individual',
firstName: 'Jane',
middleName: '<string>',
lastName: 'Smith',
email: 'jane@example.com',
phone: '+12125551234',
birthDate: '1990-05-15',
nationality: 'US',
ipAddress: '<string>',
externalId: 'usr_12345',
signedAgreement: false,
residentialAddress: {
line1: '123 Main St',
line2: '<string>',
city: 'New York',
state: 'NY',
country: 'US',
zipCode: '10001'
},
identifyingInformation: [{type: 'ssn', issuingCountry: 'US', number: '123456789'}],
endorsements: [],
metadata: {}
})
};
fetch('https://sandbox-api.polygon.technology/v0.12/customers', 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://sandbox-api.polygon.technology/v0.12/customers",
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([
'type' => 'individual',
'firstName' => 'Jane',
'middleName' => '<string>',
'lastName' => 'Smith',
'email' => 'jane@example.com',
'phone' => '+12125551234',
'birthDate' => '1990-05-15',
'nationality' => 'US',
'ipAddress' => '<string>',
'externalId' => 'usr_12345',
'signedAgreement' => false,
'residentialAddress' => [
'line1' => '123 Main St',
'line2' => '<string>',
'city' => 'New York',
'state' => 'NY',
'country' => 'US',
'zipCode' => '10001'
],
'identifyingInformation' => [
[
'type' => 'ssn',
'issuingCountry' => 'US',
'number' => '123456789'
]
],
'endorsements' => [
],
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$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://sandbox-api.polygon.technology/v0.12/customers"
payload := strings.NewReader("{\n \"type\": \"individual\",\n \"firstName\": \"Jane\",\n \"middleName\": \"<string>\",\n \"lastName\": \"Smith\",\n \"email\": \"jane@example.com\",\n \"phone\": \"+12125551234\",\n \"birthDate\": \"1990-05-15\",\n \"nationality\": \"US\",\n \"ipAddress\": \"<string>\",\n \"externalId\": \"usr_12345\",\n \"signedAgreement\": false,\n \"residentialAddress\": {\n \"line1\": \"123 Main St\",\n \"line2\": \"<string>\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"country\": \"US\",\n \"zipCode\": \"10001\"\n },\n \"identifyingInformation\": [\n {\n \"type\": \"ssn\",\n \"issuingCountry\": \"US\",\n \"number\": \"123456789\"\n }\n ],\n \"endorsements\": [],\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
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://sandbox-api.polygon.technology/v0.12/customers")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"type\": \"individual\",\n \"firstName\": \"Jane\",\n \"middleName\": \"<string>\",\n \"lastName\": \"Smith\",\n \"email\": \"jane@example.com\",\n \"phone\": \"+12125551234\",\n \"birthDate\": \"1990-05-15\",\n \"nationality\": \"US\",\n \"ipAddress\": \"<string>\",\n \"externalId\": \"usr_12345\",\n \"signedAgreement\": false,\n \"residentialAddress\": {\n \"line1\": \"123 Main St\",\n \"line2\": \"<string>\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"country\": \"US\",\n \"zipCode\": \"10001\"\n },\n \"identifyingInformation\": [\n {\n \"type\": \"ssn\",\n \"issuingCountry\": \"US\",\n \"number\": \"123456789\"\n }\n ],\n \"endorsements\": [],\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox-api.polygon.technology/v0.12/customers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"type\": \"individual\",\n \"firstName\": \"Jane\",\n \"middleName\": \"<string>\",\n \"lastName\": \"Smith\",\n \"email\": \"jane@example.com\",\n \"phone\": \"+12125551234\",\n \"birthDate\": \"1990-05-15\",\n \"nationality\": \"US\",\n \"ipAddress\": \"<string>\",\n \"externalId\": \"usr_12345\",\n \"signedAgreement\": false,\n \"residentialAddress\": {\n \"line1\": \"123 Main St\",\n \"line2\": \"<string>\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"country\": \"US\",\n \"zipCode\": \"10001\"\n },\n \"identifyingInformation\": [\n {\n \"type\": \"ssn\",\n \"issuingCountry\": \"US\",\n \"number\": \"123456789\"\n }\n ],\n \"endorsements\": [],\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"id": "cst_01H9Xa8F5dN6mP3q",
"object": "customer",
"type": "individual",
"firstName": "Jane",
"middleName": null,
"lastName": "Smith",
"email": "jane@example.com",
"phone": "+12125551234",
"nationality": "US",
"externalId": "usr_12345",
"status": "active",
"signedAgreement": true,
"signedAgreementAt": "2026-03-20T14:15:22Z",
"wallets": [
{
"id": "wlt_01H9Xb3K7nM2pQ4r",
"type": "custodial",
"address": "0x7B3a9F2c4D1eA8bF6390cE5d2B7fA104C8e3D9b1",
"network": "polygon",
"asset": "usdc",
"balance": "1234.56",
"estimatedValueUsd": "1234.56",
"createdAt": "2023-11-07T05:31:56Z"
}
],
"endorsements": [
{
"name": "basic",
"status": "INACTIVE",
"rejectionReasons": [
{
"developerReason": "<string>",
"reason": "<string>"
}
],
"requirements": {
"complete": [
"<string>"
],
"pending": [
"<string>"
],
"missing": [
"<string>"
],
"issues": [
"<string>"
]
}
}
],
"metadata": {},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}{
"error": "Unauthorized",
"code": 1000,
"msg": "unauthorized access",
"status": 401,
"cause": "signature"
}{
"error": "Unauthorized",
"code": 1000,
"msg": "unauthorized access",
"status": 401,
"cause": "signature"
}Authorizations
Token from POST /auth/token
Headers
Client-supplied request key. Required on all non-auth POST requests.
Body
application/json
Create a new individual customer. Almost all fields are optional — only type is required. PII fields (birthDate, residentialAddress, ipAddress, identifyingInformation) are write-only and never returned in responses.
Must be "individual". Only valid option for MVP.
Available options:
individual Example:
"individual"
Customer's legal first name.
Example:
"Jane"
Customer's middle name.
Customer's legal last name.
Example:
"Smith"
Example:
"jane@example.com"
Primary phone in E.164 format.
Example:
"+12125551234"
Date of birth in YYYY-MM-DD format. Write-only.
Example:
"1990-05-15"
ISO 3166-1 alpha-2 country code.
Example:
"US"
End-user's IP address. Used for geo-based compliance checks on the basic endorsement. Write-only.
Developer's own user ID for cross-referencing.
Example:
"usr_12345"
Whether the customer has accepted OMS terms of service. Default false.
Customer's residential address. Write-only.
Hide child attributes
Hide child attributes
Array of ID documents. Write-only. Supported types: ssn, itin, driversLicense, passport.
Hide child attributes
Hide child attributes
Available options:
ssn, itin, driversLicense, passport Example:
"ssn"
ISO 3166-1 alpha-2 country code.
Example:
"US"
The identification number.
Example:
"123456789"
Endorsements to request: basic, cryptoCustody, usd. If omitted, OMS defaults to cryptoCustody and usd (which auto-includes basic).
Available options:
basic, cryptoCustody, usd Response
Customer created
Customer response object. PII fields (birthDate, residentialAddress, ipAddress, identifyingInformation) are write-only — accepted in POST/PATCH but never returned in responses.
Example:
"cst_01H9Xa8F5dN6mP3q"
Example:
"customer"
Customer type. Only individual is supported for MVP.
Available options:
individual Example:
"individual"
Example:
"Jane"
Example:
null
Example:
"Smith"
Example:
"jane@example.com"
Primary phone in E.164 format.
Example:
"+12125551234"
ISO 3166-1 alpha-2 country code.
Example:
"US"
Developer's own user ID for cross-referencing.
Example:
"usr_12345"
active or inactive. Inactive customers cannot create new transactions. No intermediate states — all granularity lives in endorsement statuses.
Available options:
active, inactive Example:
"active"
Whether the customer has accepted OMS terms of service.
Example:
true
Timestamp when signedAgreement was set to true. Null if not yet signed.
Example:
"2026-03-20T14:15:22Z"
Simplified flat view: one entry per wallet-asset combination. Use GET /wallets/{id} for the full representation.
Hide child attributes
Hide child attributes
Example:
"wlt_01H9Xb3K7nM2pQ4r"
Example:
"custodial"
Example:
"0x7B3a9F2c4D1eA8bF6390cE5d2B7fA104C8e3D9b1"
Example:
"polygon"
Example:
"usdc"
Example:
"1234.56"
Example:
"1234.56"
Endorsements track KYC/compliance status. Types: basic, cryptoCustody, usd. Statuses use SCREAMING_CASE: INACTIVE, PENDING, ISSUES, ACTIVE, REJECTED, REVOKED_ISSUES, OFFBOARDED.
Hide child attributes
Hide child attributes
Available options:
basic, cryptoCustody, usd Available options:
INACTIVE, PENDING, ISSUES, ACTIVE, REJECTED, REVOKED_ISSUES, OFFBOARDED Was this page helpful?
⌘I