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

Work with data

Synchronization

Reconcile your records using version-3 content hashes and sync state.

On this page

At a glance#

  • Page compact ID/hash pairs for clients, disbursements, operations, or payments.
  • Compare resolved business state using version-3 hashes, not raw request JSON.
  • Never submit content_hash or treat a missing source record as permission to delete.

Use GET /api/sync-state/{table} to retrieve compact tenant state. Authenticate with your bearer API key. The only supported tables are clients, disbursements, operations, payments.

Read and page state

http
GET /api/sync-state/payments?limit=1000
Authorization: Bearer YOUR_API_KEY

The response has content_hash_version: 3, data containing {id, content_hash} pairs, and pagination with limit, has_more, and optional next_cursor. Every returned row must have a valid stored v3 hash. An empty tenant returns:

json
{"content_hash_version": 3, "data": [], "pagination": {"limit": 1000, "has_more": false}}

limit is an integer from 1 to 5000, default 1000. Results sort by ascending business ID. Follow the opaque next_cursor, URL-encoded; never construct one from the final ID. Stop when has_more is false. Only limit and cursor are accepted; invalid limits/cursors and unknown or duplicate query parameters return 400 with query issue paths. The total query limit is 8192 characters, with 4096 per value and no control characters.

Reconcile deliberately

  1. Gather the source business IDs and page the server state.
  2. Source ID absent on the server: plan a create.
  3. ID exists and complete, comparable v3 hashes match: skip the write.
  4. ID exists but business content differs: plan an update with a fresh event key.
  5. Review source-missing records separately; absence is not automatic authorization to delete them.
  6. Apply parent-before-child ordering, then inspect every result if using batches.

Clients that cannot reproduce canonicalization exactly should use ID-based reconciliation and let the API detect unchanged updates. Hash equality is not a guarantee of a transactionally frozen snapshot while other callers write.

Never send content_hash, content_hash_version, or request_hash_version in an ingest payload. They are server-managed. Partial updates merge with the existing row before hashing. A matching current-v3 update returns 200 unchanged without changing business data, timestamps, or generated child effects; the request event is still recorded. An older/unknown stored version may receive only a hash/version repair after the server verifies unchanged business content.

Version 3 canonicalization

The complete content hash specification includes the shared downloadable module and exact field/serialization rules. Use the local calculator to verify your implementation. If local hashing fails or context is missing, submit the normal update for that item rather than skipping it; the API still validates and detects unchanged content.

API 4.4.0 retains hash version 3, introduced in 4.3.0. It preserves literal own __proto__ keys while retaining the version-2 normalization rules, including resolved pledge_creditor and custom-creditor preservation on omitted updates. When upgrading from older hashes, operators migrate schema/hash metadata and backfill with the corrected writer; clients then refresh cached sync state. A v2 calculator must fall back to normal updates until upgraded. The 4.4.0 error-reporting changes do not introduce a new hash version or require another backfill for already valid v3 data.

The SHA-256 input is UTF-8 JSON with recursively sorted own keys in an envelope containing data, the plural table name, and version: 3. A hash of arbitrary incoming JSON will not match.

  • Exclude step, content_hash, content_hash_version, request_hash_version, event_id, original_event_id, created_at, updated_at, change_date, and change_reason; omit null object values.
  • Trim contract string fields. Normalize timestamps to UTC Z; preserve date-only values.
  • Round money to cents and represent it at persisted two-decimal scale. Do not apply that rule to ratios, counts, or arbitrary nested info values.
  • Recursively sort own object keys, preserving literal __proto__, and omit nested null object values. Omit empty top-level objects, so default info: {} equals omission. Preserve ordinary array order; sort purchase_clients by client_id.
  • Account for server defaults: company gender company, payment source client, disbursement is_pledged: true, coverage 0.9, fee 0.00, and default gross from individually rounded amount plus fee. Numeric coverage strings have trailing zeros removed for canonicalization.
  • Account for server-resolved values and existing rows when constructing the business state; a partial update is not a complete state hash. Version-3 examples are interoperability checks, not a substitute for the full field/default contract.

The trimmed string fields are client_id, name, email, phone, address, country, registration_number, contact_person, gender, disbursement_id, payment_id, operation_id, currency, kind, status, and source. Other strings, including arbitrary metadata, retain their whitespace. Timestamp normalization removes a zero millisecond part and trailing fractional zeros. Non-money integer numbers remain JSON numbers; non-integer numbers become plain decimal strings without insignificant trailing zeros, including inside info. This is hash formatting, not monetary rounding. Null array entries remain in place, unlike omitted null object properties.

Construct state from the documented business fields, not an entire read row: omit ignored legacy entity_type/entity_id and read-only/audit fields. For purchase disbursements include the effective purchase_clients links (an empty array when there are none); normalize each linked ID before sorting. Resolve loan payment client_id from its parent. Apply ingestion defaults and stored-value preservation first, including pledge_creditor: "CMK Capital" on create and the existing creditor when omitted on update. These resolved values belong in the hash input even when absent from the submitted event.

Download the version-3 language-neutral vectors. They include input/equivalent values, canonical JSON, and expected digests. They are not complete ingest requests. Decimal strings in equivalent values represent stored database values, not accepted request amount types. Match the parsed-number semantics before rounding; a decimal library cannot restore precision already lost in JSON parsing.

Version-1 and version-2 vectors are historical and must not be used for live v3 comparisons. The v3 envelope produces a new digest even when business values need no change. The hash version, documentation snapshot, and tenant setup version are different concepts.

Readiness and errors

  • 401: check bearer credentials.
  • 400: unsupported table, malformed cursor, or invalid limit.
  • 409 CONTENT_HASH_NOT_INITIALIZED: a page contains a missing/invalid hash or an older/unknown stored version. Pause hash comparison and ask the operator to run the current content-hash backfill, then refresh the snapshot. Normal ingestion remains available; do not reset or delete tenant data.
  • 503 SCHEMA_NOT_READY: pause affected operations and contact support; retries do not perform tenant setup.
  • Other 500 / 503: unexpected read, authentication-storage, or dependency failure; follow retryable and action.

New errors expose stable code, applicable issues, and recovery instructions. Keep error_id and the current X-Correlation-ID for support. See errors and recovery.

Retry hashes remain different

Business values 10.251 and 10.254 both round to 10.25, but changing the submitted value under a stored idempotency key still returns 409. Preserve original content and keys on retries; read the ingestion response guide.

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