# Types and formats

[Open in the interactive reference](https://docs.api.lensing.ai/guides/types)

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](https://docs.api.lensing.ai/guides/files.html).

### 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.