Users

Overview

Users are people who belong to organizations. Each organization must have at least one owner (created with the organization), and can have additional team members.

Users are identified by your system’s external_id - this makes it easy to map Answering Agent users to your own database without exposing internal IDs.

Base URL

Playground: https://playground.answeringagent.com/api/v1 Production: https://answeringagent.com/api/v1 All endpoints require the X-API-KEY header containing a valid partner API key.

Understanding External IDs

The external_id is your unique identifier for a user from your system:

Use your existing user IDs (e.g., "user_12345", "customer_abc")
Makes API calls simple: GET /users/user_12345/embed-token
Maintains clean mapping between your database and Answering Agent
Must be unique across all users for your partner account

Example Flow:

User signs up in your system → assigned ID "cust_789"
Create organization in Answering Agent → use external_id: "cust_789"
Later: Get embed token → GET /users/cust_789/embed-token

Key Concepts

Organization Owners vs Additional Users

Owner: Created automatically when you create an organization. Has full permissions.
Additional Users: Team members you add to the organization after creation.

Both types are managed through the same /users endpoints.

When to Use External ID

Always! The external_id is how you reference users in the API:

GET /users/{external_id} - Look up user details
GET /users/{external_id}/embed-token - Get embed token
All other user operations

You rarely need to use Answering Agent’s internal user IDs.

Can users belong to multiple organizations?

Yes! Users can be members of multiple organizations with different roles in each. This is useful for consultants, franchise managers, or team members who work across multiple locations.

1. List Users

Property	Value
Method	`GET /users`
Returns	`200 OK` on success

List all users for the authenticated reseller, with optional organization filtering.

Query Parameters

organization_id

integer

Filter users by organization ID

Example

# List all users
curl -H "X-API-KEY: <your-api-key>" \
     https://answeringagent.com/api/v1/users

# List users in specific organization
curl -H "X-API-KEY: <your-api-key>" \
     https://answeringagent.com/api/v1/users?organization_id=123

200 OK
[
  {
    "id": 2144,
    "external_id": "user_123",
    "name": "John Doe",
    "email": "[email protected]",
    "created_at": "2025-05-14T12:00:00Z",
    "updated_at": "2025-05-14T12:00:00Z"
  }
]

2. Create User

Property	Value
Method	`POST /users`
Returns	`201 Created` on success

Create a new user, optionally assigning them to an organization.

Query Parameters

organization_id

integer

Organization to assign the user to

Request Body

{
  "external_id": "your-system-id",        // required – This is the user's ID in YOUR (the reseller's) system
  "email":       "[email protected]",  // required – customer e‑mail
  "name":        "John Doe",              // optional – customer name
  "team_name":   "John's Team",           // optional – team name (creates new team if not assigned to organization)
  "organization_id": 123,                 // optional – organization ID (alternative to query parameter)
  "locations": [                          // DEPRECATED – use /locations endpoint instead
    { "name": "Main St", "area_code": "303" },
    { "name": "Elm Ave", "area_code": "720" }
  ]
}

The locations array is deprecated. Use the dedicated Locations API for better location management.

Success Response

201 Created
{
  "embed_token": "MTIzNDV8ZDgyZDk3Mzg1OTAxNTkzNA",
  "user": {
    "id": 2144,
    "name": "John Doe",
    "email": "[email protected]",
    "external_id": "your-system-id",
    "parent_user_id": 7,
    "created_at": "2025-05-14T12:00:00Z",
    "updated_at": "2025-05-14T12:00:00Z"
  },
  "team": {
    "id": 3109,
    "name": "Default",
    "created_at": "2025-05-14T12:00:00Z",
    "updated_at": "2025-05-14T12:00:00Z"
  },
  "locations": [
    { "location": "Main St", "phone_id": 889 },
    { "location": "Elm Ave", "phone_id": 890 }
  ]
}

The embed_token is a secure, compact token that authenticates the user when embedding the Answering Agent dashboard. Store this securely and use it with the embed system.

About External IDs:

The external_id is the user’s ID in your system (not Answering Agent’s internal ID)
Must be unique across all of your users (your partner account)
Use it for all API operations: looking up users, generating embed tokens, etc.
Provides clean separation between your system and Answering Agent

Error Codes

Code	Meaning	Typical Cause
401	Unauthorized	Missing or incorrect `X-API-KEY`.
422	Validation Error	Required field absent or malformed.
500	Internal Server Error	Unexpected failure during provisioning.

3. Get User by External ID

Property	Value
Method	`GET /users/{external_id}`
Returns	`200 OK` on success

Example

curl -H "X-API-KEY: <your-api-key>" \
     https://answeringagent.com/api/v1/users/your-system-id

