Skip to main content

Request Format

Complete specification of the OpenRTB 2.6 bid request format supported by the Affinity AI Bid API.

Request Structure​

{
  "id": "unique-request-id",
  "imp": [...],
  "site": {...},
  "app": {...},
  "device": {...},
  "user": {...},
  "regs": {...},
  "ext": {...}
}

Top-Level Objects​

BidRequest Object​

FieldTypeRequiredDescription
idstringYesUnique ID for this bid request
impobject[]YesArray of impression objects (at least one)
siteobjectNo*Site object (for web traffic)
appobjectNo*App object (for app traffic)
deviceobjectNoDevice object
userobjectNoUser object
regsobjectNoRegulations object (GDPR, CCPA, etc.)
extobjectNoExtensions object

*Either site or app should be provided for better targeting.

Example Minimal Request​

{
  "id": "req-001",
  "imp": [
    {
      "id": "imp-1",
      "native": {
        "request": "{\"native\":{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":80}}]}}"
      }
    }
  ]
}

Impression Object​

The imp array contains one or more impression objects representing ad placements.

Imp Object Fields​

FieldTypeRequiredDescription
idstringYesUnique ID for this impression within request
nativeobjectYesNative object
extobjectNoExtensions object

Example Impression​

{
  "id": "imp-1",
  "native": {
    "request": "{\"native\":{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":80}}]}}"
  },
  "ext": {
    "aura": {
      "adcpFormats": [
        {
          "agent_url": "https://creative.adcontextprotocol.org",
          "id": "display_300x250"
        }
      ]
    }
  }
}

Native Object​

For native ad placements.

Native Object Fields​

FieldTypeRequiredDescription
requeststringYesJSON-encoded native request object
verstringNoNative specification version (default: "1.2")
apiinteger[]NoSupported API frameworks
extobjectNoExtensions object

Example Native​

{
  "native": {
    "request": "{\"native\":{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":80}},{\"id\":2,\"required\":1,\"img\":{\"type\":3,\"w\":1200,\"h\":627}},{\"id\":3,\"required\":0,\"data\":{\"type\":2,\"len\":200}}]}}",
    "ver": "1.2",
    "api": [3, 5]
  }
}

Site Object​

For web-based traffic (mutually exclusive with app).

Site Object Fields​

FieldTypeRequiredDescription
idstringRecommendedSite ID on the exchange
domainstringRecommendedSite domain (e.g., "example.com")
keywordsstringRecommendedComma-separated keywords
publisherobjectRecommendedPublisher object
publisher.idstringRecommendedPublisher account ID (assigned by Affinity AI)
contentobjectNoContent object (for language)
extobjectNoExtensions object

Example Site​

{
  "site": {
    "id": "site-123",
    "domain": "example.com",
    "keywords": "family travel,vacation,resorts",
    "publisher": {
      "id": "my-publisher-id"
    },
    "content": {
      "language": "en"
    }
  }
}

App Object​

For app-based traffic (mutually exclusive with site).

App Object Fields​

FieldTypeRequiredDescription
idstringRecommendedApp ID on the exchange
bundlestringRecommendedApp bundle/package name
keywordsstringRecommendedComma-separated keywords
contentobjectNoContent object (for language
extobjectNoExtensions object

Example App​

{
  "app": {
    "id": "app-456",
    "bundle": "com.example.app",
    "keywords": "gaming,entertainment",
    "content": {
      "language": "en"
    }
  }
}

Device Object​

Information about the user's device.

Device Object Fields​

FieldTypeRequiredDescription
uastringRecommendedUser agent string
ipstringRecommendedIPv4 address
languagestringNoBrowser language (ISO-639-1-alpha-2)
geoobjectRecommendedGeographic location object
ifastringNoAdvertising ID (IDFA/AAID)
dpidsha1stringNoSHA1 hashed platform device ID
dpidmd5stringNoMD5 hashed platform device ID
extobjectNoExtensions object

Geo Object Fields​

FieldTypeRequiredDescription
countrystringRecommendedCountry code (ISO-3166-1-alpha-3)

Example Device​

{
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_5 like Mac OS X)...",
    "ip": "192.0.2.1",
    "language": "en",
    "geo": {
      "country": "USA"
    },
    "ifa": "AEBE52E7-03EE-455A-B3C4-E57283966239",
    "dpidsha1": "AA000DFE74168477C70D291f574D344790E0BB11"
  }
}

User Object​

Information about the user (privacy-compliant).

User Object Fields​

FieldTypeRequiredDescription
idstringNoUser ID on the exchange
extobjectNoExtensions object

Example User​

{
  "user": {
    "id": "user-789"
  }
}

Regulations Object​

Privacy and regulatory compliance information.

Regs Object Fields​

FieldTypeRequiredDescription
coppaintegerNoCOPPA compliance required (0=no, 1=yes)
extobjectNoExtensions object

Example Regs​

{
  "regs": {
    "coppa": 0,
    "ext": {
      "gdpr": 1,
      "us_privacy": "1YNN"
    }
  }
}

Affinity AI Extensions​

Optional Affinity AI-specific extensions in the ext object.

Request-Level Extensions​

{
  "ext": {
    "aura": {
      "intent": {
        "value": "information_seeking",
        "confidence": 0.92,
        "topics": ["family travel", "golf", "california"]
      },
      "sentiment": {
        "value": "positive",
        "score": 0.75
      },
      "conversation": {
        "turn_count": 3,
        "session_id": "session-abc123"
      }
    }
  }
}

View context enhancement details →

Impression-Level Extensions​

{
  "imp": [
    {
      "id": "imp-1",
      "native": {
        "request": "{\"native\":{\"ver\":\"1.2\",\"assets\":[...]}}"
      },
      "ext": {
        "aura": {
          "adcpFormats": [
            {
              "agent_url": "https://creative.adcontextprotocol.org",
              "id": "display_300x250"
            }
          ]
        }
      }
    }
  ]
}

View AdCP format support →

Validation Rules​

Required Fields​

  • id: Must be unique per request
  • imp: Must contain at least one impression
  • imp[].id: Must be unique within request
  • imp[]: Must include native
  • Either site or app (but not both)

Field Constraints​

  • id: Max 64 characters
  • imp[].id: Max 64 characters
  • native.request: Must be valid JSON-encoded native request

View complete validation rules →

Next Steps​