HTTP Response Codes
The response shape onboarding returns, the HTTP status codes you'll see, and how sensitive fields are formatted and masked.
Onboarding uses standard HTTP status codes and a consistent response shape across every endpoint. This page is the reference for what a call returns.
Response shape
- A single resource returns a flat JSON object: the resource fields at the top level, with no
{ data: … }envelope. - A list returns a bare JSON array.
POST,GET, andPATCHon a business all return the same object shape; only the populated values differ by lifecycle stage.
Status codes
| Code | When you'll see it |
|---|---|
201 Created | A resource was created. The body carries the new resource, its type-prefixed id, and a uri. |
204 No Content | A non-destructive delete succeeded (a business soft-close). No body. |
400 Bad Request | The body isn't valid JSON, or it's empty, while Content-Type: application/json is set. |
401 Unauthorized | The x-api-key credential is missing or invalid. |
404 Not Found | The addressed resource doesn't exist (for example, Entity not found). |
409 Conflict | A conflicting externalId was provided. |
422 Unprocessable | Validation failed: a field is missing or malformed, a KYB rule is broken, an unknown query parameter was sent, or a paging value is out of range. |
For the message shapes and the common validation and KYB messages, see API Error Handling.
Field formats and masking
| Convention | Rule |
|---|---|
| Money and numbers | Percentages, caps, and counts are plain JSON numbers (for example ownershipPercentage: 50.00). |
| Phone | E.164 where required (for example "+15125551234"). |
| Timestamps | ISO-8601 UTC strings (createdAt, updatedAt). |
| Sensitive fields | Written in full, returned masked: accountNumber → accountNumberLast4; routingNumber is not returned on read; taxId.value → lastFour; governmentIds[].number → numberLastFour. |
PENDING-PUBLISHThe exact status-code set, response bodies, and the full masked-field set are drawn from the boarding contract and the tested collection while the boarding spec is out of
reference/. Confirm them against the published API Reference before publish.
See also
- API Error Handling: the error message shapes and how to resolve them
- Idempotent Requests: safe retries with
externalId - Getting Started: creating and updating entities
Updated 1 day ago
Did this page help you?