Submit Result

POST /api/integration/activity-results/tasks

Submits the result of a task-type activity. The result is associated with the corresponding activity and updates its status in Reten.

Authentication: Required — permission SUBMIT_ACTIVITY_RESULT

Required headers

Header	Value
`x-api-key`	`YOUR_API_KEY`
`Content-Type`	`application/json`

Request body

Field	Type	Required	Description
`activity_id`	string (UUID)	No*	Activity ID in Reten
`provider_activity_id`	string	No*	Activity ID in the external system (for correlation)
`commerce_external_id`	string	Yes	Commerce external ID
`occurred_at`	string (ISO 8601)	Yes	Date and time when the activity was handled
`status`	string	Yes	Result status: `EFFECTIVE`, `NOT_EFFECTIVE`, or `PENDING`
`external_status`	string	No	Custom status from the external system
`hard_override`	boolean	No	Force overwrite of an existing result
`raw_payload`	object	No	Additional data from the external system (stored as-is)
`task_result`	object	Yes	Task result detail (see table below)

At least one of activity_id or provider_activity_id must be sent to identify the activity. If both are sent, activity_id takes priority.

`task_result` fields

Field	Type	Required	Description
`result`	string	Yes	Result type code (obtained from `/integration/task-result-type-configs`)
`comment`	string	No	Operator comment about the activity
`contact_type`	string	No	Contact direction: `INBOUND` or `OUTBOUND`
`operator_external_id`	string	No	External ID of the operator who handled the activity
`future_scheduled_at`	string (ISO 8601)	Conditional	Reschedule date. Required if the result type has `requiresFutureScheduledAt: true`
`payload`	object	No	Additional result data

Example

curl -X POST BASE_URL/api/integration/activity-results/tasks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "activity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "commerce_external_id": "COM-001",
    "occurred_at": "2026-04-11T10:30:00.000Z",
    "status": "EFFECTIVE",
    "task_result": {
      "result": "SALE_COMPLETED",
      "comment": "Customer accepted renewal offer",
      "operator_external_id": "OP-042",
      "contact_type": "OUTBOUND"
    }
  }'

const response = await fetch(
  `${BASE_URL}/api/integration/activity-results/tasks`,
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      activity_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      commerce_external_id: "COM-001",
      occurred_at: "2026-04-11T10:30:00.000Z",
      status: "EFFECTIVE",
      task_result: {
        result: "SALE_COMPLETED",
        comment: "Customer accepted renewal offer",
        operator_external_id: "OP-042",
        contact_type: "OUTBOUND",
      },
    }),
  }
);

const data = await response.json();

import requests

response = requests.post(
    f"{BASE_URL}/api/integration/activity-results/tasks",
    headers={
        "x-api-key": "YOUR_API_KEY",
    },
    json={
        "activity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "commerce_external_id": "COM-001",
        "occurred_at": "2026-04-11T10:30:00.000Z",
        "status": "EFFECTIVE",
        "task_result": {
            "result": "SALE_COMPLETED",
            "comment": "Customer accepted renewal offer",
            "operator_external_id": "OP-042",
            "contact_type": "OUTBOUND",
        },
    },
)

data = response.json()

Response `201 Created`

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "activityId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "resultStatus": "EFFECTIVE",
  "source": "INTEGRATION",
  "origin": "API",
  "occurredAt": "2026-04-11T10:30:00.000Z",
  "createdAt": "2026-04-11T10:30:05.000Z",
  "resultDetails": {
    "type": "TASK",
    "result": {
      "code": "SALE_COMPLETED",
      "label": "Venta completada",
      "isPositive": true
    },
    "comment": "Customer accepted renewal offer",
    "externalOperatorId": "OP-042",
    "operator": {
      "externalId": "OP-042",
      "name": "Carlos Pérez"
    },
    "requiresFutureScheduledAt": false
  }
}

Validation rules

The commerce_external_id must exist in the tenant
The result code must be a valid result type (see List Configurations)
If the result type has requiresFutureScheduledAt: true, the future_scheduled_at field is mandatory and must be a future date
If the activity already has a result, the request returns 409 Conflict (unless hard_override: true)

Errors

Status	Description
`400`	Validation error — missing fields, invalid result type, or `future_scheduled_at` required
`401`	API key missing or invalid
`403`	The key does not have the `SUBMIT_ACTIVITY_RESULT` permission
`404`	Activity or commerce not found in the tenant
`409`	The activity already has a registered result