Skip to main content

Required Fields

Complete list of required fields for valid OpenRTB 2.6 bid requests to the Affinity AI Bid API.

Overview​

The Affinity AI Bid API enforces strict validation of required fields to ensure proper bid processing. Requests missing required fields will be rejected with a 400 Bad Request error.

Top-Level Required Fields​

BidRequest Object​

FieldTypeDescriptionExample
idstringUnique ID for this bid request"req-001"
impobject[]Array of impression objects (min: 1)[{...}]

Minimal Valid Request​

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

Impression Object Required Fields​

Imp Object​

FieldTypeDescriptionExample
idstringUnique ID for this impression within request"imp-1"

Important: Each impression must include:

  • native - For native ads

Example with Multiple Impressions​

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

Native Object Required Fields​

For native impressions, this field is required:

FieldTypeDescriptionExample
requeststringJSON-encoded native request"{\"native\":{...}}"

The request field must contain a JSON-encoded string following the Native Ads 1.2 specification.

Example Native Request​

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

While not strictly required, providing either site OR app is strongly recommended for proper targeting and reporting.

For Web Traffic - Use Site​

{
  "id": "req-003",
  "imp": [
    {
      "id": "imp-1",
      "native": {
        "request": "{\"native\":{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":80}}]}}"
      }
    }
  ],
  "site": {
    "id": "site-123",
    "domain": "publisher.com",
    "keywords": "news,technology"
  }
}

For App Traffic - Use App​

{
  "id": "req-004",
  "imp": [
    {
      "id": "imp-1",
      "native": {
        "request": "{\"native\":{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":80}}]}}"
      }
    }
  ],
  "app": {
    "id": "app-456",
    "bundle": "com.example.app",
    "keywords": "gaming,entertainment"
  }
}

Field Uniqueness Requirements​

Request ID Uniqueness​

The id field in the BidRequest must be unique across all requests:

{
  "id": "req-unique-12345",  // Must be unique
  "imp": [...]
}

Best Practice: Use a combination of timestamp and random string:

const requestId = `req-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`

Impression ID Uniqueness​

Each imp[].id must be unique within the same request:

{
  "id": "req-005",
  "imp": [
    {
      "id": "imp-1", // Unique within this request
      "native": {
        "request": "{\"native\":{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":80}}]}}"
      }
    },
    {
      "id": "imp-2", // Different from imp-1
      "native": {
        "request": "{\"native\":{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":80}}]}}"
      }
    }
  ]
}

Validation Examples​

✅ Valid Minimal Request​

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

❌ Invalid: Missing Request ID​

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

Error:

{
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Required field missing",
    "details": {
      "field": "id",
      "reason": "BidRequest must include 'id' field"
    }
  }
}

❌ Invalid: Missing Impression Array​

{
  "id": "req-invalid-002"
}

Error:

{
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Required field missing",
    "details": {
      "field": "imp",
      "reason": "BidRequest must include 'imp' array with at least one impression"
    }
  }
}

❌ Invalid: Missing Impression ID​

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

Error:

{
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Required field missing",
    "details": {
      "field": "imp[0].id",
      "reason": "Impression must include 'id' field"
    }
  }
}

❌ Invalid: Missing Format Object​

{
  "id": "req-invalid-004",
  "imp": [
    {
      "id": "imp-1"
    }
  ]
}

Error:

{
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Required field missing",
    "details": {
      "field": "imp[0]",
      "reason": "Impression must include native"
    }
  }
}

Quick Reference Checklist​

Use this checklist to ensure your request includes all required fields:

Minimum Requirements​

  • id - Unique request identifier
  • imp - Array with at least one impression
  • imp[].id - Unique impression identifier (within request)
  • Format object per impression:
    • native with request string
  • site.publisher.id - Publisher account ID (assigned by Affinity AI)
  • site.id and site.domain OR app.id and app.bundle - For publisher identification
  • site.keywords OR app.keywords - For contextual targeting
  • device.ua - User agent string
  • device.ip - IP address for geo-targeting
  • device.geo.country - Country code for targeting

Testing Required Fields​

Validation Tool​

Use cURL to test your request:

curl -X POST https://bid-aura.affinity.net/openrtb2 \
  -H "Content-Type: application/json" \
  -d '{
    "id": "test-001",
    "imp": [{
      "id": "imp-1",
      "native": { "request": "{\"native\":{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":80}}]}}" }
    }]
  }'

Next Steps​

Support​

If you receive validation errors:

  1. Check the error.details.field to identify the missing field
  2. Review this documentation for field requirements
  3. Contact support with the request_id if issues persist