User Creation + Management

Understanding Subscription Requirements

All Amigo users must be associated with a subscription plan. For integration:

1. Each user requires a valid subscription plan assignment

2. The "Internal Lifetime Plan" is recommended for your users

Retrieving Available Subscription Plans

First, retrieve the list of available subscription plans using the auth token of an admin:

Get subscription plans

get

Retrieve all subscription plans satisfying the given filters. Only the latest version of each plan is returned.

Permissions

This endpoint requires the following permissions:

• User:GetUserInfo on the authenticated user.

Authorizations

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

Path parameters

organizationstringrequired

Query parameters

accepted_sourceany ofoptional

The source of the subscription plan

accepts_new_customersany ofoptional

Whether the plan still accepts new customers

idany ofoptional

The ids of the plans to fetch

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.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.amigo.ai/v1/{organization}/subscription_plan/' \
  --header 'Authorization: Bearer JWT'

200

401

403

404

422

429

503

200

{
  "plans": [
    {
      "id": "text",
      "external_name": "text",
      "unit_price_cents": 1,
      "charge_scheme": {
        "scheme": "text",
        "conversation_allowance": 1
      },
      "created_at": "2025-04-03T20:52:13.243Z"
    }
  ]
}

Succeeded.

From the response, locate and record the id of the "Internal Lifetime Plan" for use in user creation:

// Sample response for GET subscription plans
{
    "plans": [
        {
            "id": "67576eeb7584004d888cfdcd", <------ use this id in next steps
            "external_name": "Internal Lifetime Plan", <------ relevant plan
            "unit_price_cents": 0,
            "created_at": "2024-12-09T22:27:55.785000Z",
            "charge_scheme": {
                "scheme": "lifetime"
            }
        }
    ]
}

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.GetUserInfo for the authenticated user.
• 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.

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.

subscription_plan_idany ofoptional

The ID of the subscription plan to be assigned to the user. This cannot be a subscription plan that accepts Stripe checkouts. The plan will be pending until the user clicks the invite link.

subscription_plan_num_unitsany ofoptional

Must be set if subscription_plan_id is set. If the plan is lifetime or usage-based, this field is always 1. If the plan is period-based, the number of plan-units to enable for the user. For instance, if the plan is a monthly one and this field is 6, then the user would receive 6 months of the plan.

subscription_metadataobjectoptional

Additional metadata to be attached to the subscription if subscription_plan_id is defined. It must be a JSON-serializable map.

Default: {}

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.

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.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.amigo.ai/v1/{organization}/user/invite' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "text",
    "last_name": "text",
    "email": "[e-mail]",
    "subscription_plan_id": "text",
    "subscription_plan_num_units": 1,
    "subscription_metadata": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "login_link": "https://example.com",
    "role_name": "text",
    "user_preferences": {
      "enable_response_recommendation": true,
      "preferred_language": "text",
      "conversations_visible_to_admins": true,
      "user_model_visible_to_admins": true
    }
  }'

201

400

401

403

404

409

422

429

503

201

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

Succeeded

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

User Verification

After creating a user, you must verify the account:

curl --request POST \
     --url "https://api.amigo.ai/v1/<YOUR-ORG-ID>/user/<CREATED-USER-ID>/verify" \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{}'

Verify a user

post

Mark the user as verified. It's not permitted to use the Amigo platform with an unverified user account.

Permissions:

This endpoint requires the following permissions:

• User:GetUserInfo for the authenticated user.

This endpoint may require the following permissions:

• User.UpdateUserInfo for the requested user if any field in Request is not None.

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 verify.

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.

Body

first_nameany ofoptional

The first name of the user, if the user has a different preference than what's already indicated during invitation. Only updated if specified.

last_nameany ofoptional

The last name of the user, if the user has a different preference than what's already indicated during invitation. Only updated if specified.

user_preferencesany ofoptional

The preferences of the user, if the user has a different preference than what's already indicated during invitation. Only updated if specified.

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.amigo.ai/v1/{organization}/user/{requested_user_id}/verify' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "text",
    "last_name": "text",
    "user_preferences": {
      "enable_response_recommendation": true,
      "preferred_language": "text",
      "conversations_visible_to_admins": true,
      "user_model_visible_to_admins": true
    }
  }'

204

401

403

404

409

422

429

503

204

No body

Succeeded.

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
}'

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:GetUserInfo for the authenticated user.
• 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.

Body

first_nameany ofoptional

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

last_nameany ofoptional

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

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.

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: {}

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

conversations_visible_to_adminsany ofoptional

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

user_model_visible_to_adminsany ofoptional

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

additional_contextany ofoptional

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

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.amigo.ai/v1/{organization}/user/{requested_user_id}/user' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "text",
    "last_name": "text",
    "enable_response_recommendation": true,
    "preferred_language": "text",
    "conversations_visible_to_admins": true,
    "user_model_visible_to_admins": true,
    "additional_context": [
      "text"
    ]
  }'

204

401

403

404

422

429

503

204

No body

Succeeded.

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 gone through any Stripe payment flow, the user's data in Amigo's database are deleted, except for the User object, which is marked deleted. The Google user is deleted, but the Stripe user is kept for compliance.
• Otherwise the user is completely deleted. Their associated Google user and Stripe user is also deleted.

Permissions

This endpoint requires the following permissions:

• User.GetUserInfo on the authenticated user.
• 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.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://api.amigo.ai/v1/{organization}/user/{requested_user_id}' \
  --header 'Authorization: Bearer JWT'

200

400

401

403

404

422

429

503

200

{
  "not_deletable_reasons": [
    "User has past billing events."
  ]
}

Succeeded.

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