Types and formats
Open in the interactive reference
The types you meet in requests and responses, at a glance:
| Type | Example | Used in fields such as |
|---|---|---|
| Decimal | "1234.56" |
A bank account's balance |
| Currency code | "EUR" |
A credit memo's currency |
| Date | "2026-01-15" |
A bank entry's transactionDate |
| Date and time, no time zone | "2026-01-15T09:30:00.000" |
A usage record's date |
| Instant, in UTC | "2026-01-15T09:30:00.000Z" |
A customer's lastModifiedDate |
| File | "v1.Jx0qL3sT9mKp2QwR…" |
Fields that carry a document, such as an attachment |
Each is explained below.
Decimals
Decimal values are strings, such as "1234.56", so that no digit is lost in a JSON parser. Read them into a decimal type, never a float, and compare them as numbers rather than as text. Send them as strings too: a JSON number is accepted, but your serializer may already have rounded it.
Money
A monetary amount comes with an ISO 4217 currency code, either beside the amount, in an object with amount and currency, or on the document the amount belongs to. The field's description says which.
Most amounts are positive, with the direction carried by another field, such as separate debit and credit fields. Some are signed, such as a bank transaction's amount, which is negative for money out. A field that can be negative says what the sign means.
Percentages are not written the same way everywhere: some fields take 0.19 for 19%, and others take 19. Check the field's description before you send one.
Dates and times
| Type | In a response | In a request |
|---|---|---|
| Date | 2026-01-15 |
The same. |
| Time of day | 09:30:00.000 |
Also 09:30:00 or 09:30. |
| Date and time, no time zone | 2026-01-15T09:30:00.000 |
Seconds required, milliseconds optional. |
| Instant, in UTC | 2026-01-15T09:30:00.000Z |
Fractional seconds and the Z required. |
A date and time without a time zone is a wall-clock time: when something happens locally, wherever that is. An instant is an exact moment.
Send an instant in UTC, with fractional seconds and a trailing Z, as in 2026-01-15T09:30:00.000Z. A value without fractional seconds, such as 2026-01-15T09:30:00Z, is refused with 400. A value that gives an offset instead of Z, such as 2026-01-15T11:30:00.000+02:00, is also refused.
Responses always include milliseconds, whatever the request sent, so compare dates and times as values, not as strings. The OpenAPI document gives both date-and-time types the format date-time; check a field's description to see whether it is an instant.
Files
A file field is a string on the wire: a handle you exchange for the file at /public/files in a response, and an upload reference you got from /public/files in a request. The OpenAPI document marks it "x-file": true, and this reference shows its type as file. See Files.
Absent, null, and omitted
In a request, omitting a field means “leave it unchanged”, and sending null means “clear it”. null is accepted only on fields marked nullable, and refused with 400 on any other.
In a response, a field with no value is left out rather than sent as null, in a collection's records as well as in a single record. A field you did not select with fields= is left out too. Read a missing field as having no value, not as an error.