Create an end user

Create a new end user with optional profile data and sensitive metadata. Use this endpoint to establish an end user with context (language, metadata, sensitive metadata) before starting a conversation via POST /v2/conversations/. This ensures the AI Agent has full user context from the first turn. Available for custom channel (Conversations API) integrations. End users created through this endpoint that are not associated with a conversation within 24 hours of creation are automatically deleted.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

external_idstring or nullOptional<=36 characters

Optional caller-supplied identifier (for example a CRM contact ID or a phone number). Maximum 36 characters; must not contain < or > characters. Values are stored case-insensitively. If an end user with this external_id already exists, that existing user is returned with HTTP 200 (idempotent upsert); otherwise a new end user is created with HTTP 201. Available for custom channel integrations only (V1).

profileobjectOptional

The end user’s profile information. Optional — omitting profile creates a blank end user.

Response

Existing end user returned. Issued when the request includes an external_id that is already mapped to an end user on the same AI Agent (idempotent upsert).

end_user_idstringRead-only

The unique Ada-generated id for the end user

external_idstring or nullRead-only

Caller-supplied identifier that links this end user to your own system (for example a CRM contact ID or a phone number). Unique per AI Agent. Null if not set. Maximum 36 characters; values are case-insensitive. Available for custom channel integrations only (V1).

profileobject

The end user's profile information

created_atstringRead-only

The date and time the end user was created

updated_atstringRead-only

The date and time the end user was updated

Errors

400

Bad Request Error

401

Unauthorized Error

413

Content Too Large Error

429

Too Many Requests Error

500

Internal Server Error

1	import requests
2
3	url = "https://example.ada.support/api/v2/end-users/"
4
5	payload = { "profile": {
6	"first_name": "Maria",
7	"last_name": "Santos",
8	"email": "maria@example.com",
9	"language": "pt-BR",
10	"metadata": {
11	"region": "latam",
12	"plan_type": "enterprise"
13	},
14	"sensitive_metadata": { "fields": {
15	"auth_token": "eyJhbGciOiJIUzI1NiIs...",
16	"session_id": "sess_abc123"
17	} }
18	} }
19	headers = {
20	"Authorization": "Bearer <token>",
21	"Content-Type": "application/json"
22	}
23
24	response = requests.post(url, json=payload, headers=headers)
25
26	print(response.json())

1	{
2	"end_user_id": "5f7e0e2c1e7c7e000f0f9c3a",
3	"profile": {
4	"first_name": "Ada",
5	"last_name": "Lovelace",
6	"display_name": "Ada Lovelace",
7	"avatar": "https://example.com/avatars/ada.png",
8	"email": "ada.lovelace@ada.cx",
9	"language": "en-US",
10	"metadata": {
11	"example_key1": "example_string_value",
12	"example_key2": true,
13	"example_key3": 123
14	},
15	"system_properties": {
16	"sunshine_user_id": "5f7e0e2c1e7c7e000f0f9c3a"
17	}
18	},
19	"created_at": "2020-09-20T00:00:00+00:00",
20	"updated_at": "2020-09-20T00:00:00+00:00"
21	}