Developers
Show batch ingestion and synchronization guides and endpoints, core concepts, and the content hash calculator.
Explore the docs

Get started

Send your first event

Your first request, from authentication to a successful response.

On this page

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

EndpointUse it forKey location
POST /ingestOne business eventIdempotency-Key header
POST /ingest/batch1-100 events of one categoryidempotency_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

http
POST /ingest
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: create-company-001
Content-Type: application/json
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

CategoryGuideDependency
clientClient fieldsCreate before referring to the client
disbursementLoan/purchase fieldsLoan client or optional purchase-client links
paymentPayment fieldsParent disbursement; purchase client must be linked
operationOperation fieldsParent 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_REUSED without 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; follow action to 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

OutcomeHTTPstatusaction
Create201addedcreated
Changed update201addedupdated
Unchanged update200unchangedunchanged
Delete201addeddeleted
Exact replayOriginalOriginalOriginal, 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

HTTPMeaningClient action
400Invalid structure/field/key, money overflow, or parent/client validationCorrect the request; use a new key if a terminal event was recorded
401Missing/invalid bearer keyCheck your credentials
404Update target missingReconcile IDs before choosing a step
409Changed-content key reuse, duplicate ID, or restricted deletionInspect code; these are distinct conflicts
413Body larger than 1 MiBReduce the request; split bulk items, not one logical event
500Unexpected processing/storage failureFollow retryable and action; preserve the original content/key if the outcome is uncertain
503 SCHEMA_NOT_READYTenant setup incompletePause affected requests and contact support; retries do not perform setup
Other 503Authentication storage or a dependency is unavailableFollow 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.

Validate locally. Verify in sandbox.
The JSON validator checks structure and rounding. Credentials, existing records, and server-side state still require your test environment.

Search documentation

Start typing to find your next step.

    ↑ ↓ navigate Enter openLocal, private search