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:

{
  "object": "location",
  "id": "456",
  "name": "Acme Downtown",
  "phone": "[phone]",
  "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 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 scope and once to a token that has it:

// 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) and statusCode plus source.pointer for errors (see Errors).