Complete Field Reference

Complete reference for all context enhancement fields, including standard OpenRTB mappings and custom extensions.

Core Design Principles

1. OpenRTB Compatibility: Fully compatible with OpenRTB 2.6 standard 2. Extension-Based: Use OpenRTB's ext mechanism for custom fields 3. Privacy-First: No PII, only contextual and behavioral signals 4. Standard Fields First: Always use standard OpenRTB fields when available

Standard OpenRTB Field Mapping

Important: Always use standard OpenRTB fields when available. Only use custom extensions for data that has no standard representation.

Affinity AI Concept	OpenRTB Field	Notes
IAB Content Categories	site.cat or app.cat	Use IAB Content Taxonomy 2.0+
IAB Audience Segments	user.data[].segment[]	Required: Use IAB Audience Taxonomy
Keywords	site.keywords or app.keywords	Comma-separated
User Intent Category	user.ext.intent	Custom extension (no standard field exists)
Custom Interests	ext.aura.audience.interests	Custom extension (non-IAB interests)
Custom Behaviors	ext.aura.audience.behaviors	Custom extension (non-IAB behaviors)

Request Structure

Complete Request Example

{
  "id": "bid-req-20250104-001",
  "imp": [
    {
      "id": "imp-1",
      "native": { "request": "{\"native\":{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":80}}]}}" },
          { "w": 320, "h": 50 }
        ]
      }
    }
  ],
  "site": {
    "id": "site-123",
    "name": "AI Assistant Platform",
    "domain": "aiplatform.com",
    "cat": ["IAB19-30", "IAB19-18"],
    "keywords": "family activities,outdoor adventures,cooking,golf"
  },
  "user": {
    "data": [
      {
        "id": "iab-audience",
        "name": "IAB Audience Taxonomy",
        "segment": [{ "id": "355" }, { "id": "350" }, { "id": "356" }]
      }
    ]
  },
  "ext": {
    "aura": {
      "messageSequenceNumber": 3,
      "messageLength": 45,
      "isQuickReply": false,
      "userThinkTimeMs": 2500,
      "sessionDurationMs": 45000,
      "intent": {
        "value": "purchase_inquiry",
        "confidence": 0.85,
        "topics": ["family travel", "outdoor activities", "golf"],
        "signals": ["asked_about_options", "price_sensitive"]
      },
      "sentiment": {
        "value": "positive",
        "score": 0.8
      },
      "funnel": {
        "stage": "consideration",
        "progress": 0.6
      },
      "audience": {
        "interests": ["family_activities", "sports", "travel"],
        "behaviors": ["comparison_shopping"]
      }
    }
  }
}

Field Definitions

BidRequest.ext.aura

Root extension object containing all Affinity AI context enhancement fields.

Type: object
Required: No
Location: BidRequest.ext.aura

Conversation Metrics

messageSequenceNumber

Position of the current message in the conversation sequence.

Type: integer
Required: Yes
Range: 1 to N (1-indexed)
Location: BidRequest.ext.aura.messageSequenceNumber

Example:

{
  "messageSequenceNumber": 3
}

messageLength

Character count of the user's message.

Type: integer
Required: Yes
Range: 0 to N
Location: BidRequest.ext.aura.messageLength

Example:

{
  "messageLength": 45
}

isQuickReply

Whether the message was a quick reply (button/suggestion) or typed.

Type: boolean
Required: Yes
Location: BidRequest.ext.aura.isQuickReply

Example:

{
  "isQuickReply": false
}

userThinkTimeMs

Time in milliseconds between last assistant message and user response.

Type: integer
Required: No
Range: 0 to N
Location: BidRequest.ext.aura.userThinkTimeMs

Example:

{
  "userThinkTimeMs": 2500
}

sessionDurationMs

Total elapsed time in milliseconds since session start.

Type: integer
Required: Yes
Range: 0 to N
Location: BidRequest.ext.aura.sessionDurationMs

Example:

{
  "sessionDurationMs": 45000
}

Intent Object

BidRequest.ext.aura.intent

User intent classification and signals.

Type: object
Required: No
Location: BidRequest.ext.aura.intent

intent.value

Intent classification category.

Type: string
Required: Yes (if intent object present)
Values: purchase_inquiry, information_seeking, support_request, comparison, objection_handling
Location: BidRequest.ext.aura.intent.value

Example:

{
  "value": "purchase_inquiry"
}

intent.confidence

Confidence score for intent classification.

Type: number
Required: Yes (if intent object present)
Range: 0.0 to 1.0
Location: BidRequest.ext.aura.intent.confidence

Example:

{
  "confidence": 0.85
}

intent.topics

Identified topics from conversation.

Type: string[]
Required: Yes (if intent object present)
Location: BidRequest.ext.aura.intent.topics

Example:

{
  "topics": ["family travel", "outdoor activities", "golf"]
}

intent.signals

Behavioral signals detected in user interactions.

Type: string[]
Required: Yes (if intent object present)
Location: BidRequest.ext.aura.intent.signals

Example:

{
  "signals": ["asked_about_options", "price_sensitive"]
}

