End Users API

The End Users API allows you to create, update, and manage your end users’ data in real time. It also comes with webhook events you can subscribe to so you can keep track of changes to user profiles in Ada.

This API allows integrators to:

• Create end users with context before a conversation starts. Use POST /v2/end-users/ to set language, metadata, and sensitive metadata before calling POST /v2/conversations/. The AI Agent has full user context from the first turn.
• Programmatically sync user details from external systems with Ada using webhooks so that Action and Knowledge rules apply to those users.
• Get notified at your webhook endpoint when Ada users are created or updated through the API.
• Update metavariables using request blocks or Actions.
  • The end_user_id is a variable that will fill in this part of the URL programmatically for requests or actions (so you don’t have to consume webhooks unless needed).
• Pass sensitive metadata securely. Use the sensitive_metadata field to provide auth tokens, session IDs, or personally identifiable information through an encrypted, write-only pathway.

Channel eligibility

For native chat, the Chat SDK provides setMetaFields() and setSensitiveMetaFields() as the primary path. For social and email channels, PATCH /v2/end-users/:id with sensitive_metadata is the only API pathway for passing sensitive values.

For end-to-end integration patterns, see the developer guide.

User profile structure

The End User Profile entity is represented as a JSON object composed of key,value pairs. Each key in the End User object represents a metavariable you can use throughout Ada. Learn more about metavariables.

You can use the profile.metadata object to create a custom mapping of key, value pairs to reflect your company’s data schema. All values must be strings, integers, or booleans.

The system_properties object includes select keys automatically created by Ada, and is read-only. Note that depending on your Ada configuration, not all keys defined in the End Users API specification may be present or may have values.

Sensitive metadata

The sensitive_metadata field is available on both POST /v2/end-users/ and PATCH /v2/end-users/:id. It provides a secure pathway for passing values that should not be stored in standard metadata.

Sensitive metadata values are:

• Encrypted at rest in Ada’s storage layer
• Redacted from the dashboard and not visible to operators
• Excluded from LLM context and never sent to the AI model
• TTL-bound and automatically deleted after 24 hours
• Write-only and never returned in API responses (GET or PATCH)

This matches the security contract of the Chat SDK’s setSensitiveMetaFields().

Use sensitive_metadata for auth tokens, session IDs, and personally identifiable information. Use standard metadata for non-sensitive context like region and plan type.

Additional constraints:

• Maximum 20 key-value pairs per request.
• On PATCH, keys must match the pattern [A-Za-z0-9_-]+.
• On POST, sensitive metadata keys must not overlap with keys in the sibling metadata field.

The sensitive_metadata field is nested inside profile and contains a fields object. To remove a sensitive metavariable, set the key to null:

1
{
2
  "profile": {
3
    "sensitive_metadata": {
4
      "fields": {
5
        "auth_token": null
6
      }
7
    }
8
  }
9
}

Webhook support

Ada uses webhook events to keep your systems in sync. These events allow your systems to track and react to key moments related to specific user actions and updates. The following events are supported:

• v1.end_user.created: Triggered when a new user is created through any of Ada’s supported channels, including explicit creation via POST /v2/end-users/. The AI Agent’s customer persistence setting influences the rate of these events.
• v1.end_user.updated: Triggered when a value on the end user’s profile changes. Updates may occur via:
  • API calls (e.g., PATCH requests to the End Users API).
  • Updates through Ada-supported channels (e.g., setMetafields on embeds).
  • Profile field mappings from Sunshine Conversations.

For implementation details, see the webhook documentation.

Changes that do not trigger events

Certain updates do not generate end_user.updated events:

• Changes to system.properties.
• Modifications to metavariables like:
  • ip_address
  • user_agent
  • browser
  • device
  • last_answer_id
  • channel_status
• Changes to sensitive_metadata (write-only values do not trigger update events).

For more details on how to implement and use webhooks, refer to the webhook documentation.

Rate limits

All /v2/end-users/<end_user_id> endpoints adhere to these rate limits:

• Requests per day: 60,000
• Requests per minute: 300
• Requests per second: 30

All other End Users API endpoints adhere to our global rate limits.