Reten Docs

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

FieldTypeRequiredDescription
activityIdUUIDNoReten activity ID (one of activityId or providerActivityId)
providerActivityIdstringNoExternal provider activity ID
commerceExternalIdstringYesExternal ID of the commerce
statusstringYesPENDING, COMPLETED, NOT_EXECUTED, CANCELED, TRANSFERRED
resultTypeCodestringNoTask result type code (e.g., success, not_home)
commentstringNoFree text comment
contactDirectionstringNoINBOUND or OUTBOUND
operatorExternalIdstringNoExternal ID of the operator
occurredAtISO 8601YesWhen the result occurred
rawPayloadobjectNoRaw provider payload (stored as-is)
hardOverridebooleanNoSkip state transition validation

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 '{
    "providerActivityId": "ext-123",
    "commerceExternalId": "store-001",
    "status": "COMPLETED",
    "resultTypeCode": "success",
    "comment": "Order placed successfully",
    "contactDirection": "OUTBOUND",
    "occurredAt": "2025-01-16T14:30:00.000Z"
  }'
const response = await fetch("https://api.reten.ai/api/activity-results/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "x-tenant-id": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    providerActivityId: "ext-123",
    commerceExternalId: "store-001",
    status: "COMPLETED",
    resultTypeCode: "success",
    comment: "Order placed successfully",
    contactDirection: "OUTBOUND",
    occurredAt: "2025-01-16T14:30:00.000Z",
  }),
});
const result = await response.json();
import requests

response = requests.post(
    "https://api.reten.ai/api/activity-results/tasks",
    headers={
        "Authorization": "Bearer <token>",
        "x-tenant-id": "<tenant-id>",
    },
    json={
        "providerActivityId": "ext-123",
        "commerceExternalId": "store-001",
        "status": "COMPLETED",
        "resultTypeCode": "success",
        "comment": "Order placed successfully",
        "contactDirection": "OUTBOUND",
        "occurredAt": "2025-01-16T14:30:00.000Z",
    },
)
result = response.json()

Response 201 Created

{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "activityId": "ee0e8400-e29b-41d4-a716-446655440000",
  "source": "RETEN_ACTIVITY",
  "status": "COMPLETED",
  "taskDetails": {
    "result": {
      "code": "success",
      "label": "Exito"
    },
    "comment": "Order placed successfully",
    "contactDirection": "OUTBOUND"
  }
}

Notes

  • If activityId or providerActivityId matches an existing activity, source is RETEN_ACTIVITY
  • If no activity is found, source is STANDALONE
  • For standalone results, a placeholder commerce is auto-created if needed
  • Updates enforce temporal guard (occurredAt must be after existing result's updatedAt)
  • The parent activity's status is synced based on the result status