Sentiment Object

BidRequest.ext.aura.sentiment

User sentiment classification.

Type: object
Required: No
Location: BidRequest.ext.aura.sentiment

sentiment.value

Sentiment classification category.

Type: string
Required: Yes (if sentiment object present)
Values: positive, neutral, negative
Location: BidRequest.ext.aura.sentiment.value

Example:

{
  "value": "positive"
}

sentiment.score

Sentiment intensity score.

Type: number
Required: Yes (if sentiment object present)
Range: 0.0 to 1.0
Location: BidRequest.ext.aura.sentiment.score

Example:

{
  "score": 0.8
}

Funnel Object

BidRequest.ext.aura.funnel

User's position in the conversion funnel.

Type: object
Required: No
Location: BidRequest.ext.aura.funnel

funnel.stage

Funnel stage classification.

Type: string
Required: Yes (if funnel object present)
Values: awareness, consideration, intent, conversion
Location: BidRequest.ext.aura.funnel.stage

Example:

{
  "stage": "consideration"
}

funnel.progress

Progress within current funnel stage.

Type: number
Required: Yes (if funnel object present)
Range: 0.0 to 1.0
Location: BidRequest.ext.aura.funnel.progress

Example:

{
  "progress": 0.6
}

Audience Object

BidRequest.ext.aura.audience

Custom audience signals (non-IAB).

Type: object
Required: No
Location: BidRequest.ext.aura.audience

Note: IAB Audience Taxonomy segments should be passed via standard OpenRTB user.data[].segment[] field, not in this custom extension.

audience.interests

Custom interests identified (non-IAB).

Type: string[]
Required: No
Location: BidRequest.ext.aura.audience.interests

Example:

{
  "interests": ["family_activities", "sports", "travel"]
}

audience.behaviors

Custom behaviors identified (non-IAB).

Type: string[]
Required: No
Location: BidRequest.ext.aura.audience.behaviors

Example:

{
  "behaviors": ["comparison_shopping"]
}

Standard OpenRTB Fields

site.cat / app.cat

IAB Content Categories for the site or app.

Type: string[]
Required: No
Format: IAB Content Taxonomy 2.0+
Location: BidRequest.site.cat or BidRequest.app.cat

Example:

{
  "site": {
    "cat": ["IAB19-30", "IAB19-18"]
  }
}

site.keywords / app.keywords

Content keywords, comma-separated.

Type: string
Required: No
Format: Comma-separated list
Location: BidRequest.site.keywords or BidRequest.app.keywords

Example:

{
  "site": {
    "keywords": "family activities,outdoor adventures,cooking,golf"
  }
}

user.data[].segment[]

IAB Audience Taxonomy segments.

Type: object[]
Required: No
Format: IAB Audience Taxonomy
Location: BidRequest.user.data[].segment[]

Example:

{
  "user": {
    "data": [
      {
        "id": "iab-audience",
        "name": "IAB Audience Taxonomy",
        "segment": [{ "id": "355" }, { "id": "350" }, { "id": "356" }]
      }
    ]
  }
}

Privacy & Consent Fields

user.ext.consent

IAB GDPR consent string.

Type: string
Required: No (required if GDPR applies)
Location: BidRequest.user.ext.consent

Example:

{
  "user": {
    "ext": {
      "consent": "CPXxRfAPXxRfAAfKABENB-CgAAAAAAAAAAYgAAAAAAAA"
    }
  }
}

regs.ext.gdpr

GDPR applies flag.

Type: integer
Required: No
Values: 0 (does not apply), 1 (applies)
Location: BidRequest.regs.ext.gdpr

Example:

{
  "regs": {
    "ext": {
      "gdpr": 1
    }
  }
}

regs.ext.us_privacy

IAB US Privacy (CCPA) string.

Type: string
Required: No
Location: BidRequest.regs.ext.us_privacy

Example:

{
  "regs": {
    "ext": {
      "us_privacy": "1YNN"
    }
  }
}

regs.coppa

COPPA applies flag.

Type: integer
Required: No
Values: 0 (does not apply), 1 (applies)
Location: BidRequest.regs.coppa

Example:

{
  "regs": {
    "coppa": 0
  }
}

Field Validation

Required Fields

These fields are required when the parent object is present:

• messageSequenceNumber (always required)
• messageLength (always required)
• isQuickReply (always required)
• sessionDurationMs (always required)
• intent.value (if intent object present)
• intent.confidence (if intent object present)
• intent.topics (if intent object present)
• intent.signals (if intent object present)
• sentiment.value (if sentiment object present)
• sentiment.score (if sentiment object present)
• funnel.stage (if funnel object present)
• funnel.progress (if funnel object present)

Optional Fields

These fields are optional:

• userThinkTimeMs
• intent (entire object)
• sentiment (entire object)
• funnel (entire object)
• audience (entire object)
• audience.interests
• audience.behaviors

Next Steps

• Conversation Metadata - Operational metrics
• Intent Analysis - User intent signals
• Sentiment Analysis - Sentiment detection
• API Reference - Complete endpoint documentation