Create Activity
Create a new activity assigned to a commerce.
POST /api/activities
Create a new TASK activity with commerce assignment.
Auth: Required — CREATE_ACTIVITY permission
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | TASK |
reason | string | Yes | Reason for creating the activity |
channel | string | Yes | SALESMAN, CALLCENTER |
commerce_id | UUID | Yes | Target commerce ID |
idempotency_key | string | Yes | Unique key per tenant (prevents duplicates) |
scheduled_at | ISO 8601 | Yes | When the activity should be executed |
suggested_execution_time | ISO 8601 | No | Suggested time for execution |
user_status | string | No | User status context |
score | integer | No | Priority score |
assignment_reason | string | No | Reason for the assignment |
activity_details | object | No | Type-specific details — shape depends on type (see below) |
activity_details
For type: "TASK", the activity_details object carries route/operator assignment:
| Field | Type | Required | Description |
|---|---|---|---|
assigned_route_id | UUID | No | Assigned route |
assigned_route_external_id | string | No | Assigned route by external ID |
assigned_operator_id | UUID | No | Assigned operator |
assigned_operator_external_id | string | No | Assigned operator by external ID |
Example
curl -X POST https://api.reten.ai/api/activities \
-H "Authorization: Bearer <token>" \
-H "x-tenant-id: <tenant-id>" \
-H "Content-Type: application/json" \
-d '{
"type": "TASK",
"reason": "monthly_visit",
"channel": "SALESMAN",
"commerce_id": "880e8400-e29b-41d4-a716-446655440000",
"idempotency_key": "task-2025-01-15-001",
"scheduled_at": "2025-01-16T09:00:00.000Z",
"activity_details": {
"assigned_route_id": "dd0e8400-e29b-41d4-a716-446655440000",
"assigned_operator_id": "cc0e8400-e29b-41d4-a716-446655440000"
}
}'const response = await fetch("https://api.reten.ai/api/activities", {
method: "POST",
headers: {
"Authorization": "Bearer <token>",
"x-tenant-id": "<tenant-id>",
"Content-Type": "application/json",
},
body: JSON.stringify({
type: "TASK",
reason: "monthly_visit",
channel: "SALESMAN",
commerce_id: "880e8400-e29b-41d4-a716-446655440000",
idempotency_key: "task-2025-01-15-001",
scheduled_at: "2025-01-16T09:00:00.000Z",
activity_details: {
assigned_route_id: "dd0e8400-e29b-41d4-a716-446655440000",
assigned_operator_id: "cc0e8400-e29b-41d4-a716-446655440000",
},
}),
});
const activity = await response.json();import requests
response = requests.post(
"https://api.reten.ai/api/activities",
headers={
"Authorization": "Bearer <token>",
"x-tenant-id": "<tenant-id>",
},
json={
"type": "TASK",
"reason": "monthly_visit",
"channel": "SALESMAN",
"commerce_id": "880e8400-e29b-41d4-a716-446655440000",
"idempotency_key": "task-2025-01-15-001",
"scheduled_at": "2025-01-16T09:00:00.000Z",
"activity_details": {
"assigned_route_id": "dd0e8400-e29b-41d4-a716-446655440000",
"assigned_operator_id": "cc0e8400-e29b-41d4-a716-446655440000",
},
},
)
activity = response.json()Response 201 Created
{
"id": "ee0e8400-e29b-41d4-a716-446655440000",
"type": "TASK",
"reason": {
"code": "monthly_visit",
"label": "Visita Mensual"
},
"channel": "SALESMAN",
"status": "READY",
"userStatus": null,
"idempotencyKey": "task-2025-01-15-001",
"scheduledAt": "2025-01-16T09:00:00.000Z",
"commerceAssignment": {
"commerceId": "880e8400-e29b-41d4-a716-446655440000"
}
}Error Responses
| Status | Description |
|---|---|
400 | Validation error |
404 | Commerce not found |
409 | Idempotency key already exists |