200 OK
{
  "id": 2144,
  "name": "John Doe",
  "email": "[email protected]",
  "external_id": "your-system-id",
  "created_at": "2025-05-14T12:00:00Z",
}

The embed token is not returned in user lookup responses for security reasons. Use the dedicated embed token endpoints to retrieve or manage tokens.

4. Get User by Email

Property	Value
Method	`GET /users/by-email?email={address}`
Returns	`200 OK` on success

Example

curl -H "X-API-KEY: <your-api-key>" \
     "https://answeringagent.com/api/v1/users/[email protected]"

200 OK
{
  "id": 2144,
  "name": "John Doe",
  "email": "[email protected]",
  "external_id": "your-system-id",
  "created_at": "2025-05-14T12:00:00Z"
}

5. Update User

Property	Value
Method	`PATCH /users/{external_id}`
Returns	`200 OK` on success

Request Body

{
  "name": "John Smith",              // optional – updated name
  "email": "[email protected]",   // optional – updated email
  "team_name": "Updated Team Name"   // optional – updated team name
}

Success Response

200 OK
{
  "user": {
    "id": 2144,
    "name": "John Smith",
    "email": "[email protected]",
    "external_id": "your-system-id",
    "created_at": "2025-05-14T12:00:00Z",
    "updated_at": "2025-05-15T10:30:00Z"
  }
}

6. Delete User

Property	Value
Method	`DELETE /users/{external_id}`
Returns	`200 OK` on success

Example

curl -X DELETE \
     -H "X-API-KEY: <your-api-key>" \
     https://answeringagent.com/api/v1/users/your-system-id

200 OK
{
  "message": "User deleted successfully"
}

Embed Token Management

Get Current Embed Token

Property	Value
Method	`GET /users/{external_id}/embed-token`
Returns	`200 OK` on success

Retrieve the current embed token for a user. If the user doesn’t have a signing secret, one will be generated automatically.

Example

curl -H "X-API-KEY: <your-api-key>" \
     https://answeringagent.com/api/v1/users/your-system-id/embed-token

200 OK
{
  "embed_token": "MTIzNDV8ZDgyZDk3Mzg1OTAxNTkzNA",
  "user_id": "your-system-id"
}

Generate New Embed Token

Property	Value
Method	`POST /users/{external_id}/embed-token`
Returns	`200 OK` on success

Generate a new embed token for a user. This invalidates the previous token by rotating the user’s signing secret.

Generating a new embed token will invalidate all existing embedded dashboards using the old token. Ensure you update all embedded instances with the new token.

Example

curl -X POST \
     -H "X-API-KEY: <your-api-key>" \
     https://answeringagent.com/api/v1/users/your-system-id/embed-token

200 OK
{
  "embed_token": "OTg3NjV8YWJjZGVmZ2hpams1Njc4OTA",
  "user_id": "your-system-id",
  "message": "New embed token generated successfully"
}

Security Features

Compact & Secure: Embed tokens use URL-safe base64 encoding and HMAC-SHA256 for cryptographic integrity. User-Specific: Each token is tied to a specific user and cannot be transferred or reused for other users. Invalidation: Tokens can be invalidated by generating new ones, providing security rotation capabilities. No Expiration: Tokens don’t have built-in expiration but should be rotated periodically for security.

Using Embed Tokens

Once you have an embed token, use it with the embed system to integrate the Answering Agent dashboard into your application.

Getting Started

Guides

API Reference

API Playground

Overview

Base URL

Understanding External IDs

Key Concepts

1. List Users

Query Parameters

Example

2. Create User

Query Parameters

Request Body

Success Response

Error Codes

3. Get User by External ID

Example

4. Get User by Email

Example

5. Update User

Request Body

Success Response

6. Delete User

Example

Embed Token Management

Get Current Embed Token

Example

Generate New Embed Token

Example

Security Features

Using Embed Tokens

Getting Started

Guides

API Reference

API Playground

​Overview

​Base URL

​Understanding External IDs

​Key Concepts

​1. List Users

​Query Parameters

​Example

​2. Create User

​Query Parameters

​Request Body

​Success Response

​Error Codes

​3. Get User by External ID

​Example

​4. Get User by Email

​Example

​5. Update User

​Request Body

​Success Response

​6. Delete User

​Example

​Embed Token Management

​Get Current Embed Token

​Example

​Generate New Embed Token

​Example

​Security Features

​Using Embed Tokens

Overview

Base URL

Understanding External IDs

Key Concepts

1. List Users

Query Parameters

Example

2. Create User

Query Parameters

Request Body

Success Response

Error Codes

3. Get User by External ID

Example

4. Get User by Email

Example

5. Update User

Request Body

Success Response

6. Delete User

Example

Embed Token Management

Get Current Embed Token

Example

Generate New Embed Token

Example

Security Features

Using Embed Tokens