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

# The Record object

> The rows inside an object: one contact, one company, one deal.

A record is one row in an [object](/dev/api-reference/objects). Its values live in
`fields`, keyed by property key. See [How the schema works](/dev/api-reference/schema).

Everywhere an endpoint takes an `{object}` path segment you may pass the object's
**id** or its **key** (`obj_3Ab…` or `contacts`). The display name is not accepted.

<ResponseExample>
  ```json The Record object theme={null}
  {
    "id": "rec_3Ab9xK2mQ7",
    "object": "contacts",
    "objectId": "obj_7Cd1yL8nR2",
    "name": "Ada Lovelace",
    "fields": {
      "email": "ada@example.com",
      "title": "Mathematician",
      "company": "rec_9Ef2zM4pS6",
      "annual_revenue": null
    },
    "createdAt": "2026-07-23T18:04:11.000Z",
    "updatedAt": "2026-07-23T18:41:02.000Z"
  }
  ```
</ResponseExample>

## Attributes

<ResponseField name="id" type="string">
  Unique identifier, prefixed `rec_`.
</ResponseField>

<ResponseField name="object" type="string">
  The **key** of the object this record belongs to, e.g. `contacts`.
</ResponseField>

<ResponseField name="objectId" type="string">
  The id of that object.
</ResponseField>

<ResponseField name="name" type="string | null">
  The record's display name, derived from the object's primary property.
</ResponseField>

<ResponseField name="fields" type="object">
  The record's values, keyed by each property's `key`. The keys depend on the
  object's schema; a property with no value is `null` rather than absent, so every
  record in a list has identical keys. The shape of each value depends on the
  property's `type`. See [How the schema works](/dev/api-reference/schema).

  A **`notes`**-type field holds a `doc_…` [document](/dev/api-reference/documents)
  id, not the text. Retrieve the record with **`?expand=notes`** to inline it as
  markdown in one call (needs `documents:read`), or fetch the document by its id.
</ResponseField>

<ResponseField name="createdAt" type="string | null">
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="updatedAt" type="string | null">
  ISO 8601 timestamp of the last change.
</ResponseField>

<Note>
  On **create** and **update**, a field key that matches no property doesn't fail
  the request. The record is written and the key is reported back in
  `ignoredFields`. A typo'd key therefore looks just like a successful write, so
  check `ignoredFields` on your first run.
</Note>

## Querying the list

`GET /v1/records/{object}` (see **List records**) is more than a dump. You can
look records up by any property, search, sort, and page two ways.

<ResponseField name="filter[<key>]" type="query">
  Filter by a property, **this is how you fetch by your own `id` property, an
  email, or any field** instead of the `rec_` id. `filter[email]=jane@acme.com`
  matches exactly; `filter[amount][gte]=100` uses an operator (`eq` `neq` `gt`
  `lt` `gte` `lte` `contains` `notContains` `startsWith` `endsWith` `empty`
  `notEmpty`). Multiple properties AND together. A `<key>` is a property key (or
  `created_at` / `updated_at`).
</ResponseField>

<ResponseField name="q" type="query">
  Full-text search across the object's records, relevance-ranked. When set,
  `filter` / `sort` / `cursor` are ignored.
</ResponseField>

<ResponseField name="sort" type="query">
  `sort=amount:desc`, a property key (or `created_at` / `updated_at`) and an
  optional `:asc` / `:desc` (default `asc`).
</ResponseField>

<ResponseField name="cursor" type="query">
  Stable pagination for large sets. Each response carries `nextCursor` /
  `prevCursor`; pass one back as `cursor=…` for the next page. Mutually exclusive
  with `offset`. Pick one paging mode. (Offset paging still works for small sets.)
</ResponseField>

```bash Look up by a property, newest first theme={null}
curl "https://api.custral.com/v1/records/contacts?filter[external_id]=crm_42&sort=created_at:desc" \
  -H "Authorization: Bearer sk_live_..."
```


## Related topics

- [Records](/dev/webhooks/events/records.md)
- [record.created](/dev/webhooks/events/record-created.md)
- [Data Models](/data/models.md)
- [The Object object](/dev/api-reference/objects.md)