Skip to main content

Responses and conventions

Learn these once; they apply to every endpoint.

The two envelopes​

Single-object operations return a service result:

{
  "Result": true,
  "Data": { "Id": 42, "Name": "…" },
  "Errors": null,
  "ValidationErrors": null
}

On failure Result is false and Errors carries one or more entries:

{
  "Result": false,
  "Errors": [
    { "Code": "NOT_FOUND", "Category": 3, "Message": "…" }
  ]
}

Always branch on the HTTP status first, then on Errors[].Code — the codes are stable strings meant for machines; the Message is for humans and may change. See the error registry.

List operations return a paged result:

{
  "Items": [ … ],
  "TotalCount": 8231
}

TotalCount is the total across all pages, not the page size.

The platform dialect​

Five conventions that surprise every new integrator — read them now and skip the debugging session:

  • Property names are PascalCase (StartedAtUtc, not startedAtUtc), in requests and responses alike.
  • Timestamps are UTC but carry no zone marker: "2026-08-29T06:15:00" means 06:15 UTC. Parse accordingly (DateTimeKind.Utc, Instant.parse after appending Z, …); parsing it as local time is the classic one-hour-off bug. Properties named …Utc and …Local say which clock they use.
  • Enums serialize as integers in responses ("Status": 4). The reference documents each enum's values. In requests, list filters accept enum names or numbers.
  • Null fields are omitted from responses rather than sent as null.
  • X-Correlation-Id — every response echoes one (send your own to propagate it). Quote it when contacting support; it links your request to the platform's logs and audit rows.