Customer onboarding flow
1
App
→
OMS
POST /customers
2
OMS
→
App
\{id: "cst\_...", endorsements: \[...]}
3
App
→
User
Collect identity documents
4
User
→
App
KYC data
5
App
→
OMS
Submit verification (endorsement review)
6
OMS
→
App
Endorsements active
7
App
→
OMS
POST /customers/\{id}/wallets
8
OMS
→
Polygon
Derive wallet address
9
OMS
→
App
\{id: "wlt\_...", address: "0x..."}
10
App
→
OMS
POST /external-accounts
11
OMS
→
App
\{id: "ext\_bankUs\_...", status: "pending"}
***
## Prerequisites
* An OMS API key.
* Webhook endpoints registered with `POST /webhooks` (or in the OMS Dashboard) if you plan to react to status changes as endorsements advance and transactions settle.
***
## Step 1: Create a customer
Register the end user with a `POST /customers` call. OMS creates the record and returns an ID. To onboard a customer who can move USD or use cash services, send the full set of identifying fields, not just a name, and request the `endorsements` the customer needs.
### Request
```text theme={null}
POST /v0.10/customers
Authorization: Bearer {accessToken}
Idempotency-Key: cst-alice-001
Content-Type: application/json
```
```json theme={null}
{
"type": "individual",
"firstName": "Alice",
"lastName": "Martin",
"email": "alice@example.com",
"phone": "+12125551234",
"birthDate": "1990-05-15",
"nationality": "US",
"residentialAddress": {
"line1": "123 Main St",
"city": "New York",
"state": "NY",
"country": "US",
"zipCode": "10001"
},
"identifyingInformation": [
{ "type": "ssn", "issuingCountry": "US", "number": "123-45-6789" }
],
"externalId": "usr_7890",
"signedAgreement": true,
"endorsements": ["basic", "cryptoCustody", "usd"]
}
```
**Required field:** `type` must be `individual`. Only the individual customer type is supported today.
**`endorsements`** declares which capabilities the customer needs: `basic` (identity and geo checks), `cryptoCustody` (custodial wallets that hold stablecoins), and `usd` (USD movement over fiat rails, including bank payouts, virtual accounts, and cash services). Requesting `cryptoCustody` or `usd` auto-includes `basic`. If you omit `endorsements`, OMS defaults to `cryptoCustody` and `usd`. Request endorsements through the Customers API.
**`externalId`** is the recommended way to link the OMS customer record to your internal user ID. Pass it at creation to avoid a separate update call later.
### Response, `201 Created`
```json theme={null}
{
"id": "cst_01H9Xa...",
"object": "customer",
"type": "individual",
"firstName": "Alice",
"lastName": "Martin",
"email": "alice@example.com",
"externalId": "usr_7890",
"status": "active",
"endorsements": [
{ "name": "basic", "status": "ACTIVE" },
{ "name": "cryptoCustody", "status": "ACTIVE" },
{ "name": "usd", "status": "PENDING" }
],
"wallets": [],
"createdAt": "2026-01-15T10:00:00Z"
}
```
The `status` field is `active` or `inactive`; all the granularity lives in the per-endorsement `status`, which uses SCREAMING\_CASE (`INACTIVE`, `PENDING`, `ISSUES`, `ACTIVE`, `REJECTED`, `REVOKED_ISSUES`, `OFFBOARDED`). An endorsement must reach `ACTIVE` before its capability unlocks. PII fields (`birthDate`, `residentialAddress`, `ipAddress`, `identifyingInformation`) are write-only: OMS accepts them but never returns them. A customer created without the identifying fields cannot be provisioned to move fiat.
***
## Step 2: Collect identity and unlock endorsements
OMS uses an endorsement model to gate access to financial operations. An endorsement tracks the KYC and compliance status behind a capability. Request the endorsements a customer needs at creation, or add them later with `PATCH /customers/{customerId}`.
| Endorsement | Unlocks |
| --------------- | ----------------------------------------------------------------------------------- |
| `basic` | Identity and geo-based compliance checks. Auto-included with any other endorsement. |
| `cryptoCustody` | Custodial wallets that hold stablecoins. |
| `usd` | USD movement over fiat rails: US bank payouts, virtual accounts, and cash services. |
Your KYC flow submits identity documents to OMS for review, which advances each requested endorsement toward `ACTIVE`. Provisioning reads the identifying fields above, so include them even in sandbox, where endorsements are auto-approved.