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.

Type	Unique field	Description
`person`	`email_addresses`	Contacts and leads
`company`	`domains`	Organizations
`deal`	`name`	Opportunities and deals
`meeting`	None	Always creates
`task`	None	Action items and follow-ups

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"
    }
  }
}

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.

{
  "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.

Records

On this page