Items API
Manage items (deals, tickets, leads) within your CRM boards.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/crm/boards/:boardId/items | List items |
| GET | /api/crm/boards/:boardId/items/:id | Get single item |
| POST | /api/crm/boards/:boardId/items/search | Search items |
| POST | /api/crm/boards/:boardId/items | Create item |
| PUT | /api/crm/boards/:boardId/items/:itemId | Update item |
| DELETE | /api/crm/boards/:boardId/items | Delete items |
List Items
GET/api/crm/boards/:boardId/items
Retrieve all items in a board.
Query Parameters
column_idstring
Filter by column ID
searchstring
Search in item title
limitinteger
Results per page (default: 50)
offsetinteger
Pagination offset
bash
# List all items in a board
curl -X GET "https://api.cekat.ai/api/crm/boards/board_abc123/items" \
-H "Authorization: Bearer YOUR_API_KEY"
# Filter by column
curl -X GET "https://api.cekat.ai/api/crm/boards/board_abc123/items?column_id=col_001" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
200 OK
{
"success": true,
"data": [
{
"id": "item_001",
"board_id": "board_abc123",
"column_id": "col_001",
"title": "Acme Corp - Enterprise Deal",
"position": 0,
"values": {
"contact_name": "John Smith",
"email": "[email protected]",
"deal_value": "50000",
"probability": "75",
"expected_close": "2025-04-15"
},
"contact": {
"id": "contact_xyz",
"name": "John Smith",
"phone": "+62812345678"
},
"created_at": "2025-03-20T10:00:00Z",
"updated_at": "2025-03-27T14:30:00Z"
}
],
"pagination": {
"total": 127,
"limit": 50,
"offset": 0
}
}
Get Item
GET/api/crm/boards/:boardId/items/:id
Retrieve a single item by ID.
bash
curl -X GET "https://api.cekat.ai/api/crm/boards/board_abc123/items/item_001" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
200 OK
{
"success": true,
"data": {
"id": "item_001",
"board_id": "board_abc123",
"column_id": "col_001",
"title": "Acme Corp - Enterprise Deal",
"position": 0,
"values": {
"contact_name": "John Smith",
"email": "[email protected]",
"deal_value": "50000",
"probability": "75",
"expected_close": "2025-04-15"
},
"contact": {
"id": "contact_xyz",
"name": "John Smith",
"phone": "+62812345678",
"email": "[email protected]"
},
"conversation_ids": ["conv_001", "conv_002"],
"labels": ["enterprise", "hot-lead"],
"created_by": {
"id": "agent_123",
"name": "Sales Team"
},
"created_at": "2025-03-20T10:00:00Z",
"updated_at": "2025-03-27T14:30:00Z"
}
}
Search Items
POST/api/crm/boards/:boardId/items/search
Advanced search with multiple filters.
Request Body
querystring
Search term for title and values
column_idsarray
Filter by column IDs
value_filtersobject
Filter by specific field values
date_rangeobject
Filter by date range
sort_bystring
Sort field: created_at, updated_at, position
sort_orderstring
Sort direction: asc or desc
bash
curl -X POST "https://api.cekat.ai/api/crm/boards/board_abc123/items/search" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "acme",
"value_filters": {
"deal_value": { "gte": "10000" },
"probability": { "gte": "50" }
},
"sort_by": "created_at",
"sort_order": "desc"
}'
Response
200 OK
{
"success": true,
"data": [
{
"id": "item_001",
"title": "Acme Corp - Enterprise Deal",
"values": {
"deal_value": "50000",
"probability": "75"
}
}
],
"total": 3,
"limit": 50,
"offset": 0
}
Create Item
POST/api/crm/boards/:boardId/items
Create a new item in a board.
Request Body
titlestring*
Item title
column_idstring
Column ID (defaults to first column)
column_namestring
Alternative: find column by name
valuesobject
Custom field values
contact_idstring
Link to existing contact
labelsarray
Array of label strings
bash
curl -X POST "https://api.cekat.ai/api/crm/boards/board_abc123/items" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "New Lead - XYZ Company",
"column_name": "Lead",
"values": {
"contact_name": "Jane Doe",
"email": "[email protected]",
"deal_value": "25000",
"source": "Website"
},
"labels": ["hot-lead", "enterprise"]
}'
Response
201 OK
{
"success": true,
"data": {
"id": "item_new",
"board_id": "board_abc123",
"column_id": "col_001",
"title": "New Lead - XYZ Company",
"position": 42,
"values": {
"contact_name": "Jane Doe",
"email": "[email protected]",
"deal_value": "25000",
"source": "Website"
},
"labels": ["hot-lead", "enterprise"],
"created_at": "2025-03-27T15:00:00Z"
}
}
Update Item
PUT/api/crm/boards/:boardId/items/:itemId
Update an existing item.
Request Body
titlestring
New title
column_idstring
Move to different column
column_namestring
Alternative: move by column name
valuesobject
Update field values (partial update)
labelsarray
Replace labels
bash
# Update title and move to different stage
curl -X PUT "https://api.cekat.ai/api/crm/boards/board_abc123/items/item_001" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Acme Corp - Negotiation Phase",
"column_name": "Negotiation",
"values": {
"probability": "90"
}
}'
Response
200 OK
{
"success": true,
"data": {
"id": "item_001",
"column_id": "col_004",
"title": "Acme Corp - Negotiation Phase",
"values": {
"deal_value": "50000",
"probability": "90"
},
"updated_at": "2025-03-27T16:00:00Z"
}
}
Delete Items
DELETE/api/crm/boards/:boardId/items
Delete one or more items.
This action is irreversible. Deleted items cannot be recovered.
Request Body
item_idsarray*
Array of item IDs to delete
bash
curl -X DELETE "https://api.cekat.ai/api/crm/boards/board_abc123/items" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"item_ids": ["item_001", "item_002"]
}'
Response
200 OK
{
"success": true,
"data": {
"deleted": 2,
"item_ids": ["item_001", "item_002"]
}
}
Code Examples
javascript
const CRM_API = 'https://api.cekat.ai/api/crm';
const headers = {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
};
// List items
const listItems = async (boardId, filters = {}) => {
const params = new URLSearchParams(filters);
const response = await fetch(
`${CRM_API}/boards/${boardId}/items?${params}`,
{ headers }
);
return response.json();
};
// Create item
const createItem = async (boardId, item) => {
const response = await fetch(
`${CRM_API}/boards/${boardId}/items`,
{
method: 'POST',
headers,
body: JSON.stringify(item)
}
);
return response.json();
};
// Update item (move to different stage)
const moveItem = async (boardId, itemId, columnName) => {
const response = await fetch(
`${CRM_API}/boards/${boardId}/items/${itemId}`,
{
method: 'PUT',
headers,
body: JSON.stringify({ column_name: columnName })
}
);
return response.json();
};
// Usage
const newItem = await createItem('board_abc123', {
title: 'New Lead',
column_name: 'Lead',
values: { deal_value: '25000' }
});
console.log(`Created item: ${newItem.data.id}`);
// Move to next stage
await moveItem('board_abc123', newItem.data.id, 'Qualified');
Item Object
| Field | Type | Description |
|---|---|---|
id | string | Unique item identifier |
board_id | string | Parent board ID |
column_id | string | Current column ID |
title | string | Item title |
position | integer | Position within column |
values | object | Custom field values |
contact | object | Linked contact (if any) |
conversation_ids | array | Linked conversation IDs |
labels | array | Array of label strings |
created_by | object | Creator information |
created_at | string | Creation timestamp |
updated_at | string | Last update timestamp |