EndUserRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/ada/main/json-schema/ada-end-user-request-schema.json",
  "title": "EndUserRequest",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ada-end-users-api-openapi.yml#/components/schemas/EndUserRequest",
  "type": "object",
  "properties": {
    "external_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "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)."
    },
    "profile": {
      "$ref": "#/$defs/EndUserRequestProfile",
      "description": "The end user's profile information"
    }
  },
  "required": [
    "profile"
  ],
  "$defs": {
    "EndUserRequestProfile": {
      "type": "object",
      "properties": {
        "first_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The end user's first name"
        },
        "last_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The end user's last name"
        },
        "display_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The end user's display name"
        },
        "avatar": {
          "type": [
            "string",
            "null"
          ],
          "description": "URL to the end user's avatar image"
        },
        "email": {
          "type": [
            "string",
            "null"
          ],
          "description": "The end user's email address"
        },
        "language": {
          "type": [
            "string",
            "null"
          ],
          "description": "The end user's language in BCP 47 format"
        },
        "metadata": {
          "type": [
            "object",
            "null"
          ],
          "additionalProperties": {
            "description": "Any type"
          },
          "description": "A dictionary of arbitrary key, value pairs assigned to the end user.\n<br>- `metadata` keys may only be of type: `string`\n<br>- `metadata` values may only be one of type: `string`, `boolean`, or `integer`\n<br>**Note**: The total size of metadata is limited to 10KB.</br>\n"
        },
        "sensitive_metadata": {
          "oneOf": [
            {
              "$ref": "#/$defs/EndUserRequestProfileSensitiveMetadata"
            },
            {
              "type": "null"
            }
          ],
          "description": "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."
        }
      },
      "description": "The end user's profile information",
      "title": "EndUserRequestProfile"
    },
    "EndUserRequestProfileSensitiveMetadata": {
      "type": "object",
      "properties": {
        "fields": {
          "type": "object",
          "additionalProperties": {
            "oneOf": [
              {
                "$ref": "#/$defs/EndUserRequestProfileSensitiveMetadataFields"
              },
              {
                "type": "null"
              }
            ]
          },
          "description": "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."
        }
      },
      "required": [
        "fields"
      ],
      "description": "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.",
      "title": "EndUserRequestProfileSensitiveMetadata"
    },
    "EndUserRequestProfileSensitiveMetadataFields": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "boolean"
        },
        {
          "type": "integer"
        }
      ],
      "title": "EndUserRequestProfileSensitiveMetadataFields"
    }
  }
}