openapi: 3.0.3
info:
  title: Tealium Authentication Auth Privacy API
  description: Provides JWT bearer token generation for Tealium v3 APIs. Exchange a username (email address) and API key for a time-limited JWT bearer token used to authenticate all other Tealium v3 API calls. Tokens are valid for 30 minutes. The response also includes a region-specific host for subsequent API calls. API keys are obtained from Tealium iQ Tag Management and are not used directly in API calls — only for token generation.
  version: '3.0'
  contact:
    name: Tealium Support
    url: https://docs.tealium.com/api/v3/getting-started/authentication/
servers:
- url: https://platform.tealiumapis.com/v3
  description: Tealium platform API base URL
tags:
- name: Privacy
paths:
  /privacy/visitor/accounts/{account}/profiles/{profile}:
    get:
      operationId: getPrivacyVisitor
      summary: Retrieve visitor data (GDPR/CCPA lookup)
      description: Retrieves all known data about a specific visitor for GDPR/CCPA compliance purposes. Returns the full visitor profile record including all attributes, audience memberships, and badges.
      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 a 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; false returns numeric IDs
      responses:
        '200':
          description: Visitor data returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisitorPrivacyProfile'
        '400':
          description: Bad request — missing attributeId or attributeValue
        '401':
          description: Unauthorized — invalid or expired bearer token
        '404':
          description: Visitor not found
      tags:
      - Privacy
    delete:
      operationId: deletePrivacyVisitor
      summary: Delete visitor data (GDPR/CCPA erasure)
      description: Submits a deletion request for a visitor's profile data from the Customer Data Hub. Deletion is asynchronous and completes within 30 days. Returns a transactionId for tracking request status.
      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
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - attributeId
              - attributeValue
              properties:
                attributeId:
                  type: integer
                  description: Numeric ID of the Visitor ID attribute
                attributeValue:
                  type: string
                  description: Value identifying the visitor to delete
      responses:
        '200':
          description: Deletion request submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletionResponse'
              example:
                transactionId: txn_abc123xyz
        '400':
          description: Bad request — missing attributeId or attributeValue
        '401':
          description: Unauthorized
        '429':
          description: Too many requests — rate limit exceeded (50 req/s)
      tags:
      - Privacy
  /privacy/visitor/accounts/{account}/profiles/{profile}/transactions/{transaction_id}:
    get:
      operationId: getDeleteTransactionStatus
      summary: Check deletion transaction status
      description: Retrieves the status of a previously submitted visitor deletion request. Returns PENDING, SUCCESS, or FAILED for the given transaction ID.
      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: transaction_id
        in: path
        required: true
        schema:
          type: string
        description: Transaction ID returned from the DELETE visitor request
      responses:
        '200':
          description: Transaction status returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionStatusResponse'
              example:
                txn_abc123xyz: PENDING
        '401':
          description: Unauthorized
        '404':
          description: Transaction not found
      tags:
      - Privacy
  /privacy/visitor/accounts/{account}/profiles/{profile}/ids:
    get:
      operationId: getVisitorIdAttributes
      summary: List visitor ID attributes
      description: Returns all Visitor ID attributes configured for the specified account and profile, mapping numeric attribute IDs to their names. Used to discover valid attributeId values for privacy lookups.
      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
      responses:
        '200':
          description: Visitor ID attributes returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisitorIdAttributesResponse'
              example:
                '101': email_address
                '102': customer_id
                '103': phone_number
        '401':
          description: Unauthorized
      tags:
      - Privacy
components:
  schemas:
    TransactionStatusResponse:
      type: object
      description: Maps transaction ID to current status. Key is the transactionId, value is PENDING, SUCCESS, or FAILED.
      additionalProperties:
        type: string
        enum:
        - PENDING
        - SUCCESS
        - FAILED
    VisitorIdAttributesResponse:
      type: object
      description: Maps numeric attribute IDs to attribute names
      additionalProperties:
        type: string
    DeletionResponse:
      type: object
      description: Response from a successful visitor deletion request
      required:
      - transactionId
      properties:
        transactionId:
          type: string
          description: Unique identifier for tracking the deletion request
    VisitorPrivacyProfile:
      type: object
      description: Full visitor profile returned for privacy compliance purposes
      properties:
        audiences:
          type: object
          additionalProperties:
            type: boolean
        badges:
          type: object
          additionalProperties:
            type: boolean
        attributes:
          type: object
          additionalProperties: {}