> ## Documentation Index
> Fetch the complete documentation index at: https://api.docs.originone.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses

> Conventions every resource shares: resource types, lists, identifiers, dates, null versus omitted fields, and forward compatibility.

Every resource the Origin One API returns follows the same conventions, so the same parsing rules apply to every resource. This page covers what every response has in common. Each endpoint page documents its own fields.

## Resource type

Every resource carries an `object` field whose value is the resource's type name in singular lowerCamelCase. Nested resources, like `company` and `address` below, carry it too:

```json theme={null}
{
  "object": "location",
  "id": "456",
  "name": "Acme Downtown",
  "phone": "+1-206-555-0142",
  "company": {
    "object": "company",
    "id": "123",
    "name": "Acme Inc"
  },
  "address": {
    "object": "address",
    "line1": "123 Main St",
    "line2": null,
    "city": "Seattle",
    "state": "WA",
    "postalCode": "98101",
    "country": "US"
  },
  "createdAt": "2025-01-15T10:30:00.000Z"
}
```

Check `object` to tell payloads apart, for example when one handler receives several resource types. New resource types appear as the API grows. Skip or pass through any `object` value you don't recognize instead of treating it as an error.

## Lists

Every list endpoint returns its items in the same `{ "data", "total", "page", "limit" }` envelope. A list with no matches still returns `200 OK`, with an empty `data` array and `total: 0`. You never get `404 Not Found` for an empty list. See [Pagination](/pagination) for the parameters and how to page through results.

## Identifiers

An `id` is always a string, even when it looks like a number. Store and compare it as an opaque string. Don't parse it, sort it numerically, or depend on its length or format, because these can change without notice.

## Dates and times

The suffix on a field's name tells you what kind of value it holds:

| Suffix | Holds | Example |
| - | - | - |
| `…At` | A point in time, as an ISO 8601 date-time in UTC. | `"createdAt": "2025-01-15T10:30:00.000Z"` |
| `…Date` | A calendar date, with no time or time zone, as ISO 8601 `YYYY-MM-DD`. | `"birthDate": "1990-04-12"` |

Parse `…At` values with an ISO 8601 date-time parser instead of matching a fixed format. Fractional seconds aren't guaranteed, so accept both `2025-01-15T10:30:00.000Z` and `2025-01-15T10:30:00Z`. Read `…Date` values as plain dates. If you convert one to a timestamp, a time-zone offset can move it to the previous or next day.

## Null versus omitted

A missing field and a `null` field mean different things:

* **`null`**: the field applies to this resource and your token can see it, but it has no value.
* **Omitted**: the field doesn't apply to this resource, or your token lacks the scope to see it.

The API never uses empty strings, zeroes, or empty objects in place of "no value". Here the same order is shown twice, once to a token without the [`order.participant.read`](/scopes#available-scopes) scope and once to a token that has it:

```jsonc theme={null}
// Without order.participant.read: the block is omitted
{ "object": "order", "id": "0b6f…", "status": "ordered" }

// With order.participant.read: the participant has no middle name
{ "object": "order", "id": "0b6f…", "status": "ordered",
  "participant": { "firstName": "Ana", "middleName": null, "lastName": "Reis" } }
```

## Forward compatibility

Responses gain new content within a version, so build your client to accept changes like these:

* New fields can appear on any resource. Ignore fields you don't use.
* Properties can come in any order.
* Enum values in responses (such as an order's `status`) and error codes are open sets. New values can appear, and an error code can stop appearing. Base your logic on the stable signal each one provides: `isFinal` for statuses (see [Order lifecycle](/order-lifecycle)) and `statusCode` plus `source.pointer` for errors (see [Errors](/errors)).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.