User Creation + Management

Create a new user

post

Invite a user to the Amigo platform. The endpoint will create a new user in the organization, linked to the supplied email address. The created user will remain in the unverified status and will not have access to most of Amigo's services.

If login_link is not-None, an email containing it will be sent to the user's email with descriptions indicating that this would allow the user to login and start their Amigo experience. Otherwise, no email will be sent.

Permissions

This endpoint requires the following permissions:

• User:InviteUser on the user to invite.
• The authenticated user must have greater privileges than the role assigned to the new user.

Authorizations

Bearer-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-Key-Authorization-UserID

Path parameters

organizationstringRequired

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

or

nullOptional

Body

first_namestring · min: 1Required

The first name of the user.

last_namestring · min: 1Required

The last name of the user.

emailstring · emailRequired

The email of the user. This email uniquely identifies the user in the organization.

login_linkany ofOptional

If specified, this link will be sent to the user's email as the link to start their Amigo experience. For Amigo's frontend, this would be the user's organization's login page with their email already filled in.

string · uri · min: 1 · max: 2083Optional

or

nullOptional

role_namestringRequired

The role to assign to the user. Only roles that are returned from the Get roles endpoint are allowed.

user_preferencesany ofOptional

If specified, the user's preferences will be set to this value instead of the organization default.

or

nullOptional

Responses

201

Succeeded

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or role is not found.

409

User with the same email already exists in this organization.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 1000 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

HTTPcURLJavaScriptPython

POST /v1/{organization}/user/invite HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 310

{
  "first_name": "text",
  "last_name": "text",
  "email": "[e-mail]",
  "login_link": "https://example.com",
  "role_name": "text",
  "user_preferences": {
    "enable_response_recommendation": false,
    "preferred_language": "text",
    "conversations_visible_to_admins": true,
    "user_model_visible_to_admins": true,
    "timezone": "Africa/Abidjan"
  }
}

{
  "user_id": "text",
  "verify_link": "text"
}

Important Configuration Notes

• User Preferences: The settings shown above are recommended for integrations

• Role Assignment: Use DefaultUserRole unless specific custom roles are required

• Custom Roles: Contact the Amigo team if custom role definitions are needed

• Timezone: The timezone field in user preferences (found within the user_preferences object in the request body for user creation, or directly in the request body for user updates) sets the user's timezone using IANA tz database format (e.g., "America/New_York"). This is crucial as it affects how the Amigo agent perceives time for the user, including interpreting timestamps for events and understanding time-related queries (e.g., "morning" vs. "night"). If not specified, the organization's default timezone is used, or UTC if the organization's default is not set.

Get all users

Get users subject to filters as follows:

Get users

get

Retrieve all users in an organization.

Permissions

This endpoint is impacted by the following permissions:

• Only users that the authenticated user has the User:GetUserInfo permission for are returned.

Authorizations

Bearer-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-Key-Authorization-UserID

Path parameters

organizationstringRequired

Query parameters

is_verifiedany ofOptional

Whether the user is verified.

booleanOptional

or

nullOptional

user_idany ofOptional

The ID of the user.

string[]Optional

or

nullOptional

emailany ofOptional

The email of the user,

string · email[]Optional

or

nullOptional

limitinteger · max: 100Optional

The maximum number of users to retrieve.

Default: 100

continuation_tokenintegerOptional

The token from the previous request to return the next page of users.

Default: 0

sort_bystring[]Optional

The fields to sort the users by. Supported fields are first_name, last_name, email, user_stats.num_conversations, and user_stats.num_messages. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.

Default: []

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

or

nullOptional

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization is not found.

422

Invalid request path parameter or request query parameter failed validation.

429

The user has exceeded the rate limit of 60 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get

HTTPcURLJavaScriptPython

GET /v1/{organization}/user/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*

