Skip to main content
GET
/
advertisers
List advertisers
curl --request GET \
  --url https://api.interchange.io/api/v2/buyer/advertisers \
  --header 'Authorization: Bearer <token>'
{
  "items": [
    {
      "id": "12345",
      "name": "Acme Corp",
      "sandbox": true,
      "primaryCurrency": "USD",
      "currencyLocked": true,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-20T14:45:00Z",
      "linkedAccountCount": 3,
      "brand": "nike.com",
      "linkedBrand": {
        "id": "brand_123",
        "name": "Acme Brand",
        "domain": "acme.com",
        "manifest": {
          "name": "Acme Corporation",
          "url": "https://www.acme.com",
          "logos": [
            {
              "url": "<string>",
              "tags": [
                "<string>"
              ],
              "width": 123,
              "height": 123
            }
          ],
          "colors": {
            "primary": "#FF5733",
            "secondary": "<string>",
            "accent": "<string>",
            "background": "<string>",
            "text": "<string>"
          },
          "fonts": {
            "primary": "Roboto",
            "secondary": "<string>",
            "fontUrls": [
              "<string>"
            ]
          },
          "tone": "Professional, friendly, and innovative",
          "tagline": "Innovation for Everyone",
          "assets": [
            {
              "assetId": "<string>",
              "assetType": "<string>",
              "url": "<string>",
              "name": "<string>",
              "description": "<string>",
              "tags": [
                "<string>"
              ],
              "width": 123,
              "height": 123,
              "durationSeconds": 1,
              "fileSizeBytes": 123,
              "format": "<string>",
              "metadata": {}
            }
          ],
          "productCatalog": {
            "feedUrl": "<string>",
            "categories": [
              "<string>"
            ],
            "lastUpdated": "2023-11-07T05:31:56Z"
          },
          "disclaimers": [
            {
              "text": "<string>",
              "required": true,
              "context": "<string>"
            }
          ],
          "industry": "Technology",
          "advertiserIndustry": "food_beverage.restaurants",
          "targetAudience": "Small business owners aged 25-45",
          "contact": {
            "email": "jsmith@example.com",
            "phone": "<string>",
            "website": "<string>"
          },
          "metadata": {
            "createdDate": "2023-11-07T05:31:56Z",
            "updatedDate": "2023-11-07T05:31:56Z",
            "version": "1.0.0"
          }
        },
        "logoUrl": "https://acme.com/logo.png",
        "industry": "Technology",
        "colors": {
          "primary": "#FF5733"
        },
        "tagline": "Innovation for Everyone",
        "tone": "Professional, friendly, and innovative"
      }
    }
  ],
  "total": 42,
  "hasMore": true,
  "nextOffset": 4503599627370495
}

Authorizations

​
Authorization
string
header
required

API key or access token

Query Parameters

​
status
enum<string>
default:ACTIVE

Filter by advertiser status. Use ALL to include both active and archived. Defaults to ACTIVE.

Available options:
ACTIVE,
ARCHIVED,
ALL
​
name
string

Filter by advertiser name (case-insensitive, partial match)

Example:

"Acme"

​
linkedAccountPartnerId
string

Filter to advertisers linked to at least one account from this partner / sales agent ID.

Example:

"snap"

​
sandbox
boolean

Filter by sandbox mode. true returns only sandbox advertisers, false returns only production advertisers. Omit to return all.

​
includeBrand
boolean

When true, include linked brand identity data on advertiser summary rows so creative agents can use brand logos, colors, tone, and catalog data.

​
limit
integer
default:100

Maximum number of advertisers to return per page (default: 100, max: 100)

Required range: x <= 100
Example:

100

​
offset
integer
default:0

Number of advertisers to skip for pagination (default: 0)

Required range: 0 <= x <= 9007199254740991
Example:

0

Response

List advertisers

Response containing a paginated list of advertiser summaries

​
items
object[]
required

Advertisers projected to the summary shape. Use get_advertiser for the full resource.

​
total
integer
required

Total count of advertisers matching the query

Required range: 0 <= x <= 9007199254740991
Example:

42

​
hasMore
boolean
required

Whether there are more results available

​
nextOffset
integer | null
required

Offset to use for the next page of results, or null if no more results

Required range: 0 <= x <= 9007199254740991