Skip to main content
POST
/
customers
Create a customer
curl --request POST \
  --url https://api.polygon.technology/v0.9/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": [
    {
      "issuingCountry": "US",
      "number": "<string>"
    }
  ],
  "endorsements": [],
  "metadata": {}
}
'
{
  "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": [
    {
      "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"
}

Authorizations

​
Authorization
string
header
required

Token from POST /auth/token

Headers

​
Idempotency-Key
string
required

Unique key to prevent duplicate requests. Required on all 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.

​
type
enum<string>
required

Must be "individual". Only valid option for MVP.

Available options:
individual
Example:

"individual"

​
firstName
string

Customer's legal first name.

Example:

"Jane"

​
middleName
string

Customer's middle name.

​
lastName
string

Customer's legal last name.

Example:

"Smith"

​
email
string<email>
Example:

"jane@example.com"

​
phone
string

Primary phone in E.164 format.

Example:

"+12125551234"

​
birthDate
string
write-only

Date of birth in YYYY-MM-DD format. Write-only.

Example:

"1990-05-15"

​
nationality
string

ISO 3166-1 alpha-2 country code.

Example:

"US"

​
ipAddress
string
write-only

End-user's IP address. Used for geo-based compliance checks on the basic endorsement. Write-only.

​
externalId
string

Developer's own user ID for cross-referencing.

Example:

"usr_12345"

​
signedAgreement
boolean
default:false

Whether the customer has accepted OMS terms of service. Default false.

​
residentialAddress
object
write-only

Customer's residential address. Write-only.

​
identifyingInformation
object[]
write-only

Array of ID documents. Write-only. Supported types: ssn, itin, driversLicense, passport.

​
endorsements
enum<string>[]

Endorsements to request: basic, cryptoCustody, usd. If omitted, OMS defaults to cryptoCustody and usd (which auto-includes basic).

Available options:
basic,
cryptoCustody,
usd
​
metadata
object

Response

Customer created

Customer response object. PII fields (birthDate, residentialAddress, ipAddress, identifyingInformation) are write-only — accepted in POST/PATCH but never returned in responses.

​
id
string
Example:

"cst_01H9Xa8F5dN6mP3q"

​
object
string
Example:

"customer"

​
type
enum<string>

Customer type. Only individual is supported for MVP.

Available options:
individual
Example:

"individual"

​
firstName
string | null
Example:

"Jane"

​
middleName
string | null
Example:

null

​
lastName
string | null
Example:

"Smith"

​
email
string | null
Example:

"jane@example.com"

​
phone
string | null

Primary phone in E.164 format.

Example:

"+12125551234"

​
nationality
string | null

ISO 3166-1 alpha-2 country code.

Example:

"US"

​
externalId
string | null

Developer's own user ID for cross-referencing.

Example:

"usr_12345"

​
status
enum<string>

active or inactive. Inactive customers cannot create new transactions. No intermediate states — all granularity lives in endorsement statuses.

Available options:
active,
inactive
Example:

"active"

​
signedAgreement
boolean

Whether the customer has accepted OMS terms of service.

Example:

true

​
signedAgreementAt
string<date-time> | null

Timestamp when signedAgreement was set to true. Null if not yet signed.

Example:

"2026-03-20T14:15:22Z"

​
wallets
object[]

Simplified flat view: one entry per wallet-asset combination. Use GET /wallets/{id} for the full representation.

​
endorsements
object[]

Endorsements track KYC/compliance status. Types: basic, cryptoCustody, usd. Statuses use SCREAMING_CASE: INACTIVE, PENDING, ISSUES, ACTIVE, REJECTED, REVOKED_ISSUES, OFFBOARDED.

​
metadata
object
​
createdAt
string<date-time>
​
updatedAt
string<date-time>