Custom objects

Custom objects let you model data beyond the standard person, company, deal, and meeting types. Names are normalized to a c_ prefixed identifier — "Sales Order" becomes c_sales_order.

Create a custom object

POST /schemas/objects

{
  "name": "Sales Order",
  "plural": "Sales Orders",
  "description": "Customer purchase orders and invoices"
}

Field	Type	Required	Notes
`name`	string	Yes	1–32 chars. Normalized to `c_` prefix (e.g., `c_sales_order`)
`plural`	string	Yes	1–32 chars. Used in the UI for display
`description`	string	No	Max 256 chars. Stored as AI context for this object type
`properties`	object	No	Initial field definitions (same format as schema properties)

Returns the created schema with a 201 status.

You can include initial fields in the properties object at creation time, or add them later via the schema properties endpoint.

Update a custom object

PUT /schemas/objects/{object}

Updates the schema for a custom object. The object param must use the c_ prefixed identifier. This is an async operation — returns an async-task resource.

{
  "$id": "entities/c_sales_order",
  "properties": {
    "order_number": { "type": "string", "title": "Order Number" },
    "total": { "type": "number", "title": "Total" },
    "status": {
      "type": "string",
      "title": "Status",
      "enum": ["Draft", "Submitted", "Fulfilled"]
    }
  }
}

The $id in the body must match the entity. This replaces the full schema definition — include all fields, not just changes.

Delete a custom object

DELETE /schemas/objects/{object}

Permanently deletes a custom object type and all its records. Only custom objects (with the c_ prefix) can be deleted. This is an async operation — returns an async-task resource.

Deletion is not available in all workspaces. Contact support if you need this enabled.

CRUD operations

Once created, custom objects use the same record endpoints as standard objects:

Operation	Endpoint
Create records	`POST /objects/{object}/records`
Bulk create	`POST /objects/{object}/records/bulk`
Get record	`GET /objects/{object}/records/{id}`
List records	`GET /objects/{object}/resources`
Update record	`PATCH /objects/{object}/records/{id}`
Bulk update	`PATCH /objects/{object}/records`
Delete record	`DELETE /objects/{object}/records/{id}`

Use the c_ prefixed name as the {object} parameter. See the records reference for full details.

Updating custom object records

For custom objects, always use the bulk PATCH endpoint — even when updating a single record. The single-record PATCH endpoint (/records/{id}) does not currently support custom objects.

# PATCH /objects/c_sales_order/records
curl -X PATCH \
  -H "Authorization: api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "id": "rec_01HX9Z2K3M4N5P6Q7R8S9T0U",
        "type": "c_sales_order",
        "attributes": { "status": "Fulfilled" }
      }
    ]
  }' \
  "https://api.clarify.ai/v1/workspaces/acme/objects/c_sales_order/records"