Tealium Customer API

openapi: 3.2.0
info:
  title: Tealium Visitor Profile Customer API
  description: Queries full visitor profile records from the AudienceStream Customer Data Hub, returning audience memberships, badges, and attribute values for a given visitor. Used to retrieve the complete live or historical profile of a known or anonymous visitor identified by account, profile, and visitor ID attribute. Authenticates via JWT bearer token.
  version: '3.0'
  contact:
    name: Tealium Support
    url: https://docs.tealium.com/api/v3/visitor-profile/endpoints/
servers:
- url: https://{host}/v3
  description: Region-specific host returned by authentication API
  variables:
    host:
      default: platform.tealiumapis.com
      description: Region-specific host from auth response
security:
- BearerAuth: []
tags:
- name: Customer
paths:
  /customer/visitor/accounts/{account}/profiles/{profile}:
    get:
      operationId: getVisitorProfile
      summary: Get visitor profile
      description: Retrieves the full visitor profile for a specific visitor identified by a Visitor ID attribute value. Supports live data, historical data, or both. Returns audience memberships, badges, and all configured attribute values. Maximum of 150 attribute IDs can be filtered per request.
      parameters:
      - name: account
        in: path
        required: true
        schema:
          type: string
        description: Tealium account name
      - name: profile
        in: path
        required: true
        schema:
          type: string
        description: Tealium profile name
      - name: attributeId
        in: query
        required: true
        schema:
          type: integer
        description: Numeric ID of the Visitor ID attribute
      - name: attributeValue
        in: query
        required: true
        schema:
          type: string
        description: Value to look up (URL-encode special characters)
      - name: prettyName
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: When true, returns user-friendly attribute names; when false, returns numeric IDs
      - name: searchPriority
        in: query
        required: false
        schema:
          type: string
        description: 'JSON array controlling search order. Defaults to ["live","historical"]. Options: ["live"], ["historical"], or ["live","historical"]'
        example: '["live","historical"]'
      - name: responseFilters
        in: query
        required: false
        schema:
          type: string
        description: JSON array of up to 150 attribute IDs to include in response. Omit to return all attributes.
        example: '[101,102,103]'
      responses:
        '200':
          description: Visitor profile returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisitorProfile'
        '400':
          description: Bad request — missing attributeId or attributeValue
        '401':
          description: Unauthorized — invalid or expired bearer token
        '404':
          description: Visitor not found or invalid searchPriority parameter
      tags:
      - Customer
  /customer/visitor/historical/accounts/{account}/profiles/{profile}:
    get:
      operationId: getHistoricalVisitorProfile
      summary: Get historical visitor profile
      description: Retrieves the historical visitor profile for a specific visitor. Searches historical data only (no live data). Historical data is available after a 30-minute waiting period. Maximum of 150 attribute IDs can be filtered per request. The searchPriority parameter is not available for this endpoint.
      parameters:
      - name: account
        in: path
        required: true
        schema:
          type: string
        description: Tealium account name
      - name: profile
        in: path
        required: true
        schema:
          type: string
        description: Tealium profile name
      - name: attributeId
        in: query
        required: true
        schema:
          type: integer
        description: Numeric ID of the Visitor ID attribute
      - name: attributeValue
        in: query
        required: true
        schema:
          type: string
        description: Value to look up (URL-encode special characters)
      - name: prettyName
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: When true, returns user-friendly attribute names
      - name: responseFilters
        in: query
        required: false
        schema:
          type: string
        description: JSON array of up to 150 attribute IDs to include in response
      responses:
        '200':
          description: Historical visitor profile returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisitorProfile'
        '400':
          description: Bad request — missing attributeId or attributeValue
        '401':
          description: Unauthorized
        '404':
          description: Visitor not found
      tags:
      - Customer
components:
  schemas:
    VisitorProfile:
      type: object
      description: Full visitor profile record from AudienceStream
      properties:
        audiences:
          type: object
          description: Audience memberships keyed by audience ID or name
          additionalProperties:
            type: boolean
        badges:
          type: object
          description: Badge memberships keyed by badge ID or name
          additionalProperties:
            type: boolean
        attributes:
          type: object
          description: Visitor attribute values keyed by attribute ID (numeric) or name (when prettyName=true)
          additionalProperties: {}
        currentVisit:
          type: object
          description: Visit-scoped attribute values for the current session
          additionalProperties: {}
        dates:
          type: object
          description: Date-type attribute values
          additionalProperties:
            type: string
            format: date-time
        metrics:
          type: object
          description: Metric-type attribute values
          additionalProperties:
            type: number
        properties:
          type: object
          description: Property-type attribute values
          additionalProperties:
            type: string
        flags:
          type: object
          description: Boolean flag attribute values
          additionalProperties:
            type: boolean
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT bearer token obtained from the Authentication API. Valid for 30 minutes. Reuse tokens rather than generating new ones per request.