Activity Results
Create Activity Result
Create a task activity result.
POST /api/activity-results/tasks
Create a result for a task activity. Results can be linked to existing Reten activities or created as standalone entries.
Auth: Required — CREATE_ACTIVITY permission
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
activity_id | UUID | No | Reten activity ID (one of activity_id or provider_activity_id) |
provider_activity_id | string | No | External provider activity ID |
commerce_external_id | string | Yes | External ID of the commerce |
occurred_at | ISO 8601 | Yes | When the result occurred |
status | string | Yes | PENDING, COMPLETED, NOT_EXECUTED, CANCELED, TRANSFERRED |
external_status | string | No | Provider-specific status string |
hard_override | boolean | No | Skip state transition validation |
raw_payload | object | No | Raw provider payload (stored as-is) |
task_result | object | Yes | Task-specific result details (see below) |
task_result Object
| Field | Type | Required | Description |
|---|---|---|---|
result | string | Yes | Task result type code (e.g., success, not_home) |
comment | string | No | Free text comment |
contact_type | string | No | INBOUND or OUTBOUND |
operator_external_id | string | No | External ID of the operator |
future_scheduled_at | ISO 8601 | No | Suggested date for a follow-up activity |
payload | object | No | Additional task-specific data |
Example
curl -X POST https://api.reten.ai/api/activity-results/tasks \
-H "Authorization: Bearer <token>" \
-H "x-tenant-id: <tenant-id>" \
-H "Content-Type: application/json" \
-d '{
"provider_activity_id": "ext-123",
"commerce_external_id": "store-001",
"status": "COMPLETED",
"occurred_at": "2025-01-16T14:30:00.000Z",
"task_result": {
"result": "success",
"comment": "Order placed successfully",
"contact_type": "OUTBOUND"
}
}'import axios from 'axios';
const response = await axios.post(
'https://api.reten.ai/api/activity-results/tasks',
{
provider_activity_id: 'ext-123',
commerce_external_id: 'store-001',
status: 'COMPLETED',
occurred_at: '2025-01-16T14:30:00.000Z',
task_result: {
result: 'success',
comment: 'Order placed successfully',
contact_type: 'OUTBOUND',
},
},
{
headers: {
Authorization: 'Bearer <token>',
'x-tenant-id': '<tenant-id>',
},
}
);Response 201 Created
{
"id": "770e8400-e29b-41d4-a716-446655440000",
"activityId": "ee0e8400-e29b-41d4-a716-446655440000",
"source": "RETEN_ACTIVITY",
"resultStatus": "COMPLETED",
"occurredAt": "2025-01-16T14:30:00.000Z",
"taskDetails": {
"result": "success",
"comment": "Order placed successfully",
"contactType": "OUTBOUND"
},
"createdAt": "2025-01-16T14:30:05.000Z",
"updatedAt": "2025-01-16T14:30:05.000Z"
}Notes
- If
activity_idorprovider_activity_idmatches an existing activity, source isRETEN_ACTIVITY - If no activity is found, source is
STANDALONE - For standalone results, a placeholder commerce is auto-created if needed
- Updates enforce temporal guard (
occurred_atmust be after existing result'supdatedAt) - The parent activity's status is synced based on the result status
Error Responses
| Status | Description |
|---|---|
400 | Validation error — invalid or missing fields |
401 | Missing or invalid authentication token |
404 | Activity not found (when activity_id is provided) |
409 | Stale event — occurred_at is older than existing result |
409 | Invalid state transition (unless hard_override: true) |