Users

The Users API lets you list, retrieve, and update user records associated with your Agent’s team. Users are identified by an internal UUID and optionally by your own external_id (for example a CRM id or the same identifier you pass as user on chat completions).

Base path: /api/v1/users on your Agent’s domain.

Authentication #

See Authentication on the Overview page for how to authenticate Fusion API requests. An API key is always required for Users endpoints — same-origin requests are not exempt. Results are limited to the Agent’s team.

List Users #

Use GET /api/v1/users to get a paginated list of users for the authenticated Agent’s team, ordered by created_at descending.

curl \
--header 'x-api-key: apg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--url 'https://my.gospel.bot/api/v1/users?page=1&per_page=50'

Pagination #

Parameter	Type	Default	Max	Description
page	integer	1	—	Page number
per_page	integer	50	100	Records per page

Filter Parameters #

All filters are optional and combinable.

Parameter	Type	Description
external_id	string	Exact match on the user’s external identifier
tags	string	Comma-separated tag ids; user must contain all listed tags
responder_id	integer	Users whose persisted responder for this Agent matches the id
min_timestamp	string	Minimum created_at (ISO 8601 timestamp)
max_timestamp	string	Maximum created_at (ISO 8601 timestamp)

Response #

{
    "data": [ /* array of user objects */ ],
    "total": 142,
    "page": 1,
    "per_page": 50
}

total reflects the full count matching the applied filters (not just the current page).

Get User #

Use GET /api/v1/users/{user_id} to retrieve a single user. The path accepts either:

• Internal UUID (id)
• Your external_id string

If the user does not exist on the Agent’s team, a 404 is returned.

curl \
--header 'x-api-key: apg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--url https://my.gospel.bot/api/v1/users/crm-123

Response #

{
    "data": { /* user object */ }
}

List User Flags #

Use GET /api/v1/users/flags to get a paginated list of user flag definitions for the authenticated Agent’s team (rows from the user_flags table). This returns the flag catalog you can reference when setting flags on a user — not the per-user flag values (those appear on the user object as flags).

curl \
--header 'x-api-key: apg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--url 'https://my.gospel.bot/api/v1/users/flags?page=1&per_page=50'

Pagination #

Parameter	Type	Default	Max	Description
page	integer	1	—	Page number
per_page	integer	50	100	Records per page

Response #

{
    "data": [
        {
            "id": 42,
            "name": "Donated",
            "user_id": 9,
            "team_id": 3,
            "synced_at": "2024-06-01 12:00:00"
        }
    ],
    "total": 1,
    "page": 1,
    "per_page": 50
}

User Flag Object #

Field	Type	Description
id	integer	Flag definition id (use this as the key when patching flags on a user)
name	string	Display name
user_id	integer | null	Upstream owning user id when present (mirrored from Ignite)
team_id	integer | null	Team that owns the flag definition
synced_at	string	UTC timestamp when the definition was last synced

Update User #

Use PATCH /api/v1/users/{user_id} to update a user. The path accepts UUID or external_id, same as get. Only include fields you want to change. Unknown properties are rejected.

curl \
--request PATCH \
--header 'x-api-key: apg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "external_id": "crm-123",
    "tags": ["Praise", 4],
    "responder_id": 5,
    "flags": {
        "42": true,
        "7": null
    }
}' \
--url https://my.gospel.bot/api/v1/users/crm-123

Request Body #

Field	Type	Description
external_id	string | null	Set or clear the external identifier (max 100 characters)
tags	array	Replace applied tags. Items may be existing tag ids (integer) and/or tag names (string) in the team’s default language. Unknown ids/names return 400. Empty [] clears all tags. Tags are never created by this endpoint.
responder_id	integer	Persist this responder for the user on the current Agent. Must be an active responder on the Agent; otherwise 400.
flags	object	Partial merge of flag values. Keys are flag ids (as strings). Values: true / false to set, null to clear. Omitted keys are left unchanged. Unknown flag ids return 400.

Successful updates return the same shape as get: { "data": { /* user object */ } }.

User Object #

Field	Type	Description
id	string (UUID)	Internal user identifier
external_id	string | null	Your identifier for the user
team_id	integer	Team that owns the user
created_at	string	UTC timestamp when the user was created
migrated_at	string | null	Set when an anonymous user was merged into an authenticated user
migrated_to_user_id	string | null	Target user id after migration, if any
tags	array	Applied tags as { id, name } objects
responder_id	integer | null	Persisted responder for this Agent
flags	array	Applied flags as { id, name, value, set_at } objects

Setting a User’s Responder #

A responder is a configured persona/routing target on an Agent (managed in Apologist Ignite). The user’s responder_id is the persisted responder for that Agent — used when responder routing is enabled, distinct from the responder chosen for a single chat turn.

Via the Users API #

Patch the user with an active responder_id:

curl \
--request PATCH \
--header 'x-api-key: apg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "responder_id": 5
}' \
--url https://my.gospel.bot/api/v1/users/crm-123

If the newly assigned responder has configured set_flags in Ignite, those flag values are applied automatically when the persisted responder changes.

Via signed action links (end-user clicks) #

Agents can also expose one-click responder changes in CTA or guardrail content using the merge tag:

{set_responder_link:5}

At render time this becomes a signed URL on the Agent host:

https://my.gospel.bot/api/set-responder?t=<jwt>&redirect=<optional-url>

• Authenticated by the signed token (not an API key)
• Requires a known user identity in the conversation; otherwise the merge tag is stripped
• On success, persists the responder (and any responder set_flags) and returns a 307 redirect
• Optional redirect must be a valid http/https URL; otherwise the Agent origin is used
• This is not part of the versioned /api/v1 surface — intended for end-user clicks, not server-to-server integrations

Setting a User Flag #

User flags are boolean attributes defined for your team in Apologist Ignite (for example “Donated” or “Newsletter”). Values are stored per user and returned on list/get as { id, name, value, set_at }.

Via the Users API #

Patch a partial map of flag id → value. Use null to clear a flag:

curl \
--request PATCH \
--header 'x-api-key: apg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "flags": {
        "42": true,
        "7": false,
        "9": null
    }
}' \
--url https://my.gospel.bot/api/v1/users/crm-123

Via signed action links (end-user clicks) #

In CTA or guardrail content, use:

{set_flag_link:42}

This becomes a signed URL that sets that flag to true:

https://my.gospel.bot/api/set-flag?t=<jwt>&redirect=<optional-url>

• Same signed-token / redirect behavior as set-responder
• Not part of /api/v1; meant for end-user clicks
• Flags can also be set implicitly by Agent configuration (responder set_flags, CTAs, guardrails, automations) when those fire

Error Responses #

Status	Meaning
400	Invalid JSON, unknown tag/flag/responder, or other request error
403	Missing or invalid API key
404	User not found on this Agent’s team
422	Body failed schema validation
500	Internal server error
503	Agent not found or inactive for the request’s host