Records

Records are the core data in Clarify — people, companies, deals, and custom objects. Each object type has a unique field used for upsert matching.

Custom object types follow a c_ prefix (e.g. c_sales_order, c_subscription). They use the same record endpoints as standard types — substitute the custom object's type name in the path. Unique fields are configurable; check your object's schema via GET /schemas to see which field (if any) drives upsert matching. See custom objects for the full management API.

Create a record

POST /objects/{object}/records

Creates a record. If a record with the same unique field value already exists, Clarify updates it instead (upsert). Don't include id in the body — it's auto-generated and will return a 422 if present.

{
  "data": {
    "type": "person",
    "attributes": {
      "name": "Taylor Reeves",
      "email_addresses": { "items": ["taylor@example.com"] },
      "title": "VP of Sales",
      "company_name": "Acme Corp"
    }
  }
}

Returns the created record with its id.

Bulk create

POST /objects/{object}/records/bulk

Creates multiple records in a single request (max 25 per batch). The batch is atomic — if any record fails validation, the whole batch is rejected. Upsert matching applies per record.

{
  "data": [
    {
      "type": "person",
      "attributes": {
        "name": "Taylor Reeves",
        "email_addresses": { "items": ["taylor@example.com"] },
        "title": "VP of Sales"
      }
    },
    {
      "type": "person",
      "attributes": {
        "name": "Jordan Kim",
        "email_addresses": { "items": ["jordan@example.com"] },
        "title": "Account Executive"
      }
    }
  ]
}

Get a record

GET /objects/{object}/records/{id}

Returns a single record by ID. Use ?include=companies (or other relationship names) to expand related records inline.

{
  "data": {
    "id": "per_01HX9Z2K3M4N5P6Q7R8S9T0U",
    "type": "person",
    "attributes": {
      "name": "Taylor Reeves",
      "email_addresses": { "items": ["taylor@example.com"] },
      "title": "VP of Sales",
      "company_name": "Acme Corp",
      "_created_at": "2024-03-01T12:00:00Z",
      "_updated_at": "2024-03-15T09:30:00Z"
    }
  }
}

Every record also returns _created_by and _updated_by — opaque user identifiers (e.g. user_01K59WY3MBB1KE6SZSKNEW1RDR, google-oauth2|106236165388989412707, or system). There is no public users endpoint to resolve them. See Tasks → User IDs.

List records

GET /objects/{object}/resources

Returns a paginated list of records. Uses offset-based pagination — see pagination for details.

{
  "data": [
    {
      "id": "per_01HX9Z2K3M4N5P6Q7R8S9T0U",
      "type": "person",
      "attributes": {
        "name": "Taylor Reeves",
        "email_addresses": { "items": ["taylor@example.com"] },
        "title": "VP of Sales"
      }
    },
    {
      "id": "per_01HX9Z2K3M4N5P6Q7R8S9T0V",
      "type": "person",
      "attributes": {
        "name": "Jordan Kim",
        "email_addresses": { "items": ["jordan@example.com"] },
        "title": "Account Executive"
      }
    }
  ],
  "meta": {
    "total_records": 284,
    "total_pages": 12,
    "offset": 0,
    "limit": 25
  },
  "links": {
    "next": "https://api.clarify.ai/v1/workspaces/acme/objects/person/resources?page[limit]=25&page[offset]=25"
  }
}

See search and filter for filtering, sorting, and field selection.

Update a record

PATCH /objects/{object}/records/{id}

Updates a single record. Only fields included in the body are changed — omitted fields are left as-is.

{
  "data": {
    "type": "person",
    "attributes": {
      "title": "Chief Revenue Officer",
      "company_name": "Acme Holdings"
    }
  }
}

Bulk update

PATCH /objects/{object}/records

Updates multiple records in one request. Each record must include id. Clarify pre-validates all IDs before writing — returns 404 if any are missing.

Like single-record PATCH, only fields included in the body are changed — any attributes you omit are left as-is on each record. (Older versions of the bulk endpoint nulled missing fields; that was fixed in April 2026.)

{
  "data": [
    {
      "id": "per_01HX9Z2K3M4N5P6Q7R8S9T0U",
      "type": "person",
      "attributes": {
        "title": "Chief Revenue Officer"
      }
    },
    {
      "id": "per_01HX9Z2K3M4N5P6Q7R8S9T0V",
      "type": "person",
      "attributes": {
        "title": "Senior Account Executive"
      }
    }
  ]
}

Delete a record

DELETE /objects/{object}/records/{id}

Deletes a single record. Returns 204 No Content on success with no response body.

Bulk delete

DELETE /objects/{object}/records

Deletes multiple records. Uses { items: [...] } format — not { data: [...] }.

{
  "items": [
    "per_01HX9Z2K3M4N5P6Q7R8S9T0U",
    "per_01HX9Z2K3M4N5P6Q7R8S9T0V"
  ]
}

Collection fields

Fields that hold multiple values — email addresses, domains, and phone numbers — use { items: [...] } format, not plain arrays.

{
  "email_addresses": { "items": ["taylor@example.com", "taylor@personal.com"] },
  "domains": { "items": ["example.com", "acmecorp.io"] },
  "phone_numbers": { "items": ["+14155550100"] }
}

This applies to both create and update requests. Sending { items: [] } clears the field. Sending the field as a plain array will return a 422.

Rich text fields

Some fields use a rich text format based on BlockNote instead of plain strings. These fields are stored as an object and cannot be set with a plain string value — you must use the BlockNote structure.

Rich text fields are an object with a text property containing an array of BlockNote blocks:

{
  "description": {
    "text": [
      {
        "id": "1",
        "type": "paragraph",
        "props": {},
        "content": [
          {
            "type": "text",
            "text": "Your text here",
            "styles": {}
          }
        ],
        "children": []
      }
    ]
  }
}