PCABidRequest

The top-level bid request for Product Contextual Ads. Publishers send this object as the JSON body of the POST request to describe the page, placements, user, device, and app or site context.

idstringrequired

A unique ID for the ad request, generated by the publisher.

Example: requestId-abc-123

pagestringrequired

The type of page where FCC displays the ad.

Possible values: [SEARCH, BROWSE]

placement_requests object[]required

Array of Placement Request objects, each defining a specific ad placement (ad slot) on the page. Include one object per placement you want FCC to fill.

Every request must include at least one placement.

Possible values: >= 1

Array [

placementstringrequired

The unique, alphanumeric ID for the specific ad placement (e.g., "TOP_OF_SEARCH", "REST_OF_SEARCH").

Example: TOP_OF_SEARCH

countinteger

The maximum number of ads to return for this placement. Defaults to 1.

Default value: 1

]

querystring

The raw search query entered by the user. Recommended. Required for page: "SEARCH".

Example: foo

query_langstring

The language of the query string (e.g., "en", "fr") using ISO 639-1 alpha-2 codes.

filters object[]

Array of Filter objects used to refine the ad selection based on specific product attributes. Include one Filter object per attribute you want to filter on.Values within a single filter have an OR relationship. Multiple filters have an AND relationship

Array [

fieldstringrequired

The name of the field to which this filter applies. Filterable fields are product-level attributes ingested in the catalog (e.g., brand_id, category_id_path).

Example: brand_id

valuestring[]required

The set of values on which to apply the matching operation. Values within a single filter have an OR relationship.

Example: ["260332020","260332021"]

typestringrequired

The type of matching to perform.

Possible values: [EQ, RANGE, GE, LE]

]

device objectrequired

Device object containing the details of the user's device to which FCC delivers the impression. Includes hardware, platform, location, and carrier data.

FCC uses this context to target and deliver the ad correctly to the requesting device.

uastringrequired

User agent of the device. Send the original user agent without any modifications.

Example: Dalvik/2.1.0 (Linux; U; Android 7.0; SM-J701F Build/NRD90M)

ipstring

IP address of the device in IPv4 format. Required if you omit the ipv6 field.

osstring

Name of the operating system currently installed on the device.

osvstring

Version of the operating system currently installed on the device.

ifastring

Unique AdId for the device: Identifier for Advertising (IDFA) for iOS, Google Advertising ID (AAID) for Android. Use visitorId as a proxy for msite and website, or when ifa is unavailable.

Example: 58f33893-09d7-4b42-9427-9540179adddd

user objectrequired

Details about the end user.

The user id is an exchange artifact and may be subject to rotation or other privacy policies. Keep the user id stable long enough to serve as the basis for attribution or personalization use cases.

idstringrequired

A unique, persistent ID for the user, generated by the publisher.

Example: 7d797540-aaf7-44f3-a347-28754be43792

yobinteger

The user's year of birth as a 4-digit integer.

genderstring

The user's gender.

M: male
F: female
O: other

Possible values: [M, F, O]

app object

Details of the mobile application where FCC shows the ad.

Required if you omit site. Include this object if you show the ad in a mobile application. A request must include at either one of app or site.

idstringrequired

The unique identifier for the mobile application.

Example: app-store-id-12345

namestringrequired

The application's name.

domainstring

The domain of the application's publisher.

publisher objectrequired

Describes the publisher who owns the app.

idstringrequired

A unique ID for the publisher.

Example: pub-Id-5678

namestring

The publisher's name.

site object

Details of the website where FCC shows the ad.

Required if you omit app. Include this object if you show the ad on a website. A request must include at either one of app or site.

idstringrequired

The site's unique ID on the ad platform.

namestringrequired

The site's name.

domainstringrequired

The domain of the site (e.g., "flipkart.com").

pagestring

The URL of the page where FCC displays the ad.

publisher objectrequired

Describes the publisher who owns the site.

idstringrequired

A unique ID for the publisher.

Example: pub-Id-5678

namestring

The publisher's name.

wlangstring[]required

An array of languages for the request, using ISO 639-1 alpha-2 codes. Represents the primary language of the app or site.

PCABidRequest
{
  "id": "requestId-abc-123",
  "page": "SEARCH",
  "placement_requests": [
    {
      "placement": "TOP_OF_SEARCH",
      "count": 1
    }
  ],
  "query": "foo",
  "query_lang": "string",
  "filters": [
    {
      "field": "brand_id",
      "value": [
        "260332020",
        "260332021"
      ],
      "type": "EQ"
    }
  ],
  "device": {
    "ua": "Dalvik/2.1.0 (Linux; U; Android 7.0; SM-J701F Build/NRD90M)",
    "ip": "string",
    "os": "string",
    "osv": "string",
    "ifa": "58f33893-09d7-4b42-9427-9540179adddd"
  },
  "user": {
    "id": "7d797540-aaf7-44f3-a347-28754be43792",
    "yob": 0,
    "gender": "M"
  },
  "app": {
    "id": "app-store-id-12345",
    "name": "string",
    "domain": "string",
    "publisher": {
      "id": "pub-Id-5678",
      "name": "string"
    }
  },
  "site": {
    "id": "string",
    "name": "string",
    "domain": "string",
    "page": "string",
    "publisher": {
      "id": "pub-Id-5678",
      "name": "string"
    }
  },
  "wlang": [
    "string"
  ]
}