❗️
Authorization
To query this API, include a Secret Key in the Authorization header of your request. The value of the header must be formatted as secret {SECRET_KEY}, ensuring that the word secret is followed by a space before the key itself.
For details on generating a Secret Key for your site, visit our Authorization guide.

🚧
Required Field
The campaignId parameter is mandatory for all API requests. To get a list of campaigns, or search for a specific campaign by name, visit our Campaigns guide.

Rate Limiting

📘
API Rate Limit
1 request every 10 seconds

Requests are limited to 1 request every 10 seconds. Exceeding this rate limit can result in your API key being temporarily blocked or throttled.

To adhere to this rate limit:

Include a delay of at least 10 seconds between consecutive API calls.
If you need to make multiple requests (e.g., when paginating through results), ensure there is a minimum gap of 10 seconds between each request or that the previous request has completed before making another one.

Filters

You can filter the response by including one or more filters in the request body. Each filter consists of a type and a list of values. The available filter types are: NAME, GROUP_ID, DOMAIN, GEO, PROGRAM_TYPE, and CATEGORY. Each filter is represented as an object in the filters array.

🚧
Filter Limits
Thefilters object supports a maximum of 2,500 values per request. Requests exceeding this limit won’t be processed. To avoid issues, we recommend requesting the full list and applying filtering on your side, or batching into multiple smaller requests.

Filters Structure

In the request body, you can pass multiple filters using the following structure:

{
  "filters": [
    {
      "type": "<FILTER_TYPE>",
      "values": ["<VALUE_1>", "<VALUE_2>", "..."]
    }
  ],
  "page": 1,
  "pageSize": 1000
}

Name

Filter results based on the name of the merchant.

{
  "type": "NAME",
  "values": ["Walmart"]
}

Group ID

Filter results by the merchant group id.

{
  "type": "GROUP_ID",
  "values": [384]
}

Domain

Filter results by domains associated with the merchant.

{
  "type": "DOMAIN",
  "values": ["walmart.com"]
}

Geo

Filter merchant groups by geographic regions using lower-case ISO Country Codes (e.g., “us” for United States, “ca” for Canada).

🚧
Only CPA programs return results when filtering by geo. Please do not include a geo filter if you are looking for CPC results.

{
  "type": "GEO",
  "values": ["us", "ca"]
}

Program Type

Filter results by the program type, such as CPA (Cost Per Acquisition) or CPC (Cost Per Click).

{
  "type": "PROGRAM_TYPE",
  "values": ["CPA"]
}

Accepted Arguments	Meaning
`CPA`	Cost per action
`CPC`	Cost per click

Category

Filter results based on the category of the merchant using Sovrn category codes.

{
  "type": "CATEGORY",
  "values": ["CE", "AU"]
}

Accepted Arguments	Meaning
`CE`	Consumer Electronics
`AU`	Automotive
`FS`	Fashion & Accessories
`HB`	Health & Beauty
`RU`	Real Estate
`AE`	Art & Entertainment
`SF`	Sports & Fitness
`SH`	Self-Help
`TV`	Travel
`FI`	Financial Services
`PT`	Pets
`CM`	Cell Phones & Mobile
`BK`	News, Books & Magazines
`ED`	Education
`OT`	Other
`DT`	Dating
`MM`	Music & Musicians
`FD`	Food & Drink
`HG`	Home & Garden
`AG`	Adult & Gambling
`CA`	Career & Employment
`CB`	Collectibles
`EM`	Online Services
`FB`	Family & Baby
`FH`	Firearms and Hunting
`GM`	Gaming
`JW`	Jewelry & Watches
`LF`	Lifestyle
`MP`	Motorcycles & PowerSports
`SP`	Shopping & Coupons
`HO`	Toys & Hobbies
`CP`	Cameras & Photo
`UN`	Undefined

Pagination

The API supports pagination to control the number of results returned in a single response. You can specify the page number and the number of results per page using the page and pageSize fields in the request body.

page: The page number to retrieve (starting from 1).
pageSize: The number of results to return per page. The maximum allowed value is 2500, and the default value is 1000.

Example Request:

{
  "filters": [
    {
      "type": "GROUP_ID",
      "values": [384]
    }
  ],
  "page": 1,
  "pageSize": 1000
}

Pagination Fields in the Response:

page: The current page number.
perPage: The number of results per page (as specified in the request).
totalItems: The total number of items that match the filters.

Example Response:

{
  "results": [
    // Array of merchant summaries
  ],
  "page": 1,
  "perPage": 1000,
  "totalItems": 5000
}

200Successful operation