This documentation describes API 4.4.0, updated October 13, 2026. Review the release notes and error handling and recovery. Bearer authentication, idempotency, parent checks, and payload validation remain required.
Choose single or batch ingestion
| Endpoint | Use it for | Key location |
|---|---|---|
POST /ingest | One business event | Idempotency-Key header |
POST /ingest/batch | 1-100 events of one category | idempotency_key inside each item |
Both use Authorization: Bearer YOUR_API_KEY, JSON bodies, synchronous processing, and a 1 MiB total body limit. Public callers do not need internal service credentials. Use sandbox for integration testing; confirm availability before production rollout.
Send a complete event
POST /ingest
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: create-company-001
Content-Type: application/json{
"category": "client",
"data": {
"step": "create",
"client_id": "COMPANY-001",
"name": "Acme Trading",
"email": "finance@acme.example",
"phone": "+15550001031",
"address": "100 Market Street",
"country": "US",
"is_company": true,
"registration_number": "REG-001",
"contact_person": "Jane Smith"
}
}Company gender is normalized to company; individual creates require gender. Unknown envelope/data fields are rejected. Do not send database audit fields, content_hash, content_hash_version, or request_hash_version. Declared info objects can contain custom metadata, including literal own __proto__ keys. Supplied field types are checked before defaults can replace values; JSON hashing is bounded to 32 nested levels and 100,000 values. Use the local validator for structural checks, not proof that database references exist.
JSON strings and property names must contain valid Unicode without U+0000 or unpaired surrogates. Dates must be real calendar dates with a year greater than zero; timestamp offsets cannot exceed 15:59. Integer fields reject fractions and values outside their declared bounds. On updates, omitted fields preserve stored values and null is accepted only where the field is nullable. Conditional requirements are checked against the merged record.
Categories and ordering
| Category | Guide | Dependency |
|---|---|---|
client | Client fields | Create before referring to the client |
disbursement | Loan/purchase fields | Loan client or optional purchase-client links |
payment | Payment fields | Parent disbursement; purchase client must be linked |
operation | Operation fields | Parent disbursement |
Steps remain create, update, and delete. Duplicate business-ID creates return 409; they are not upserts. Missing update targets return 404. Old categories such as loan, purchase, schedule, insurance, and worker-managed status/history categories are not accepted.
Idempotency: preserve the original request
- Use a nonblank, case-sensitive key of at most 255 UTF-8 bytes. UUID is recommended, not required. Keys are tenant-scoped and remain reserved while their event records exist; waiting for a cache timeout does not release a key.
- Identical stored request/key pairs replay the original HTTP status and body, not a generic duplicate response. Object-property ordering does not matter.
- New request hashing preserves all own JSON keys. Historical events must also retain enough payload evidence to prove an exact retry: if earlier hashing/defaulting lost submitted object values, the API returns
409 IDEMPOTENCY_KEY_REUSEDwithout executing again or replacing the original response. - Changing category, step, or payload under a stored key returns
409 IDEMPOTENCY_KEY_REUSED. This includes different submitted amounts that happen to round to the same cents. - Persist the original key and body before first sending. After a timeout, process restart, or lost response, retry the same original content and key. Do not create a new logical event just because a response was lost.
- Recorded business failures replay their original rejection, including
error_id. After resolving the issue, use a new key even if only related resource state changed and the payload stays the same. Validation before key reservation does not consume the key; followactionto correct that request. Rolled-back work can be retried with the original key and body. - Older events may replay bodies without the newer fields. A legacy pending event can return
409 IDEMPOTENCY_REQUEST_IN_PROGRESS; contact support if it persists.
Interpret responses
| Outcome | HTTP | status | action |
|---|---|---|---|
| Create | 201 | added | created |
| Changed update | 201 | added | updated |
| Unchanged update | 200 | unchanged | unchanged |
| Delete | 201 | added | deleted |
| Exact replay | Original | Original | Original, if present |
New successful responses include the business id, event_id, and idempotency_key. Creates/updates also include a server-computed content_hash; deletes omit it. Keep the business ID separate from the event identifier.
An unchanged update still records an ingest event/response without changing business data, refreshing business timestamps, or generating child/history effects. An older/unknown content-hash version may receive a metadata-only hash/version repair after the server verifies unchanged business content. Treat it as success. Partial updates are merged with the stored row before hashing.
Money is rounded by the API, not rejected for extra decimals: 10.255 becomes 10.26. Read money and rounding for sign/range rules, derived sums, and retry implications. Use batch ingestion for bulk work and synchronization to avoid unnecessary updates.
Errors and support
| HTTP | Meaning | Client action |
|---|---|---|
400 | Invalid structure/field/key, money overflow, or parent/client validation | Correct the request; use a new key if a terminal event was recorded |
401 | Missing/invalid bearer key | Check your credentials |
404 | Update target missing | Reconcile IDs before choosing a step |
409 | Changed-content key reuse, duplicate ID, or restricted deletion | Inspect code; these are distinct conflicts |
413 | Body larger than 1 MiB | Reduce the request; split bulk items, not one logical event |
500 | Unexpected processing/storage failure | Follow retryable and action; preserve the original content/key if the outcome is uncertain |
503 SCHEMA_NOT_READY | Tenant setup incomplete | Pause affected requests and contact support; retries do not perform setup |
Other 503 | Authentication storage or a dependency is unavailable | Follow code, retryable, and action; operator intervention may be required |
New errors include stable code, human-readable error, recovery action, retryable, and error_id, with applicable field-level issues and business context. Use code for handling and show issues to explain rejected fields. Historical stored responses replay unchanged and can lack these fields; fall back to their HTTP status and string error.
Keep both error_id and the response's X-Correlation-ID for support. The header traces the current request, including a replay; the error ID stays attached to a recorded failure. See errors and recovery for examples, public codes, and safe retries after non-JSON or lost responses.
GET /health is public and returns status, environment, and timestamp; it does not prove your tenant is ready. See the API reference for exact schemas.
