> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/reference/end-users/patch-end-user-by-id/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Update an end user PATCH https://example.ada.support/api/v2/end-users/{end_user_id} Content-Type: application/json Update a specific end user by id Reference: https://docs.ada.cx/reference/end-users/patch-end-user-by-id ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `end_user_id` (string, required) — The Ada end_user_id ### Body (application/json) This endpoint expects an EndUserRequest. - `profile` (EndUserRequestProfile, required) — The end user's profile information - `external_id` (string, optional, nullable) — Set or update the external identifier for this end user. Pass null to remove the current external\_id. Must be unique per AI Agent; maximum 36 characters; must not contain \< or > characters. Values are stored case-insensitively. Returns 409 if the external\_id is already assigned to a different end user. Available for custom channel integrations only (V1). ## Response ### 200 OK - `end_user_id` (string, optional) — The unique Ada-generated id for the end user - `external_id` (string, optional, nullable) — 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). - `profile` (EndUserProfile, optional) — The end user's profile information - `created_at` (string, optional) — The date and time the end user was created - `updated_at` (string, optional) — The date and time the end user was updated ## Errors ### 400 Bad Request Error Invalid request - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 401 Unauthorized Error Unauthorized - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 404 Not Found Error Not Found - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 409 Conflict Error Conflict — the requested external_id is already assigned to a different end user on this AI Agent. - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 429 Too Many Requests Error Too Many Requests - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 500 Internal Server Error Internal Server Error - `errors` (list of ErrorsErrorsItems, required) — A list of errors ## Types ### EndUserRequestProfile The end user's profile information - `first_name` (string, optional, nullable) — The end user's first name - `last_name` (string, optional, nullable) — The end user's last name - `display_name` (string, optional, nullable) — The end user's display name - `avatar` (string, optional, nullable) — URL to the end user's avatar image - `email` (string, optional, nullable) — The end user's email address - `language` (string, optional, nullable) — The end user's language in BCP 47 format - `metadata` (map from string to any, optional, nullable) — A dictionary of arbitrary key, value pairs assigned to the end user. \- `metadata` keys may only be of type: `string` \- `metadata` values may only be one of type: `string`, `boolean`, or `integer` **Note**: The total size of metadata is limited to 10KB. - `sensitive_metadata` (EndUserRequestProfileSensitiveMetadata, optional, nullable) — Sensitive key-value pairs to update on the end user. Values are stored in an encrypted, isolated store and are never returned in any API response, dashboard view, conversation transcript, or LLM prompt. Values are automatically and permanently deleted after 24 hours. ### EndUserProfile The end user's profile information - `first_name` (string, optional, nullable) — The end user's first name - `last_name` (string, optional, nullable) — The end user's last name - `display_name` (string, optional, nullable) — The end user's display name - `avatar` (string, optional, nullable) — URL to the end user's avatar image - `email` (string, optional, nullable) — The end user's email address - `language` (string, optional, nullable) — The end user's language in BCP 47 format - `metadata` (map from string to any, optional) — A dictionary of arbitrary key, value pairs assigned to the end user - `metadata` keys may only be of type: `string` - `metadata` values may only be one of type: `string`, `boolean`, or `integer` - `system_properties` (EndUserProfileSystemProperties, optional) — Read-only profile information set by Ada ### ErrorsErrorsItems - `type` (string, required) — The error type - `message` (string, required) — The error message - `details` (string, optional, nullable) — Extra information about the error ### EndUserRequestProfileSensitiveMetadata Sensitive key-value pairs to update on the end user. Values are stored in an encrypted, isolated store and are never returned in any API response, dashboard view, conversation transcript, or LLM prompt. Values are automatically and permanently deleted after 24 hours. - `fields` (map from string to EndUserRequestProfileSensitiveMetadataFields, required) — A dictionary of sensitive key-value pairs. Keys must match the pattern [A-Za-z0-9_-]+. Values must be non-empty strings, booleans, integers, or null. Setting a key to null removes the metavariable. Maximum 20 key-value pairs per request. ### EndUserProfileSystemProperties Read-only profile information set by Ada - `sunshine_user_id` (string, optional, nullable) — The Sunshine Conversations user id for the end user ### EndUserRequestProfileSensitiveMetadataFields ## Examples **Request** ```json { "profile": { "first_name": "Ada", "last_name": "Lovelace", "display_name": "Ada Lovelace", "avatar": "https://example.com/avatars/ada.png", "email": "ada.lovelace@ada.cx", "language": "en-US", "metadata": { "example_key1": "example_string_value", "example_key2": true, "example_key3": 123 }, "sensitive_metadata": { "fields": { "auth_token": "eyJhbGciOiJIUzI1NiIs...", "session_id": "sess_abc123" } } } } ``` **Response** ```json { "end_user_id": "5f7e0e2c1e7c7e000f0f9c3a", "profile": { "first_name": "Ada", "last_name": "Lovelace", "display_name": "Ada Lovelace", "avatar": "https://example.com/avatars/ada.png", "email": "ada.lovelace@ada.cx", "language": "en-US", "metadata": { "example_key1": "example_string_value", "example_key2": true, "example_key3": 123 }, "system_properties": { "sunshine_user_id": "5f7e0e2c1e7c7e000f0f9c3a" } }, "created_at": "2020-09-20T00:00:00+00:00", "updated_at": "2020-09-20T00:00:00+00:00" } ``` **SDK Code** ```python import requests url = "https://example.ada.support/api/v2/end-users/end_user_id" payload = { "profile": { "first_name": "Ada", "last_name": "Lovelace", "display_name": "Ada Lovelace", "avatar": "https://example.com/avatars/ada.png", "email": "ada.lovelace@ada.cx", "language": "en-US", "metadata": { "example_key1": "example_string_value", "example_key2": True, "example_key3": 123 }, "sensitive_metadata": { "fields": { "auth_token": "eyJhbGciOiJIUzI1NiIs...", "session_id": "sess_abc123" } } } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://example.ada.support/api/v2/end-users/end_user_id'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"profile":{"first_name":"Ada","last_name":"Lovelace","display_name":"Ada Lovelace","avatar":"https://example.com/avatars/ada.png","email":"ada.lovelace@ada.cx","language":"en-US","metadata":{"example_key1":"example_string_value","example_key2":true,"example_key3":123},"sensitive_metadata":{"fields":{"auth_token":"eyJhbGciOiJIUzI1NiIs...","session_id":"sess_abc123"}}}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://example.ada.support/api/v2/end-users/end_user_id" payload := strings.NewReader("{\n \"profile\": {\n \"first_name\": \"Ada\",\n \"last_name\": \"Lovelace\",\n \"display_name\": \"Ada Lovelace\",\n \"avatar\": \"https://example.com/avatars/ada.png\",\n \"email\": \"ada.lovelace@ada.cx\",\n \"language\": \"en-US\",\n \"metadata\": {\n \"example_key1\": \"example_string_value\",\n \"example_key2\": true,\n \"example_key3\": 123\n },\n \"sensitive_metadata\": {\n \"fields\": {\n \"auth_token\": \"eyJhbGciOiJIUzI1NiIs...\",\n \"session_id\": \"sess_abc123\"\n }\n }\n }\n}") req, _ := http.NewRequest("PATCH", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://example.ada.support/api/v2/end-users/end_user_id") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Patch.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"profile\": {\n \"first_name\": \"Ada\",\n \"last_name\": \"Lovelace\",\n \"display_name\": \"Ada Lovelace\",\n \"avatar\": \"https://example.com/avatars/ada.png\",\n \"email\": \"ada.lovelace@ada.cx\",\n \"language\": \"en-US\",\n \"metadata\": {\n \"example_key1\": \"example_string_value\",\n \"example_key2\": true,\n \"example_key3\": 123\n },\n \"sensitive_metadata\": {\n \"fields\": {\n \"auth_token\": \"eyJhbGciOiJIUzI1NiIs...\",\n \"session_id\": \"sess_abc123\"\n }\n }\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.patch("https://example.ada.support/api/v2/end-users/end_user_id") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"profile\": {\n \"first_name\": \"Ada\",\n \"last_name\": \"Lovelace\",\n \"display_name\": \"Ada Lovelace\",\n \"avatar\": \"https://example.com/avatars/ada.png\",\n \"email\": \"ada.lovelace@ada.cx\",\n \"language\": \"en-US\",\n \"metadata\": {\n \"example_key1\": \"example_string_value\",\n \"example_key2\": true,\n \"example_key3\": 123\n },\n \"sensitive_metadata\": {\n \"fields\": {\n \"auth_token\": \"eyJhbGciOiJIUzI1NiIs...\",\n \"session_id\": \"sess_abc123\"\n }\n }\n }\n}") .asString(); ``` ```php request('PATCH', 'https://example.ada.support/api/v2/end-users/end_user_id', [ 'body' => '{ "profile": { "first_name": "Ada", "last_name": "Lovelace", "display_name": "Ada Lovelace", "avatar": "https://example.com/avatars/ada.png", "email": "ada.lovelace@ada.cx", "language": "en-US", "metadata": { "example_key1": "example_string_value", "example_key2": true, "example_key3": 123 }, "sensitive_metadata": { "fields": { "auth_token": "eyJhbGciOiJIUzI1NiIs...", "session_id": "sess_abc123" } } } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://example.ada.support/api/v2/end-users/end_user_id"); var request = new RestRequest(Method.PATCH); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"profile\": {\n \"first_name\": \"Ada\",\n \"last_name\": \"Lovelace\",\n \"display_name\": \"Ada Lovelace\",\n \"avatar\": \"https://example.com/avatars/ada.png\",\n \"email\": \"ada.lovelace@ada.cx\",\n \"language\": \"en-US\",\n \"metadata\": {\n \"example_key1\": \"example_string_value\",\n \"example_key2\": true,\n \"example_key3\": 123\n },\n \"sensitive_metadata\": {\n \"fields\": {\n \"auth_token\": \"eyJhbGciOiJIUzI1NiIs...\",\n \"session_id\": \"sess_abc123\"\n }\n }\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["profile": [ "first_name": "Ada", "last_name": "Lovelace", "display_name": "Ada Lovelace", "avatar": "https://example.com/avatars/ada.png", "email": "ada.lovelace@ada.cx", "language": "en-US", "metadata": [ "example_key1": "example_string_value", "example_key2": true, "example_key3": 123 ], "sensitive_metadata": ["fields": [ "auth_token": "eyJhbGciOiJIUzI1NiIs...", "session_id": "sess_abc123" ]] ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://example.ada.support/api/v2/end-users/end_user_id")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PATCH" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```