🚧

Authorization

In order to query this API you will need to use a Secret Key in the Authorization header of the request. To learn more about 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.

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).

{
  "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"]
}

Category

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

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

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
}