{
  "users": [
    {
      "org_id": "text",
      "user_id": "text",
      "first_name": "text",
      "last_name": "text",
      "email": "text",
      "user_stats": {
        "num_conversations": 1,
        "num_messages": 1,
        "last_message_time": "2025-05-20T22:10:21.561Z"
      },
      "verified_at": "2025-05-20T22:10:21.561Z",
      "role": "text",
      "preferences": {
        "enable_response_recommendation": false,
        "preferred_language": "text",
        "conversations_visible_to_admins": true,
        "user_model_visible_to_admins": true,
        "timezone": "text"
      }
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Updating a User

Update a user's details as follows:

curl --request POST \
     --url "https://api.amigo.ai/v1/<YOUR-ORG-ID>/user/<USER-ID>/user" \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
  "first_name": "Joe",
  "last_name": "Smith",
  "enable_response_recommendation": true,
  "preferred_language": {},
  "conversations_visible_to_admins": true,
  "timezone": "America/Los_Angeles"
}'

Update user info

post

Update information about an user. Only fields that are specified in the request are updated.

Permissions

This endpoint requires the following permissions:

• User:UpdateUserInfo for the user to update.

Authorizations

Bearer-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-Key-Authorization-UserID

Path parameters

organizationstringRequired

requested_user_idstringRequired

The identifier of the user to update information for.

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

or

nullOptional

Body

first_nameany ofOptional

The first name of the user to update. If null, the first name is not modified.

string · min: 1Optional

or

nullOptional

last_nameany ofOptional

The last name of the user to update. If null, the last name is not modified.

string · min: 1Optional

or

nullOptional

enable_response_recommendationany ofOptional

Whether to automatically recommend responses to the user if the user hasn't replied to the coach for a while. If null, the preference is not modified.

booleanOptional

or

nullOptional

preferred_languageany ofOptional

The preferred language for the user. The agent will attempt to converse to the user in this language if set. This field must be in the ISO 639-1 alpha-2 format. If null, erase the user's preferred setting, and the specific language used will be the agent's default spoken language. In order to not update this field, leave it out of the request or set it to an empty object (_NotSet).

Default: {}

stringOptionalPattern: ^\w{2}$

or

object · _NotSetOptional

A specific type to indicate that a field is not set in the request.

or

nullOptional

timezoneany ofOptional

The user's timezone in the IANA tz database format. If not specified, the organization's timezone is used.

Default: {}

string · enum · min: 1OptionalPossible values:

or

object · _NotSetOptional

A specific type to indicate that a field is not set in the request.

or

nullOptional

conversations_visible_to_adminsany ofOptional

Whether conversations are visible to the admins. If null, the preference is not modified.

booleanOptional

or

nullOptional

user_model_visible_to_adminsany ofOptional

Whether the user's user model is visible to the admins. If null, the preference is not modified.

booleanOptional

or

nullOptional

additional_contextany ofOptional

A list of additional context to update. If null, the context is not modified.

string[]Optional

or

nullOptional

Responses

204

Succeeded.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or user is not found.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 100 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

HTTPcURLJavaScriptPython

POST /v1/{organization}/user/{requested_user_id}/user HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 239

{
  "first_name": "text",
  "last_name": "text",
  "enable_response_recommendation": true,
  "preferred_language": "text",
  "timezone": "Africa/Abidjan",
  "conversations_visible_to_admins": true,
  "user_model_visible_to_admins": true,
  "additional_context": [
    "text"
  ]
}

No content

Deleting a User

Delete a user with a given user ID as follows:

curl --request DELETE \
     --url "https://api.amigo.ai/v1/<YOUR-ORG-ID>/user/<USER-ID>" \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-AN-ADMIN>' \
     --header 'Accept: application/json'

A 200 response means the user was deleted. However, internally the deletion may be either implemented as a hard or soft delete. A soft delete is reflected by a non-emptynot_deletable_reasons array in the response.

Delete an user

delete

Delete an user. This endpoint deletes the user from the Amigo system, and also deletes all the user's information as much as possible.

• If the user has created an API key, the user's data in Amigo's database are deleted, except for the User object, which is marked deleted. The Google user is deleted as well.
• Otherwise the user is completely deleted. Their associated Google user is also deleted.

Permissions

This endpoint requires the following permissions:

• User.DeleteUser on the user to delete.

Authorizations

Bearer-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-Key-Authorization-UserID

Path parameters

organizationstringRequired

requested_user_idstringRequired

The identifier of the user to delete.

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

or

nullOptional

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or user is not found.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 1000 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

delete

HTTPcURLJavaScriptPython

DELETE /v1/{organization}/user/{requested_user_id} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*

{
  "not_deletable_reasons": [
    "There are API keys created by the user."
  ]
}

User Management Best Practices

1. User ID Mapping: Save the returned user_id and map it to your internal user management system

2. Auth Token Management: Generate and manage auth tokens for each user as needed

3. User State Tracking: Maintain user state in your system to provide seamless experiences

User Model Management

Data Retrieval + User Model Management