Target Users

GET /api/activities/:id/target-users

List the target users for an activity.

Auth: Required — VIEW_ACTIVITIES permission

Target User Statuses

Status	Description
`PENDING`	Not yet resolved — waiting for resolution (ON_DISPATCH/MANUAL strategy) or retry
`RESOLVED`	A commerce user has been matched and assigned
`LOCKED`	Resolved and locked — cannot be modified
`FAILED`	Resolution attempted but no match found

Lock Reasons

Lock Reason	Description
`CRITERIA_MATCH`	Matched via resolution criteria (e.g., ROLE_MATCH)
`FALLBACK_COMMERCE_REP`	Fell back to commerce representative
`FALLBACK_OWNER`	Fell back to commerce owner
`MANUAL_ASSIGNMENT`	Manually assigned via the resolve endpoint

Path Parameters

Parameter	Type	Description
`id`	UUID	Activity ID

Example

curl https://api.reten.ai/api/activities/ee0e8400-e29b-41d4-a716-446655440000/target-users \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>"

import axios from 'axios';

const response = await axios.get(
  'https://api.reten.ai/api/activities/ee0e8400-e29b-41d4-a716-446655440000/target-users',
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

const targetUsers = response.data;

Response `200 OK`

[
  {
    "id": "110e8400-e29b-41d4-a716-446655440000",
    "commerceUserId": "aa0e8400-e29b-41d4-a716-446655440000",
    "resolutionStatus": "LOCKED",
    "resolutionStrategy": "ON_CREATION",
    "lockReason": "CRITERIA_MATCH",
    "resolvedAt": "2025-01-15T10:30:00.000Z",
    "lockedAt": "2025-01-15T10:31:00.000Z",
    "commerceUser": {
      "firstName": "Maria",
      "lastName": "Garcia"
    }
  }
]

PATCH /api/activities/:id/target-users/:targetUserId/resolve

Manually assign a commerce user as the target user. Only works on PENDING or FAILED target users that are not locked.

Auth: Required — CREATE_ACTIVITY permission

Path Parameters

Parameter	Type	Description
`id`	UUID	Activity ID
`targetUserId`	UUID	Target user record ID

Request Body

Field	Type	Required	Description
`commerce_user_id`	UUID	Yes	Commerce user to assign

Example

curl -X PATCH https://api.reten.ai/api/activities/ee0e8400-e29b-41d4-a716-446655440000/target-users/110e8400-e29b-41d4-a716-446655440000/resolve \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "commerce_user_id": "aa0e8400-e29b-41d4-a716-446655440000"
  }'

import axios from 'axios';

const response = await axios.patch(
  'https://api.reten.ai/api/activities/ee0e8400-e29b-41d4-a716-446655440000/target-users/110e8400-e29b-41d4-a716-446655440000/resolve',
  {
    commerce_user_id: 'aa0e8400-e29b-41d4-a716-446655440000',
  },
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

Response `200 OK`

Returns the updated target user record.

Error Responses

Status	Description
`400`	Activity is in a terminal status
`400`	Target user is already locked
`400`	Target user is not in `PENDING` or `FAILED` status