Reten Docs

User Retention Status Configs

Per-tenant configuration of active user retention statuses.

Each tenant's catalog is seeded from the platform default retention status codes at tenant setup, and can be re-synced anytime from the import dialog (which reads GET /api/user-retention-status-configs/defaults). Each config lives entirely inside the tenant: it is identified by its unique code and carries the tenant's display label — there is no global catalog backing it.

GET /api/user-retention-status-configs

List all tenant user retention status configurations.

Auth: Required — VIEW_ACTIVITIES permission

Example

curl https://api.reten.ai/api/user-retention-status-configs \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>"
import axios from 'axios';

const response = await axios.get(
  'https://api.reten.ai/api/user-retention-status-configs',
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

const configs = response.data;

Response 200 OK

[
  {
    "id": "aa0e8400-e29b-41d4-a716-446655440000",
    "code": "habit",
    "label": "En hábito",
    "isActive": true,
    "createdAt": "2026-06-18T06:00:00.000Z",
    "updatedAt": "2026-06-18T06:00:00.000Z"
  },
  {
    "id": "bb0e8400-e29b-41d4-a716-446655440000",
    "code": "dormant",
    "label": "En riesgo",
    "isActive": true,
    "createdAt": "2026-06-18T06:00:00.000Z",
    "updatedAt": "2026-06-18T06:00:00.000Z"
  }
]

GET /api/user-retention-status-configs/defaults

Return the platform default retention statuses as a flat { code, label } catalog. The admin app uses this to prefill the import dialog with the statuses a tenant can adopt.

Auth: Required — VIEW_ACTIVITIES permission

This endpoint is prefill, not an entity. The payload is the hardcoded defaults catalog — non-authoritative and NOT persisted — and always lists every default regardless of what the tenant already has. To adopt them, the admin picks the ones that are still missing and creates them via POST /api/user-retention-status-configs/bulk. Nothing is created by calling this endpoint.

Example

curl https://api.reten.ai/api/user-retention-status-configs/defaults \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>"
import axios from 'axios';

const response = await axios.get(
  'https://api.reten.ai/api/user-retention-status-configs/defaults',
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

const defaults = response.data;

Response 200 OK

[
  {
    "code": "sign_up",
    "label": "Registrado"
  },
  {
    "code": "habit",
    "label": "En hábito"
  }
]

POST /api/user-retention-status-configs

Create a tenant user retention status configuration.

Auth: Required — MANAGE_ACTIVITY_CONFIG permission

Request Body

FieldTypeRequiredDescription
codestringYesCanonical retention status code (from the catalog)
labelstringYesDisplay label for this tenant

Example

curl -X POST https://api.reten.ai/api/user-retention-status-configs \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "habit",
    "label": "En hábito"
  }'
import axios from 'axios';

const response = await axios.post(
  'https://api.reten.ai/api/user-retention-status-configs',
  {
    code: 'habit',
    label: 'En hábito',
  },
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

Response 201 Created

POST /api/user-retention-status-configs/bulk

Bulk create tenant user retention status configurations.

Auth: Required — MANAGE_ACTIVITY_CONFIG permission

Request Body

FieldTypeRequiredDescription
itemsarrayYesArray of configurations to create
items[].codestringYesCanonical retention status code (from the catalog)
items[].labelstringYesDisplay label for this tenant

Example

curl -X POST https://api.reten.ai/api/user-retention-status-configs/bulk \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "code": "habit",
        "label": "En hábito"
      },
      {
        "code": "dormant",
        "label": "En riesgo"
      }
    ]
  }'
import axios from 'axios';

const response = await axios.post(
  'https://api.reten.ai/api/user-retention-status-configs/bulk',
  {
    items: [
      {
        code: 'habit',
        label: 'En hábito',
      },
      {
        code: 'dormant',
        label: 'En riesgo',
      },
    ],
  },
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

Response 201 Created

PATCH /api/user-retention-status-configs/:id

Update a tenant user retention status configuration.

Auth: Required — MANAGE_ACTIVITY_CONFIG permission

Request Body

FieldTypeRequiredDescription
labelstringNoDisplay label
is_activebooleanNoEnable or disable this config

Example

curl -X PATCH https://api.reten.ai/api/user-retention-status-configs/<id> \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Updated Label"
  }'
import axios from 'axios';

const response = await axios.patch(
  'https://api.reten.ai/api/user-retention-status-configs/<id>',
  {
    label: 'Updated Label',
  },
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

Response 200 OK

DELETE /api/user-retention-status-configs/:id

Deactivate a tenant user retention status configuration.

Auth: Required — MANAGE_ACTIVITY_CONFIG permission

Example

curl -X DELETE https://api.reten.ai/api/user-retention-status-configs/<id> \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>"
import axios from 'axios';

const response = await axios.delete(
  'https://api.reten.ai/api/user-retention-status-configs/<id>',
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

Response 204 No Content