API reference

Customers

Objects and fields, records, list views, search, pipelines, activities, imports and exports.

See Customers. Records are read and changed as the caller: what sharing and their role allow. Keys act as their maker, narrowed by the key's scopes.

`GET /v1/orgs/:orgId/crm/objects`

Every object with its fields, validation rules and indexes.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Response 200

{
  objects: {
    id: string
    label: string
    plural: string
    prefix: string
    glyph: string
    custom?: boolean
    nameFields: string[]
    fields: {
      id: string
      label: string
      type: "number" | "text" | "email" | "url" | "date" | "owner" | "pipeline" | "phone" | "textarea" | "checkbox" | "currency" | "stage" | "lookup" | "datetime" | "percent" | "picklist" | "multipicklist" | "lookups"
      required?: boolean
      custom?: boolean
      system?: boolean
      readOnly?: boolean
      searchable?: boolean
      help?: string
      maxLength?: number
      min?: number
      max?: number
      decimals?: number
      values?: {
        value: string
        label?: string
        inactive?: boolean
      }[]
      target?: string
      convertTo?: {
        object: "contact" | "account" | "opportunity"
        field: string
      }
    }[]
    rules: {
      id: string
      name: string
      active: boolean
      when: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      require: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      message: string
      field?: string
    }[]
    sharing: "private" | "read" | "readwrite"
    indexes: {
      id: string
      eq: string[]
      sort: string
      status: "building" | "ready"
      builtin?: boolean
      createdAt: number
    }[]
    indexShards: number
    listColumns: string[]
    subtitleFields: string[]
    version: number
    createdAt: number
    updatedAt: number
  }[]
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`POST /v1/orgs/:orgId/crm/objects`

A custom object (Customers admins): a name field, the system fields and the built-in indexes.

Auth: user access token or platform agent key · Scopes: crm:read, crm:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Request body

Field	Type	Required	Default	Notes
`label`	`string`	Yes		1–60 characters; trimmed
`plural`	`string`	No	`""`	up to 60 characters; trimmed
`nameLabel`	`string`	No		up to 60 characters; trimmed
`sharing`	`"private" \| "read" \| "readwrite"`	No

Response 201

{
  object: {
    id: string
    label: string
    plural: string
    prefix: string
    glyph: string
    custom?: boolean
    nameFields: string[]
    fields: {
      id: string
      label: string
      type: "number" | "text" | "email" | "url" | "date" | "owner" | "pipeline" | "phone" | "textarea" | "checkbox" | "currency" | "stage" | "lookup" | "datetime" | "percent" | "picklist" | "multipicklist" | "lookups"
      required?: boolean
      custom?: boolean
      system?: boolean
      readOnly?: boolean
      searchable?: boolean
      help?: string
      maxLength?: number
      min?: number
      max?: number
      decimals?: number
      values?: {
        value: string
        label?: string
        inactive?: boolean
      }[]
      target?: string
      convertTo?: {
        object: "contact" | "account" | "opportunity"
        field: string
      }
    }[]
    rules: {
      id: string
      name: string
      active: boolean
      when: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      require: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      message: string
      field?: string
    }[]
    sharing: "private" | "read" | "readwrite"
    indexes: {
      id: string
      eq: string[]
      sort: string
      status: "building" | "ready"
      builtin?: boolean
      createdAt: number
    }[]
    indexShards: number
    listColumns: string[]
    subtitleFields: string[]
    version: number
    createdAt: number
    updatedAt: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`GET /v1/orgs/:orgId/crm/objects/:object`

One object with its fields, validation rules and indexes.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).

Response 200

{
  object: {
    id: string
    label: string
    plural: string
    prefix: string
    glyph: string
    custom?: boolean
    nameFields: string[]
    fields: {
      id: string
      label: string
      type: "number" | "text" | "email" | "url" | "date" | "owner" | "pipeline" | "phone" | "textarea" | "checkbox" | "currency" | "stage" | "lookup" | "datetime" | "percent" | "picklist" | "multipicklist" | "lookups"
      required?: boolean
      custom?: boolean
      system?: boolean
      readOnly?: boolean
      searchable?: boolean
      help?: string
      maxLength?: number
      min?: number
      max?: number
      decimals?: number
      values?: {
        value: string
        label?: string
        inactive?: boolean
      }[]
      target?: string
      convertTo?: {
        object: "contact" | "account" | "opportunity"
        field: string
      }
    }[]
    rules: {
      id: string
      name: string
      active: boolean
      when: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      require: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      message: string
      field?: string
    }[]
    sharing: "private" | "read" | "readwrite"
    indexes: {
      id: string
      eq: string[]
      sort: string
      status: "building" | "ready"
      builtin?: boolean
      createdAt: number
    }[]
    indexShards: number
    listColumns: string[]
    subtitleFields: string[]
    version: number
    createdAt: number
    updatedAt: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`PATCH /v1/orgs/:orgId/crm/objects/:object`

Labels, sharing default, default columns and search subtitle (Customers admins), over version.

Auth: user access token or platform agent key · Scopes: crm:read, crm:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).

Request body

Field	Type	Required	Notes
`version`	`integer`	Yes
`label`	`string`	No	up to 60 characters; trimmed
`plural`	`string`	No	up to 60 characters; trimmed
`sharing`	`"private" \| "read" \| "readwrite"`	No
`listColumns`	`string[]`	No	up to 30 items; each 1–60 characters
`subtitleFields`	`string[]`	No	up to 5 items; each 1–60 characters

Response 200

{
  object: {
    id: string
    label: string
    plural: string
    prefix: string
    glyph: string
    custom?: boolean
    nameFields: string[]
    fields: {
      id: string
      label: string
      type: "number" | "text" | "email" | "url" | "date" | "owner" | "pipeline" | "phone" | "textarea" | "checkbox" | "currency" | "stage" | "lookup" | "datetime" | "percent" | "picklist" | "multipicklist" | "lookups"
      required?: boolean
      custom?: boolean
      system?: boolean
      readOnly?: boolean
      searchable?: boolean
      help?: string
      maxLength?: number
      min?: number
      max?: number
      decimals?: number
      values?: {
        value: string
        label?: string
        inactive?: boolean
      }[]
      target?: string
      convertTo?: {
        object: "contact" | "account" | "opportunity"
        field: string
      }
    }[]
    rules: {
      id: string
      name: string
      active: boolean
      when: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      require: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      message: string
      field?: string
    }[]
    sharing: "private" | "read" | "readwrite"
    indexes: {
      id: string
      eq: string[]
      sort: string
      status: "building" | "ready"
      builtin?: boolean
      createdAt: number
    }[]
    indexShards: number
    listColumns: string[]
    subtitleFields: string[]
    version: number
    createdAt: number
    updatedAt: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`DELETE /v1/orgs/:orgId/crm/objects/:object`

Deletes a custom object without records.

Auth: user access token or platform agent key · Scopes: crm:read, crm:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).

Response 200

{
  ok: true
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`POST /v1/orgs/:orgId/crm/objects/:object/fields`

Adds a custom field (Customers admins): text, number, currency, date, picklist, multi-picklist, checkbox, lookup, email, phone or URL; required makes it required.

Auth: user access token or platform agent key · Scopes: crm:read, crm:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).

Request body

Field	Type	Required	Default	Notes
`label`	`string`	Yes		1–80 characters; trimmed
`type`	`"text" \| "textarea" \| "number" \| "currency" \| "percent" \| "date" \| "datetime" \| "picklist" \| "multipicklist" \| "checkbox" \| "lookup" \| "email" \| "phone" \| "url"`	Yes
`required`	`boolean`	No
`help`	`string`	No		up to 255 characters
`searchable`	`boolean`	No
`maxLength`	`integer`	No		1–32000
`min`	`number`	No
`max`	`number`	No
`decimals`	`integer`	No		0–6
`values`	`object[]`	No		up to 2,000 items
`values[].value`	`string`	No	`""`	up to 80 characters
`values[].label`	`string`	No		up to 80 characters
`values[].inactive`	`boolean`	No
`target`	`string`	No		up to 40 characters
`convertTo`	`object`	No
`convertTo.object`	`"account" \| "contact" \| "opportunity"`	Yes
`convertTo.field`	`string`	Yes		1–60 characters

Response 201

{
  object: {
    id: string
    label: string
    plural: string
    prefix: string
    glyph: string
    custom?: boolean
    nameFields: string[]
    fields: {
      id: string
      label: string
      type: "number" | "text" | "email" | "url" | "date" | "owner" | "pipeline" | "phone" | "textarea" | "checkbox" | "currency" | "stage" | "lookup" | "datetime" | "percent" | "picklist" | "multipicklist" | "lookups"
      required?: boolean
      custom?: boolean
      system?: boolean
      readOnly?: boolean
      searchable?: boolean
      help?: string
      maxLength?: number
      min?: number
      max?: number
      decimals?: number
      values?: {
        value: string
        label?: string
        inactive?: boolean
      }[]
      target?: string
      convertTo?: {
        object: "contact" | "account" | "opportunity"
        field: string
      }
    }[]
    rules: {
      id: string
      name: string
      active: boolean
      when: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      require: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      message: string
      field?: string
    }[]
    sharing: "private" | "read" | "readwrite"
    indexes: {
      id: string
      eq: string[]
      sort: string
      status: "building" | "ready"
      builtin?: boolean
      createdAt: number
    }[]
    indexShards: number
    listColumns: string[]
    subtitleFields: string[]
    version: number
    createdAt: number
    updatedAt: number
  }
  field: {
    id: string
    label: string
    type: "number" | "text" | "email" | "url" | "date" | "owner" | "pipeline" | "phone" | "textarea" | "checkbox" | "currency" | "stage" | "lookup" | "datetime" | "percent" | "picklist" | "multipicklist" | "lookups"
    required?: boolean
    custom?: boolean
    system?: boolean
    readOnly?: boolean
    searchable?: boolean
    help?: string
    maxLength?: number
    min?: number
    max?: number
    decimals?: number
    values?: {
      value: string
      label?: string
      inactive?: boolean
    }[]
    target?: string
    convertTo?: {
      object: "contact" | "account" | "opportunity"
      field: string
    }
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`PATCH /v1/orgs/:orgId/crm/objects/:object/fields/:field`

Changes a field's label, help, required, picklist values or lookup, over the object's version.

Auth: user access token or platform agent key · Scopes: crm:read, crm:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).
`:field`	A field's id in Customers, as `GET …/crm/objects/:object` lists them (custom fields `x_…`).

Request body

Field	Type	Required	Default	Notes
`label`	`string`	No		1–80 characters; trimmed
`required`	`boolean`	No
`help`	`string`	No		up to 255 characters
`searchable`	`boolean`	No
`maxLength`	`integer`	No		1–32000
`min`	`number`	No
`max`	`number`	No
`decimals`	`integer`	No		0–6
`values`	`object[]`	No		up to 2,000 items
`values[].value`	`string`	No	`""`	up to 80 characters
`values[].label`	`string`	No		up to 80 characters
`values[].inactive`	`boolean`	No
`version`	`integer`	Yes
`convertTo`	`any JSON`	Yes		can be `null`

Response 200

{
  object: {
    id: string
    label: string
    plural: string
    prefix: string
    glyph: string
    custom?: boolean
    nameFields: string[]
    fields: {
      id: string
      label: string
      type: "number" | "text" | "email" | "url" | "date" | "owner" | "pipeline" | "phone" | "textarea" | "checkbox" | "currency" | "stage" | "lookup" | "datetime" | "percent" | "picklist" | "multipicklist" | "lookups"
      required?: boolean
      custom?: boolean
      system?: boolean
      readOnly?: boolean
      searchable?: boolean
      help?: string
      maxLength?: number
      min?: number
      max?: number
      decimals?: number
      values?: {
        value: string
        label?: string
        inactive?: boolean
      }[]
      target?: string
      convertTo?: {
        object: "contact" | "account" | "opportunity"
        field: string
      }
    }[]
    rules: {
      id: string
      name: string
      active: boolean
      when: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      require: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      message: string
      field?: string
    }[]
    sharing: "private" | "read" | "readwrite"
    indexes: {
      id: string
      eq: string[]
      sort: string
      status: "building" | "ready"
      builtin?: boolean
      createdAt: number
    }[]
    indexShards: number
    listColumns: string[]
    subtitleFields: string[]
    version: number
    createdAt: number
    updatedAt: number
  }
  field: {
    id: string
    label: string
    type: "number" | "text" | "email" | "url" | "date" | "owner" | "pipeline" | "phone" | "textarea" | "checkbox" | "currency" | "stage" | "lookup" | "datetime" | "percent" | "picklist" | "multipicklist" | "lookups"
    required?: boolean
    custom?: boolean
    system?: boolean
    readOnly?: boolean
    searchable?: boolean
    help?: string
    maxLength?: number
    min?: number
    max?: number
    decimals?: number
    values?: {
      value: string
      label?: string
      inactive?: boolean
    }[]
    target?: string
    convertTo?: {
      object: "contact" | "account" | "opportunity"
      field: string
    }
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`DELETE /v1/orgs/:orgId/crm/objects/:object/fields/:field`

Deletes a custom field, with its rules and indexes (their entries go in the background).

Auth: user access token or platform agent key · Scopes: crm:read, crm:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).
`:field`	A field's id in Customers, as `GET …/crm/objects/:object` lists them (custom fields `x_…`).

Query parameter	Type	Required	Notes
`version`	`integer`	Yes	coerced from a string

Response 200

{
  object: {
    id: string
    label: string
    plural: string
    prefix: string
    glyph: string
    custom?: boolean
    nameFields: string[]
    fields: {
      id: string
      label: string
      type: "number" | "text" | "email" | "url" | "date" | "owner" | "pipeline" | "phone" | "textarea" | "checkbox" | "currency" | "stage" | "lookup" | "datetime" | "percent" | "picklist" | "multipicklist" | "lookups"
      required?: boolean
      custom?: boolean
      system?: boolean
      readOnly?: boolean
      searchable?: boolean
      help?: string
      maxLength?: number
      min?: number
      max?: number
      decimals?: number
      values?: {
        value: string
        label?: string
        inactive?: boolean
      }[]
      target?: string
      convertTo?: {
        object: "contact" | "account" | "opportunity"
        field: string
      }
    }[]
    rules: {
      id: string
      name: string
      active: boolean
      when: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      require: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      message: string
      field?: string
    }[]
    sharing: "private" | "read" | "readwrite"
    indexes: {
      id: string
      eq: string[]
      sort: string
      status: "building" | "ready"
      builtin?: boolean
      createdAt: number
    }[]
    indexShards: number
    listColumns: string[]
    subtitleFields: string[]
    version: number
    createdAt: number
    updatedAt: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`PUT /v1/orgs/:orgId/crm/objects/:object/rules`

Replaces the object's validation rules.

Auth: user access token or platform agent key · Scopes: crm:read, crm:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).

Request body

Field	Type	Required	Notes
`version`	`integer`	Yes
`rules`	`object[]`	Yes	up to 500 items
`rules[].id`	`string`	Yes	up to 40 characters
`rules[].name`	`string`	Yes	1–80 characters; trimmed
`rules[].active`	`boolean`	Yes
`rules[].when`	`object[]`	Yes	up to 10 items
`rules[].when[].field`	`string`	Yes	1–60 characters
`rules[].when[].op`	`"eq" \| "ne" \| "gt" \| "gte" \| "lt" \| "lte" \| "contains" \| "blank" \| "notBlank"`	Yes
`rules[].when[].value`	`any JSON`	No
`rules[].require`	`object[]`	Yes	1–10 items
`rules[].require[].field`	`string`	Yes	1–60 characters
`rules[].require[].op`	`"eq" \| "ne" \| "gt" \| "gte" \| "lt" \| "lte" \| "contains" \| "blank" \| "notBlank"`	Yes
`rules[].require[].value`	`any JSON`	No
`rules[].message`	`string`	Yes	1–255 characters; trimmed
`rules[].field`	`string`	No	1–60 characters

Response 200

{
  object: {
    id: string
    label: string
    plural: string
    prefix: string
    glyph: string
    custom?: boolean
    nameFields: string[]
    fields: {
      id: string
      label: string
      type: "number" | "text" | "email" | "url" | "date" | "owner" | "pipeline" | "phone" | "textarea" | "checkbox" | "currency" | "stage" | "lookup" | "datetime" | "percent" | "picklist" | "multipicklist" | "lookups"
      required?: boolean
      custom?: boolean
      system?: boolean
      readOnly?: boolean
      searchable?: boolean
      help?: string
      maxLength?: number
      min?: number
      max?: number
      decimals?: number
      values?: {
        value: string
        label?: string
        inactive?: boolean
      }[]
      target?: string
      convertTo?: {
        object: "contact" | "account" | "opportunity"
        field: string
      }
    }[]
    rules: {
      id: string
      name: string
      active: boolean
      when: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      require: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      message: string
      field?: string
    }[]
    sharing: "private" | "read" | "readwrite"
    indexes: {
      id: string
      eq: string[]
      sort: string
      status: "building" | "ready"
      builtin?: boolean
      createdAt: number
    }[]
    indexShards: number
    listColumns: string[]
    subtitleFields: string[]
    version: number
    createdAt: number
    updatedAt: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`POST /v1/orgs/:orgId/crm/objects/:object/indexes`

Adds an index (built in the background): up to two equality fields and a sort field.

Auth: user access token or platform agent key · Scopes: crm:read, crm:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).

Request body

Field	Type	Required	Notes
`eq`	`string[]`	Yes	up to 2 items; each 1–60 characters
`sort`	`string`	Yes	1–60 characters

Response 201

{
  index: {
    id: string
    eq: string[]
    sort: string
    status: "building" | "ready"
    builtin?: boolean
    createdAt: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`DELETE /v1/orgs/:orgId/crm/objects/:object/indexes/:indexId`

Drops a custom index (its entries go in the background); built-in ones stay.

Auth: user access token or platform agent key · Scopes: crm:read, crm:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).
`:indexId`	A list view index's id in Customers (`ix…`), as the object's `indexes` list them.

Response 200

{
  object: {
    id: string
    label: string
    plural: string
    prefix: string
    glyph: string
    custom?: boolean
    nameFields: string[]
    fields: {
      id: string
      label: string
      type: "number" | "text" | "email" | "url" | "date" | "owner" | "pipeline" | "phone" | "textarea" | "checkbox" | "currency" | "stage" | "lookup" | "datetime" | "percent" | "picklist" | "multipicklist" | "lookups"
      required?: boolean
      custom?: boolean
      system?: boolean
      readOnly?: boolean
      searchable?: boolean
      help?: string
      maxLength?: number
      min?: number
      max?: number
      decimals?: number
      values?: {
        value: string
        label?: string
        inactive?: boolean
      }[]
      target?: string
      convertTo?: {
        object: "contact" | "account" | "opportunity"
        field: string
      }
    }[]
    rules: {
      id: string
      name: string
      active: boolean
      when: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      require: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      message: string
      field?: string
    }[]
    sharing: "private" | "read" | "readwrite"
    indexes: {
      id: string
      eq: string[]
      sort: string
      status: "building" | "ready"
      builtin?: boolean
      createdAt: number
    }[]
    indexShards: number
    listColumns: string[]
    subtitleFields: string[]
    version: number
    createdAt: number
    updatedAt: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`GET /v1/orgs/:orgId/crm/objects/:object/views`

Built-in, shared and the caller's own list views.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).

Response 200

{
  views: {
    id: string
    object: string
    name: string
    ownerId?: string
    filters: {
      field: string
      op: "in" | "startsWith" | "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
      value?: unknown
    }[]
    sort: {
      field: string
      dir: "asc" | "desc"
    }
    columns: string[]
    builtin?: boolean
    createdAt: number
    updatedAt: number
  }[]
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`POST /v1/orgs/:orgId/crm/objects/:object/views`

Saves a view (shared ones: Customers admins); an index it needs is added and built.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).

Request body

Field	Type	Required	Default	Notes
`name`	`string`	Yes		1–80 characters; trimmed
`filters`	`object[]`	No	`[]`	up to 20 items
`filters[].field`	`string`	Yes		1–60 characters
`filters[].op`	`"eq" \| "ne" \| "in" \| "gt" \| "gte" \| "lt" \| "lte" \| "contains" \| "startsWith" \| "blank" \| "notBlank"`	Yes
`filters[].value`	`any JSON`	No
`sort`	`object`	Yes
`sort.field`	`string`	Yes		1–60 characters
`sort.dir`	`"asc" \| "desc"`	Yes
`columns`	`string[]`	No	`[]`	up to 30 items; each 1–60 characters
`shared`	`boolean`	No

Response 201

{
  view: {
    id: string
    object: string
    name: string
    ownerId?: string
    filters: {
      field: string
      op: "in" | "startsWith" | "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
      value?: unknown
    }[]
    sort: {
      field: string
      dir: "asc" | "desc"
    }
    columns: string[]
    builtin?: boolean
    createdAt: number
    updatedAt: number
  }
  index?: {
    id: string
    eq: string[]
    sort: string
    status: "building" | "ready"
    builtin?: boolean
    createdAt: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`PATCH /v1/orgs/:orgId/crm/objects/:object/views/:viewId`

Changes a saved view (the caller's own; shared ones: Customers admins).

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).
`:viewId`	A list view: `all`, `mine`, `recent` or a saved view's id (`cvw_…`).

Request body

Field	Type	Required	Default	Notes
`name`	`string`	Yes		1–80 characters; trimmed
`filters`	`object[]`	No	`[]`	up to 20 items
`filters[].field`	`string`	Yes		1–60 characters
`filters[].op`	`"eq" \| "ne" \| "in" \| "gt" \| "gte" \| "lt" \| "lte" \| "contains" \| "startsWith" \| "blank" \| "notBlank"`	Yes
`filters[].value`	`any JSON`	No
`sort`	`object`	Yes
`sort.field`	`string`	Yes		1–60 characters
`sort.dir`	`"asc" \| "desc"`	Yes
`columns`	`string[]`	No	`[]`	up to 30 items; each 1–60 characters
`shared`	`boolean`	No

Response 200

{
  view: {
    id: string
    object: string
    name: string
    ownerId?: string
    filters: {
      field: string
      op: "in" | "startsWith" | "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
      value?: unknown
    }[]
    sort: {
      field: string
      dir: "asc" | "desc"
    }
    columns: string[]
    builtin?: boolean
    createdAt: number
    updatedAt: number
  }
  index?: {
    id: string
    eq: string[]
    sort: string
    status: "building" | "ready"
    builtin?: boolean
    createdAt: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`DELETE /v1/orgs/:orgId/crm/objects/:object/views/:viewId`

Deletes a saved view (the caller's own; shared ones: Customers admins).

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).
`:viewId`	A list view: `all`, `mine`, `recent` or a saved view's id (`cvw_…`).

Response 200

{
  ok: true
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`GET /v1/orgs/:orgId/crm/objects/:object/records`

A page of records by a view, or filters (JSON) and sort; cursor continues.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).

Query parameter	Type	Required	Default	Notes
`view`	`string`	No		up to 40 characters
`filters`	`string`	No		up to 8,000 characters
`sort`	`string`	No		up to 80 characters
`cursor`	`string`	No		up to 8,000 characters
`limit`	`integer`	No	`50`	1–200; coerced from a string

Response 200

{
  names: {
    records: {
      [key: string]: {
        id: string
        name: string
        object: string
      }
    }
    people: {
      [key: string]: string
    }
  }
  records: {
    id: string
    object: string
    version: number
    ownerId: string
    name: string
    fields: {
      [key: string]: unknown
    }
    createdAt: number
    updatedAt: number
    createdBy: string
    updatedBy: string
    via: "api" | "mcp" | "calendar" | "app" | "system" | "import" | "mail" | "marketing" | "convert"
  }[]
  cursor?: string
  total?: number
  missingIndex?: {
    eq: string[]
    sort: string
  }
  partial?: boolean
  plan: {
    index: string
    exactSort: boolean
    memorySort: boolean
  }
}

Errors

Status	Message
`400`	filters: a JSON list of { field, op, value }.
`400`	sort: field:asc or field:desc.
`429`	Too many requests to Customers this minute. Try again shortly.

`POST /v1/orgs/:orgId/crm/objects/:object/records/query`

The same list with the filters in the body.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).

Request body

Field	Type	Required	Default	Notes
`view`	`string`	No		up to 40 characters
`filters`	`object[]`	No		up to 20 items
`filters[].field`	`string`	Yes		1–60 characters
`filters[].op`	`"eq" \| "ne" \| "in" \| "gt" \| "gte" \| "lt" \| "lte" \| "contains" \| "startsWith" \| "blank" \| "notBlank"`	Yes
`filters[].value`	`any JSON`	No
`sort`	`object`	No
`sort.field`	`string`	Yes		1–60 characters
`sort.dir`	`"asc" \| "desc"`	Yes
`cursor`	`string`	No		up to 8,000 characters
`limit`	`integer`	No	`50`	1–200

Response 200

{
  names: {
    records: {
      [key: string]: {
        id: string
        name: string
        object: string
      }
    }
    people: {
      [key: string]: string
    }
  }
  records: {
    id: string
    object: string
    version: number
    ownerId: string
    name: string
    fields: {
      [key: string]: unknown
    }
    createdAt: number
    updatedAt: number
    createdBy: string
    updatedBy: string
    via: "api" | "mcp" | "calendar" | "app" | "system" | "import" | "mail" | "marketing" | "convert"
  }[]
  cursor?: string
  total?: number
  missingIndex?: {
    eq: string[]
    sort: string
  }
  partial?: boolean
  plan: {
    index: string
    exactSort: boolean
    memorySort: boolean
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`POST /v1/orgs/:orgId/crm/objects/:object/records`

Creates a record owned by the caller (or ownerId); field errors come back as 422 with errors.

Auth: user access token or platform agent key · Scopes: crm:read, crm:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).

Request body

Field	Type	Required	Notes
`fields`	`object`	Yes	keys up to 60 characters; values: any JSON
`ownerId`	`string`	No	up to 40 characters

Response 201

{
  record: {
    id: string
    object: string
    version: number
    ownerId: string
    name: string
    fields: {
      [key: string]: unknown
    }
    createdAt: number
    updatedAt: number
    createdBy: string
    updatedBy: string
    via: "api" | "mcp" | "calendar" | "app" | "system" | "import" | "mail" | "marketing" | "convert"
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`POST /v1/orgs/:orgId/crm/objects/:object/records/bulk`

Updates, transfers or deletes many records; each reports its own result.

Auth: user access token or platform agent key · Scopes: crm:read, crm:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).

Request body

Field	Type	Required	Notes
`ids`	`string[]`	Yes	1–1,000 items; each matches `^[a-z][a-z0-9]{1,5}_[0-9a-z]{26}$`
`operation`	`"update" \| "transfer" \| "delete"`	Yes
`fields`	`object`	No	keys up to 60 characters; values: any JSON
`ownerId`	`string`	No	up to 40 characters

Response 200

{
  results: {
    id: string
    ok: true
    error?: undefined
  } | {
    id: string
    ok: false
    error: string
  }[]
}

Errors

Status	Message
`400`	ownerId: who gets the records.
`429`	Too many requests to Customers this minute. Try again shortly.

`GET /v1/orgs/:orgId/crm/objects/:object/export`

A view (or filters) as CSV, up to 10,000 rows; X-More: 1 when there are more (use an export job).

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).

Query parameter	Type	Required	Notes
`view`	`string`	No	up to 40 characters
`filters`	`string`	No	up to 8,000 characters
`sort`	`string`	No	up to 80 characters
`columns`	`string`	No	up to 2,000 characters

Response 200 with no body.

Errors

Status	Message
`400`	filters: a JSON list of { field, op, value }.
`400`	sort: field:asc or field:desc.
`429`	Too many requests to Customers this minute. Try again shortly.

`POST /v1/orgs/:orgId/crm/objects/:object/exports`

Exports a view to a file in the background (any size); download it from the job when done.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:object`	An object's id in Customers: `account`, `contact`, `lead`, `opportunity`, `activity`, or a custom object's (`x_…`).

Request body

Field	Type	Required	Notes
`view`	`string`	No	up to 40 characters
`filters`	`object[]`	No	up to 20 items
`filters[].field`	`string`	Yes	1–60 characters
`filters[].op`	`"eq" \| "ne" \| "in" \| "gt" \| "gte" \| "lt" \| "lte" \| "contains" \| "startsWith" \| "blank" \| "notBlank"`	Yes
`filters[].value`	`any JSON`	No
`sort`	`object`	No
`sort.field`	`string`	Yes	1–60 characters
`sort.dir`	`"asc" \| "desc"`	Yes
`columns`	`string[]`	No	up to 60 items; each 1–60 characters

Response 202

{
  job: {
    id: string
    kind: "import" | "export"
    object: string
    state: "queued" | "ready" | "done" | "failed" | "uploading" | "running"
    fileName: string
    fileKey: string
    size: number
    headers?: string[]
    mapping?: string[]
    options?: {
      mode: "create" | "upsert"
      ownerId?: string
      dateOrder: "iso" | "dmy" | "mdy"
    }
    view?: {
      viewId?: string
      filters?: unknown[]
      sort?: unknown
      columns?: string[]
    }
    progress: {
      rows: number
      created: number
      updated: number
      failed: number
      offset: number
    }
    errors: {
      row: number
      message: string
    }[]
    error?: string
    createdBy: string
    createdByLabel: string
    createdAt: number
    updatedAt: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`GET /v1/orgs/:orgId/crm/records/:id`

The record, what the caller may do with it, and names of the people and records it refers to.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:id`	A record's id in Customers: its object's prefix and a time-sortable id (`acc_…`, `cnt_…`, `led_…`, `opp_…`, `act_…`).

Response 200

{
  record: {
    id: string
    object: string
    version: number
    ownerId: string
    name: string
    fields: {
      [key: string]: unknown
    }
    createdAt: number
    updatedAt: number
    createdBy: string
    updatedBy: string
    via: "api" | "mcp" | "calendar" | "app" | "system" | "import" | "mail" | "marketing" | "convert"
  }
  object: string
  access: {
    read: boolean
    edit: boolean
    delete: boolean
    transfer: boolean
  }
  names: {
    records: {
      [key: string]: {
        id: string
        name: string
        object: string
      }
    }
    people: {
      [key: string]: string
    }
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`PATCH /v1/orgs/:orgId/crm/records/:id`

Changes fields and the owner; version refuses a stale edit (409).

Auth: user access token or platform agent key · Scopes: crm:read, crm:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:id`	A record's id in Customers: its object's prefix and a time-sortable id (`acc_…`, `cnt_…`, `led_…`, `opp_…`, `act_…`).

Request body

Field	Type	Required	Notes
`fields`	`object`	No	keys up to 60 characters; values: any JSON
`ownerId`	`string`	No	up to 40 characters
`version`	`integer`	No

Response 200

{
  record: {
    id: string
    object: string
    version: number
    ownerId: string
    name: string
    fields: {
      [key: string]: unknown
    }
    createdAt: number
    updatedAt: number
    createdBy: string
    updatedBy: string
    via: "api" | "mcp" | "calendar" | "app" | "system" | "import" | "mail" | "marketing" | "convert"
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`DELETE /v1/orgs/:orgId/crm/records/:id`

Deletes the record; its history and the audit log keep who deleted it.

Auth: user access token or platform agent key · Scopes: crm:read, crm:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:id`	A record's id in Customers: its object's prefix and a time-sortable id (`acc_…`, `cnt_…`, `led_…`, `opp_…`, `act_…`).

Response 200

{
  ok: true
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`GET /v1/orgs/:orgId/crm/records/:id/history`

Field changes, newest first.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:id`	A record's id in Customers: its object's prefix and a time-sortable id (`acc_…`, `cnt_…`, `led_…`, `opp_…`, `act_…`).

Query parameter	Type	Required	Default	Notes
`cursor`	`string`	No		up to 2,000 characters
`limit`	`integer`	No	`50`	1–200; coerced from a string

Response 200

{
  entries: {
    at: number
    version: number
    actor: string
    via: "api" | "mcp" | "calendar" | "app" | "system" | "import" | "mail" | "marketing" | "convert"
    kind: "deleted" | "created" | "updated" | "converted"
    changes: {
      field: string
      from?: unknown
      to?: unknown
    }[]
  }[]
  cursor?: string
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

Records of other objects that look up to this one (a few of each).

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:id`	A record's id in Customers: its object's prefix and a time-sortable id (`acc_…`, `cnt_…`, `led_…`, `opp_…`, `act_…`).

Response 200

{
  lists: {
    object: string
    field: string
    label: string
    records: {
      id: string
      object: string
      version: number
      ownerId: string
      name: string
      fields: {
        [key: string]: unknown
      }
      createdAt: number
      updatedAt: number
      createdBy: string
      updatedBy: string
      via: "api" | "mcp" | "calendar" | "app" | "system" | "import" | "mail" | "marketing" | "convert"
    }[]
    more: boolean
  }[]
  names: {
    [key: string]: {
      records: {
        [key: string]: {
          id: string
          name: string
          object: string
        }
      }
      people: {
        [key: string]: string
      }
    }
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`GET /v1/orgs/:orgId/crm/records/:id/activities`

The timeline: activities related to the record, newest first.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:id`	A record's id in Customers: its object's prefix and a time-sortable id (`acc_…`, `cnt_…`, `led_…`, `opp_…`, `act_…`).

Query parameter	Type	Required	Default	Notes
`cursor`	`string`	No		up to 8,000 characters
`limit`	`integer`	No	`25`	1–100; coerced from a string
`type`	`"task" \| "call" \| "meeting" \| "note" \| "email"`	No

Response 200

{
  names: {
    records: {
      [key: string]: {
        id: string
        name: string
        object: string
      }
    }
    people: {
      [key: string]: string
    }
  }
  records: {
    id: string
    object: string
    version: number
    ownerId: string
    name: string
    fields: {
      [key: string]: unknown
    }
    createdAt: number
    updatedAt: number
    createdBy: string
    updatedBy: string
    via: "api" | "mcp" | "calendar" | "app" | "system" | "import" | "mail" | "marketing" | "convert"
  }[]
  cursor?: string
  total?: number
  missingIndex?: {
    eq: string[]
    sort: string
  }
  partial?: boolean
  plan: {
    index: string
    exactSort: boolean
    memorySort: boolean
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`POST /v1/orgs/:orgId/crm/records/:id/activities`

Logs a task, call, meeting, note or email on the record (and any others in relatedIds).

Auth: user access token or platform agent key · Scopes: crm:read, crm:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:id`	A record's id in Customers: its object's prefix and a time-sortable id (`acc_…`, `cnt_…`, `led_…`, `opp_…`, `act_…`).

Request body

Field	Type	Required	Default	Notes
`type`	`"task" \| "call" \| "meeting" \| "note" \| "email"`	Yes
`subject`	`string`	Yes		1–255 characters; trimmed
`body`	`string`	No		up to 32,000 characters
`status`	`"open" \| "completed"`	No
`dueDate`	`string`	No		matches `^\d{4}-\d{2}-\d{2}$`
`startAt`	`number \| string`	No		up to 40 characters
`endAt`	`number \| string`	No		up to 40 characters
`durationMinutes`	`integer`	No		0–100000
`direction`	`"inbound" \| "outbound"`	No
`relatedIds`	`string[]`	No	`[]`	up to 24 items; each matches `^[a-z][a-z0-9]{1,5}_[0-9a-z]{26}$`
`ownerId`	`string`	No		up to 40 characters

Response 201

{
  record: {
    id: string
    object: string
    version: number
    ownerId: string
    name: string
    fields: {
      [key: string]: unknown
    }
    createdAt: number
    updatedAt: number
    createdBy: string
    updatedBy: string
    via: "api" | "mcp" | "calendar" | "app" | "system" | "import" | "mail" | "marketing" | "convert"
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`POST /v1/orgs/:orgId/crm/records/:id/convert`

Converts a lead into an account (or uses one), a contact (or uses one) and an opportunity.

Auth: user access token or platform agent key · Scopes: crm:read, crm:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:id`	A record's id in Customers: its object's prefix and a time-sortable id (`acc_…`, `cnt_…`, `led_…`, `opp_…`, `act_…`).

Request body

Field	Type	Required	Default	Notes
`accountId`	`string`	No		matches `^[a-z][a-z0-9]{1,5}_[0-9a-z]{26}$`
`contactId`	`string`	No		matches `^[a-z][a-z0-9]{1,5}_[0-9a-z]{26}$`
`createOpportunity`	`boolean`	No	`true`
`opportunity`	`object`	No
`opportunity.name`	`string`	No		up to 255 characters
`opportunity.pipelineId`	`string`	No		up to 40 characters
`opportunity.stage`	`string`	No		up to 40 characters
`opportunity.amount`	`number`	No		≥ 0
`opportunity.closeDate`	`string`	No		matches `^\d{4}-\d{2}-\d{2}$`
`ownerId`	`string`	No		up to 40 characters

Response 200

{
  lead: {
    id: string
    object: string
    version: number
    ownerId: string
    name: string
    fields: {
      [key: string]: unknown
    }
    createdAt: number
    updatedAt: number
    createdBy: string
    updatedBy: string
    via: "api" | "mcp" | "calendar" | "app" | "system" | "import" | "mail" | "marketing" | "convert"
  }
  accountId: string
  contactId: string
  opportunityId?: string
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`GET /v1/orgs/:orgId/crm/pipelines`

Opportunity pipelines with their stages.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Response 200

{
  pipelines: {
    id: string
    name: string
    stages: {
      id: string
      name: string
      probability: number
      category: "lost" | "open" | "won"
    }[]
    isDefault?: boolean
    order: number
    version: number
  }[]
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`POST /v1/orgs/:orgId/crm/pipelines`

A pipeline (Customers admins): stages with probability and whether each is open, won or lost.

Auth: user access token or platform agent key · Scopes: crm:read, crm:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Request body

Field	Type	Required	Notes
`name`	`string`	Yes	1–80 characters; trimmed
`stages`	`object[]`	Yes	3–30 items
`stages[].id`	`string`	No	up to 40 characters
`stages[].name`	`string`	Yes	1–60 characters; trimmed
`stages[].probability`	`number`	Yes	0–100
`stages[].category`	`"open" \| "won" \| "lost"`	Yes
`isDefault`	`boolean`	No
`order`	`integer`	No	0–1000
`version`	`integer`	No

Response 201

{
  pipeline: {
    id: string
    name: string
    stages: {
      id: string
      name: string
      probability: number
      category: "lost" | "open" | "won"
    }[]
    isDefault?: boolean
    order: number
    version: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`PUT /v1/orgs/:orgId/crm/pipelines/:pipelineId`

Replaces a pipeline's name and stages (Customers admins), over version; a stage with deals can't be removed.

Auth: user access token or platform agent key · Scopes: crm:read, crm:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pipelineId`	A pipeline's id in Customers (`sales`, or `pip_…`).

Request body

Field	Type	Required	Notes
`name`	`string`	Yes	1–80 characters; trimmed
`stages`	`object[]`	Yes	3–30 items
`stages[].id`	`string`	No	up to 40 characters
`stages[].name`	`string`	Yes	1–60 characters; trimmed
`stages[].probability`	`number`	Yes	0–100
`stages[].category`	`"open" \| "won" \| "lost"`	Yes
`isDefault`	`boolean`	No
`order`	`integer`	No	0–1000
`version`	`integer`	No

Response 200

{
  pipeline: {
    id: string
    name: string
    stages: {
      id: string
      name: string
      probability: number
      category: "lost" | "open" | "won"
    }[]
    isDefault?: boolean
    order: number
    version: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`DELETE /v1/orgs/:orgId/crm/pipelines/:pipelineId`

Deletes a pipeline without opportunities (Customers admins); the default stays.

Auth: user access token or platform agent key · Scopes: crm:read, crm:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pipelineId`	A pipeline's id in Customers (`sales`, or `pip_…`).

Response 200

{
  ok: true
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`GET /v1/orgs/:orgId/crm/pipelines/:pipelineId/board`

The board: each stage's first opportunities by close date with its count and amount; stage and cursor page one column.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pipelineId`	A pipeline's id in Customers (`sales`, or `pip_…`).

Query parameter	Type	Required	Default	Notes
`perStage`	`integer`	No	`25`	1–100; coerced from a string
`stage`	`string`	No		up to 40 characters
`cursor`	`string`	No		up to 8,000 characters
`owner`	`string`	No		up to 40 characters

Response 200

{
  names: {
    records: {
      [key: string]: {
        id: string
        name: string
        object: string
      }
    }
    people: {
      [key: string]: string
    }
  }
  pipeline: {
    id: string
    name: string
    stages: {
      id: string
      name: string
      probability: number
      category: "lost" | "open" | "won"
    }[]
    isDefault?: boolean
    order: number
    version: number
  }
  columns: {
    stage: {
      id: string
      name: string
      probability: number
      category: "lost" | "open" | "won"
    }
    records: {
      id: string
      object: string
      version: number
      ownerId: string
      name: string
      fields: {
        [key: string]: unknown
      }
      createdAt: number
      updatedAt: number
      createdBy: string
      updatedBy: string
      via: "api" | "mcp" | "calendar" | "app" | "system" | "import" | "mail" | "marketing" | "convert"
    }[]
    cursor?: string
    total: {
      count: number
      amount: number
    }
  }[]
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`GET /v1/orgs/:orgId/crm/jobs`

Recent imports and exports (the caller's; every one for Customers admins).

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Response 200

{
  jobs: {
    id: string
    kind: "import" | "export"
    object: string
    state: "queued" | "ready" | "done" | "failed" | "uploading" | "running"
    fileName: string
    fileKey: string
    size: number
    headers?: string[]
    mapping?: string[]
    options?: {
      mode: "create" | "upsert"
      ownerId?: string
      dateOrder: "iso" | "dmy" | "mdy"
    }
    view?: {
      viewId?: string
      filters?: unknown[]
      sort?: unknown
      columns?: string[]
    }
    progress: {
      rows: number
      created: number
      updated: number
      failed: number
      offset: number
    }
    errors: {
      row: number
      message: string
    }[]
    error?: string
    createdBy: string
    createdByLabel: string
    createdAt: number
    updatedAt: number
  }[]
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`GET /v1/orgs/:orgId/crm/jobs/:jobId`

An import or export: state, progress counts and the first errors.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:jobId`	Job id: an agent job (`job_…`), under `pipelines` a pipeline job (`pjb_…`), or under `crm` an import or export (`cjb_…`); under `marketing` a list import (`mkj_…`).

Response 200

{
  job: {
    id: string
    kind: "import" | "export"
    object: string
    state: "queued" | "ready" | "done" | "failed" | "uploading" | "running"
    fileName: string
    fileKey: string
    size: number
    headers?: string[]
    mapping?: string[]
    options?: {
      mode: "create" | "upsert"
      ownerId?: string
      dateOrder: "iso" | "dmy" | "mdy"
    }
    view?: {
      viewId?: string
      filters?: unknown[]
      sort?: unknown
      columns?: string[]
    }
    progress: {
      rows: number
      created: number
      updated: number
      failed: number
      offset: number
    }
    errors: {
      row: number
      message: string
    }[]
    error?: string
    createdBy: string
    createdByLabel: string
    createdAt: number
    updatedAt: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`GET /v1/orgs/:orgId/crm/jobs/:jobId/download`

A finished export's download link (ten minutes).

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:jobId`	Job id: an agent job (`job_…`), under `pipelines` a pipeline job (`pjb_…`), or under `crm` an import or export (`cjb_…`); under `marketing` a list import (`mkj_…`).

Response 200

{
  url: string
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`POST /v1/orgs/:orgId/crm/imports`

Starts an import: up to 5 MB in content, or a presigned uploadUrl for the file (PUT it, then call uploaded).

Auth: user access token or platform agent key · Scopes: crm:read, crm:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Request body (up to 6 MB)

Field	Type	Required	Default	Notes
`object`	`string`	Yes		up to 40 characters
`fileName`	`string`	Yes		up to 200 characters
`size`	`integer`	No	`0`	0–53687091200
`content`	`string`	No

Response 201

{
  job: {
    id: string
    kind: "import" | "export"
    object: string
    state: "queued" | "ready" | "done" | "failed" | "uploading" | "running"
    fileName: string
    fileKey: string
    size: number
    headers?: string[]
    mapping?: string[]
    options?: {
      mode: "create" | "upsert"
      ownerId?: string
      dateOrder: "iso" | "dmy" | "mdy"
    }
    view?: {
      viewId?: string
      filters?: unknown[]
      sort?: unknown
      columns?: string[]
    }
    progress: {
      rows: number
      created: number
      updated: number
      failed: number
      offset: number
    }
    errors: {
      row: number
      message: string
    }[]
    error?: string
    createdBy: string
    createdByLabel: string
    createdAt: number
    updatedAt: number
  }
  uploadUrl?: string
}

Errors

Status	Message
`413`	Send files over 5 MB through the upload link.
`429`	Too many requests to Customers this minute. Try again shortly.

`POST /v1/orgs/:orgId/crm/imports/:jobId/uploaded`

Marks a presigned upload complete so the import can be previewed.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:jobId`	Job id: an agent job (`job_…`), under `pipelines` a pipeline job (`pjb_…`), or under `crm` an import or export (`cjb_…`); under `marketing` a list import (`mkj_…`).

Response 200

{
  job: {
    id: string
    kind: "import" | "export"
    object: string
    state: "queued" | "ready" | "done" | "failed" | "uploading" | "running"
    fileName: string
    fileKey: string
    size: number
    headers?: string[]
    mapping?: string[]
    options?: {
      mode: "create" | "upsert"
      ownerId?: string
      dateOrder: "iso" | "dmy" | "mdy"
    }
    view?: {
      viewId?: string
      filters?: unknown[]
      sort?: unknown
      columns?: string[]
    }
    progress: {
      rows: number
      created: number
      updated: number
      failed: number
      offset: number
    }
    errors: {
      row: number
      message: string
    }[]
    error?: string
    createdBy: string
    createdByLabel: string
    createdAt: number
    updatedAt: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`POST /v1/orgs/:orgId/crm/imports/:jobId/preview`

The header, ten sample rows and a suggested column mapping.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:jobId`	Job id: an agent job (`job_…`), under `pipelines` a pipeline job (`pjb_…`), or under `crm` an import or export (`cjb_…`); under `marketing` a list import (`mkj_…`).

Response 200

{
  job: {
    id: string
    kind: "import" | "export"
    object: string
    state: "queued" | "ready" | "done" | "failed" | "uploading" | "running"
    fileName: string
    fileKey: string
    size: number
    headers?: string[]
    mapping?: string[]
    options?: {
      mode: "create" | "upsert"
      ownerId?: string
      dateOrder: "iso" | "dmy" | "mdy"
    }
    view?: {
      viewId?: string
      filters?: unknown[]
      sort?: unknown
      columns?: string[]
    }
    progress: {
      rows: number
      created: number
      updated: number
      failed: number
      offset: number
    }
    errors: {
      row: number
      message: string
    }[]
    error?: string
    createdBy: string
    createdByLabel: string
    createdAt: number
    updatedAt: number
  }
  headers: string[]
  sample: string[][]
  mapping: string[]
  estimatedRows: number
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`POST /v1/orgs/:orgId/crm/imports/:jobId/dry-run`

Checks the first 1,000 rows with the mapping, writing nothing.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:jobId`	Job id: an agent job (`job_…`), under `pipelines` a pipeline job (`pjb_…`), or under `crm` an import or export (`cjb_…`); under `marketing` a list import (`mkj_…`).

Request body

Field	Type	Required	Default	Notes
`mapping`	`string[]`	Yes		up to 500 items; each up to 60 characters
`options`	`object`	Yes
`options.mode`	`"create" \| "upsert"`	No	`"create"`
`options.ownerId`	`string`	No		up to 40 characters
`options.dateOrder`	`"iso" \| "dmy" \| "mdy"`	No	`"dmy"`

Response 200

{
  checked: number
  valid: number
  updates: number
  errors: {
    row: number
    message: string
  }[]
  complete: boolean
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`POST /v1/orgs/:orgId/crm/imports/:jobId/start`

Queues the import; follow it on the job.

Auth: user access token or platform agent key · Scopes: crm:read, crm:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:jobId`	Job id: an agent job (`job_…`), under `pipelines` a pipeline job (`pjb_…`), or under `crm` an import or export (`cjb_…`); under `marketing` a list import (`mkj_…`).

Request body

Field	Type	Required	Default	Notes
`mapping`	`string[]`	Yes		up to 500 items; each up to 60 characters
`options`	`object`	Yes
`options.mode`	`"create" \| "upsert"`	No	`"create"`
`options.ownerId`	`string`	No		up to 40 characters
`options.dateOrder`	`"iso" \| "dmy" \| "mdy"`	No	`"dmy"`

Response 202

{
  job?: {
    id: string
    kind: "import" | "export"
    object: string
    state: "queued" | "ready" | "done" | "failed" | "uploading" | "running"
    fileName: string
    fileKey: string
    size: number
    headers?: string[]
    mapping?: string[]
    options?: {
      mode: "create" | "upsert"
      ownerId?: string
      dateOrder: "iso" | "dmy" | "mdy"
    }
    view?: {
      viewId?: string
      filters?: unknown[]
      sort?: unknown
      columns?: string[]
    }
    progress: {
      rows: number
      created: number
      updated: number
      failed: number
      offset: number
    }
    errors: {
      row: number
      message: string
    }[]
    error?: string
    createdBy: string
    createdByLabel: string
    createdAt: number
    updatedAt: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`GET /v1/orgs/:orgId/crm/meta`

The caller's view of Customers: objects, pipelines, settings, the people in the org and what the caller may do.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Response 200

{
  objects: {
    id: string
    label: string
    plural: string
    prefix: string
    glyph: string
    custom?: boolean
    nameFields: string[]
    fields: {
      id: string
      label: string
      type: "number" | "text" | "email" | "url" | "date" | "owner" | "pipeline" | "phone" | "textarea" | "checkbox" | "currency" | "stage" | "lookup" | "datetime" | "percent" | "picklist" | "multipicklist" | "lookups"
      required?: boolean
      custom?: boolean
      system?: boolean
      readOnly?: boolean
      searchable?: boolean
      help?: string
      maxLength?: number
      min?: number
      max?: number
      decimals?: number
      values?: {
        value: string
        label?: string
        inactive?: boolean
      }[]
      target?: string
      convertTo?: {
        object: "contact" | "account" | "opportunity"
        field: string
      }
    }[]
    rules: {
      id: string
      name: string
      active: boolean
      when: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      require: {
        field: string
        op: "eq" | "contains" | "lte" | "gt" | "lt" | "ne" | "gte" | "blank" | "notBlank"
        value?: unknown
      }[]
      message: string
      field?: string
    }[]
    sharing: "private" | "read" | "readwrite"
    indexes: {
      id: string
      eq: string[]
      sort: string
      status: "building" | "ready"
      builtin?: boolean
      createdAt: number
    }[]
    indexShards: number
    listColumns: string[]
    subtitleFields: string[]
    version: number
    createdAt: number
    updatedAt: number
  }[]
  pipelines: {
    id: string
    name: string
    stages: {
      id: string
      name: string
      probability: number
      category: "lost" | "open" | "won"
    }[]
    isDefault?: boolean
    order: number
    version: number
  }[]
  settings: {
    currency: string
    logEmails: boolean
    logMeetings: boolean
    roles: {
      owner: {
        viewAll: boolean | string[]
        modifyAll: boolean | string[]
      }
      admin: {
        viewAll: boolean | string[]
        modifyAll: boolean | string[]
      }
      developer: {
        viewAll: boolean | string[]
        modifyAll: boolean | string[]
      }
      viewer: {
        viewAll: boolean | string[]
        modifyAll: boolean | string[]
      }
    }
    version: number
  }
  people: {
    userId: string
    name: string
    email?: string
    role: "owner" | "admin" | "developer" | "viewer"
  }[]
  permissions: {
    write: boolean
    admin: boolean
    viewAll: string[]
    modifyAll: string[]
  }
  me: null | string
  limits: {
    bulkRecords: number
    importMb: number
    fieldsPerObject: number
    indexesPerObject: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`GET /v1/orgs/:orgId/crm/summary`

Home: the pipeline summary (counters) and the caller's open tasks.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Response 200

{
  tasks: [] | {
    id: string
    object: string
    version: number
    ownerId: string
    name: string
    fields: {
      [key: string]: unknown
    }
    createdAt: number
    updatedAt: number
    createdBy: string
    updatedBy: string
    via: "api" | "mcp" | "calendar" | "app" | "system" | "import" | "mail" | "marketing" | "convert"
  }[]
  month: string
  pipelines: {
    pipeline: {
      id: string
      name: string
      stages: {
        id: string
        name: string
        probability: number
        category: "lost" | "open" | "won"
      }[]
      isDefault?: boolean
      order: number
      version: number
    }
    stages: {
      stage: {
        id: string
        name: string
        probability: number
        category: "lost" | "open" | "won"
      }
      total: {
        count: number
        amount: number
      }
    }[]
    open: {
      count: number
      amount: number
      weighted: number
    }
    won: {
      count: number
      amount: number
    }
    lost: {
      count: number
      amount: number
    }
    history: {
      month: string
      won: {
        count: number
        amount: number
      }
      lost: {
        count: number
        amount: number
      }
    }[]
  }[]
  records: {
    [key: string]: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`GET /v1/orgs/:orgId/crm/search`

Records matching words, an email, a phone number or an id, that the caller can see.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Query parameter	Type	Required	Default	Notes
`q`	`string`	No	`""`	up to 200 characters
`objects`	`string`	No		up to 400 characters
`limit`	`integer`	No	`20`	1–50; coerced from a string

Response 200

{
  hits: {
    id: string
    object: string
    name: string
    subtitle: string
    ownerId: string
    score: number
  }[]
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`GET /v1/orgs/:orgId/crm/settings`

Customers settings: currency, Mail and Calendar logging, role permissions, with version.

Auth: user access token or platform agent key · Scope: crm:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Response 200

{
  settings: {
    currency: string
    logEmails: boolean
    logMeetings: boolean
    roles: {
      owner: {
        viewAll: boolean | string[]
        modifyAll: boolean | string[]
      }
      admin: {
        viewAll: boolean | string[]
        modifyAll: boolean | string[]
      }
      developer: {
        viewAll: boolean | string[]
        modifyAll: boolean | string[]
      }
      viewer: {
        viewAll: boolean | string[]
        modifyAll: boolean | string[]
      }
    }
    version: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

`PATCH /v1/orgs/:orgId/crm/settings`

Currency, Mail and Calendar logging, and what each role may see and change.

Auth: user access token or platform agent key · Scopes: crm:read, crm:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Request body

Field	Type	Required	Notes
`version`	`integer`	Yes	≥ 0
`currency`	`string`	No	matches `^[A-Z]{3}$`
`logEmails`	`boolean`	No
`logMeetings`	`boolean`	No
`roles`	`object`	No
`roles.owner`	`object`	No
`roles.owner.viewAll`	`boolean \| string[]`	Yes	up to 200 items; each up to 40 characters
`roles.owner.modifyAll`	`boolean \| string[]`	Yes	up to 200 items; each up to 40 characters
`roles.admin`	`object`	No
`roles.admin.viewAll`	`boolean \| string[]`	Yes	up to 200 items; each up to 40 characters
`roles.admin.modifyAll`	`boolean \| string[]`	Yes	up to 200 items; each up to 40 characters
`roles.developer`	`object`	No
`roles.developer.viewAll`	`boolean \| string[]`	Yes	up to 200 items; each up to 40 characters
`roles.developer.modifyAll`	`boolean \| string[]`	Yes	up to 200 items; each up to 40 characters
`roles.viewer`	`object`	No
`roles.viewer.viewAll`	`boolean \| string[]`	Yes	up to 200 items; each up to 40 characters
`roles.viewer.modifyAll`	`boolean \| string[]`	Yes	up to 200 items; each up to 40 characters

Response 200

{
  settings: {
    currency: string
    logEmails: boolean
    logMeetings: boolean
    roles: {
      owner: {
        viewAll: boolean | string[]
        modifyAll: boolean | string[]
      }
      admin: {
        viewAll: boolean | string[]
        modifyAll: boolean | string[]
      }
      developer: {
        viewAll: boolean | string[]
        modifyAll: boolean | string[]
      }
      viewer: {
        viewAll: boolean | string[]
        modifyAll: boolean | string[]
      }
    }
    version: number
  }
}

Errors

Status	Message
`429`	Too many requests to Customers this minute. Try again shortly.

Customers

On this page