Items
Create, retrieve, and update pipeline items. Requires items:read and/or items:write scopes.
List items
GET /v1/ext/items
Returns a list of items in your company. Custom fields are included using their field names as keys.
Response
[
{
"item_id": "01926a3b-...",
"short_id": "DEAL-42",
"name": "Acme Corp Deal",
"pipeline": "Sales",
"stage": "Qualified",
"status": "Open",
"contact_id": "01926a3b-...",
"source": "website",
"email": "john@acme.com",
"deal_value": 15000,
"created_at": "2026-04-01T10:30:00Z",
"updated_at": "2026-04-01T14:22:00Z"
}
]
Custom fields from your pipeline blueprint are included using their field names. The short_id field is an automatically generated identifier.
Query parameters
{
"pipeline_id": "string, filter by pipeline",
"stage_id": "string, filter by stage",
"status_id": "string, filter by status",
"created_after": "string (ISO 8601), filter by creation date"
}
Use the Pipelines API to look up pipeline, stage, and status IDs.
Get item
GET /v1/ext/items/{item_id}
Returns a single item by ID.
Create item
POST /v1/ext/items
Fields
{
"name": "string, required",
"pipeline_id": "string, required",
"stage_id": "string, required",
"status_id": "string",
"metadata": "object, custom field values keyed by field name"
}
Example
{
"name": "New Deal",
"pipeline_id": "01926a3b-...",
"stage_id": "01926a3b-...",
"metadata": {
"email": "jane@example.com",
"deal_value": 25000
}
}
Update item
PATCH /v1/ext/items/{item_id}
Fields
{
"stage_id": "string",
"status_id": "string",
"version": "number, for optimistic locking",
"metadata": "object, custom field values to update"
}
Only include the fields you want to update.
Example
{
"stage_id": "01926a3b-...",
"status_id": "01926a3b-...",
"metadata": {
"deal_value": 30000
}
}
Optimistic locking
Items include a version field that increments with each update. When updating an item, you can include the expected version in your request to prevent overwriting concurrent changes. If the version does not match, the update is rejected with a conflict error.
Duplicate check
Before creating an item, you can check for potential duplicates:
POST /v1/ext/items/check-duplicates
This uses the pipeline's duplicate detection configuration to find matches without creating the item.
Looking up IDs
To create or update items, you need pipeline, stage, and status IDs. Use the Pipelines API to look these up.