The Object object

An object is a table: Contacts, Companies, Deals, or anything your workspace defines. Its properties are its columns. Read an object before writing to it: the property types decide what values records will accept.

{
  "id": "obj_3Ab9xK2mQ7",
  "key": "contacts",
  "name": "Contacts",
  "description": "People we talk to",
  "icon": "user",
  "color": "blue",
  "system": false,
  "primaryPropertyId": "prop_5Bc0xJ1kP4",
  "properties": [
    { "id": "prop_5Bc0xJ1kP4", "key": "full_name", "type": "text", "…": "…" },
    {
      "id": "prop_7Cd1yK9lQ2",
      "key": "stage",
      "type": "select",
      "options": [
        { "id": "opt_7Fd2yL8nR1", "value": "Qualified", "description": null, "color": "green", "seq": 0 },
        { "id": "opt_8Ge3zM9oS2", "value": "Won", "description": null, "color": "blue", "seq": 1 }
      ],
      "…": "…"
    }
  ]
}

Attributes

string

Unique identifier, prefixed obj_.

string

The stable, URL-safe identifier, contacts. Usable anywhere an endpoint takes an {object} segment, and what a record’s object field reports.

string

The display name shown in the app.

string | null

Free-text description.

string | null

Icon name used in the app.

string | null

The object’s accent color.

boolean

true for objects Custral ships and maintains. System objects can be extended with your own properties but not deleted.

string

The primary property. The one whose value becomes a record’s name.

array

The object’s columns (see the Property object below). Present only when you retrieve a single object. The list response omits it to stay lean.

Show property attributes

string

Unique identifier, prefixed prop_.

string

The stable identifier, what a record’s fields map is keyed by, and what you send when writing.

string

The display name. Also accepted (case-insensitively) when writing.

string

What kind of value this property holds, text, number, select, relation, … See How the schema works.

integer

Increments when the definition changes materially. Integrations don’t need to track it.

boolean

Whether the app requires a value. The API does not reject a record that omits it.

boolean

Whether the property is indexed for filtering and sorting.

boolean

Whether it’s hidden in the app’s default views. Still readable + writable via the API.

boolean

Whether the property’s definition is protected from edits.

integer

Display order within the object.

object

Type-specific settings: a currency’s code, a select’s isMultiSelect flag, a formula’s expression. The choices themselves are in options, not here.

array

The property’s choices, present only on select, status and multi-select properties that have any. Absent on every other type, and absent when none were loaded.A record stores the option’s id, not its label, so a select field reads back as ["opt_7Fd2yL8nR1"]. Use this list to render that as a label, and to offer the values a write may set. Writes accept either the id or the label, matched case-insensitively.

Show option attributes

string

Unique identifier, prefixed opt_. This is what a record’s field value holds.

string

The label, e.g. Qualified. Unique within the property, not across the workspace.

string | null

Optional explanatory text.

string | null

The chip color the app renders.

integer

Display order within the property. The list is returned in this order.

The retrieve endpoint takes the object’s id or its key, the same as the record endpoints. GET /v1/objects/contacts and GET /v1/objects/obj_3Ab9xK2mQ7 return the same object.

Introduction

Endpoints

Embeds & real-time

Attributes

​Attributes

Attributes