Getting Started

Introduction

Use this page to get started with the Marketplace Supply-Side Platform (SSP) application programming interface (API).

If you're looking for more API resources, you'll find them in our knowledge base. Use the following links for quick access.

• SSP & Ad Server Integration Documentation
• Ad Serving Order Management API
• SSP Venue Management APIs
• SSP Reporting API
• DSP Reporting API

What You'll learn

In this topic, you'll learn about:

• Where and how to call the API.
• The authentication process.
• API rate and access limits.
• Pagination using the page and page_size parameters.
• Using the filter query parameter.
• Using the search parameter.
• Using the sorting parameters (order and asc).

Calling the API

Once you’ve reviewed how the API works and set up authentication, you're ready to start calling the endpoints.

API Environments and Hostnames

The SSP API is available in both Staging and Production environments. These environments correspond with our Trafficking Staging and Production environments as follows:

• Staging: staging-platform-api.vistarmedia.com
• Production: platform-api.vistarmedia.com

Connection Requirements

To protect data in transit, the API enforces strong encryption standards:

• Use Transport Layer Security (TLS) (HTTPS) only
• TLS versions: 1.2 or 1.3
• Supported cipher suites:
  • TLS_AES_128_GCM_SHA256
  • TLS_AES_256_GCM_SHA384
  • TLS_CHACHA20_POLY1305_SHA256
  • ECDHE-RSA-AES128-GCM-SHA256
  • ECDHE-RSA-AES128-SHA256
  • ECDHE-RSA-AES256-GCM-SHA384
  • ECDHE-RSA-AES256-SHA384
• Protocol compatibility: Supports both HTTP/1.1 and HTTP/2

These requirements help ensure your API integration meets modern security standards—protecting your data and your users.

Authentication

Before you can interact with the Marketplace SSP API, you must authenticate using a dedicated user (similar to a Service Account) and obtain a session token. This ensures your requests are securely scoped to the correct account and environment.

Set Up a Dedicated API User

You must create a dedicated API Access-enabled user for each account you plan to access via the API.

• Use this user only for API access.
• A user is tied to one account and one environment. If you work across multiple accounts or across Staging and Production, create separate users for each.
• When you set up the user in Admin, select API Access. For instructions on creating a new user, see Admin Management.

Session-Based Authentication

The API uses session-based authentication. To begin:

1. Call the session endpoint using your API user’s login credentials (username and password).
2. The API returns a Set-Cookie header containing your session token.
3. Include this token in the Cookie header of all subsequent requests.

Some Hypertext Transfer Protocol (HTTP) clients automatically manage session cookies. If yours does not, persist the token and send it manually.

Example

Sample JSON Request

POST https://platform-api.vistarmedia.com/api/session

Content-Type: application/json

{
  "email": "username",
  "password": "mypassword"
}

Sample HTTP Response Headers

HTTP/1.1 200 OK
Date: Fri, 01 Aug 2025 14:45:45 GMT
Content-Type: application/json
Set-Cookie: tr-development=eyJfcGVybWFuZW50Ijp0cnVlLCJ1c2VyLmlkIjoiSkxPRklwOUJUOVNidFFvNXU1QlJ0USIsInVzZXIuaXNfYWRtaW4iOmZhbHNlfQ.G25kmQ.TIUV2Zvlm3dq5Ssl93mlKchG2QU; Domain=.vistarmedia.com; 
Domain=.vistarmedia.com; 
Expires=Fri, 01-Aug-2025 22:45:45 GMT; Secure; HttpOnly; Path=/

In this example, the session cookie is:

tr-development=eyJfcGVybWFuZW50Ijp0cnVlLCJ1c2VyLmlkIjoiSkxPRklwOUJUOVNidFFvNXU1QlJ0USIsInVzZXIuaXNfYWRtaW4iOmZhbHNlfQ.G25kmQ.TIUV2Zvlm3dq5Ssl93mlKchG2QU

A subsequent request sends this back in the Cookie header:

GET https://platform-api.vistarmedia.com/api/ssp/v1/advertisers/000lYW0SSFSPuV32udyVpA

Cookie: tr-development=eyJfcGVybWFuZW50Ijp0cnVlLCJ1c2VyLmlkIjoiSkxPRklwOUJUOVNidFFvNXU1QlJ0USIsInVzZXIuaXNfYWRtaW4iOmZhbHNlfQ.G25kmQ.TIUV2Zvlm3dq5Ssl93mlKchG2QU

Access Limits

To ensure system stability and fair usage, the Marketplace SSP API enforces rate limits on all requests. These limits help prevent server overload and protect performance for all users.

If you exceed these limits, the API returns an HTTP 429 error. To avoid errors, build in increasing wait times between retries—especially when automating workflows or running batch operations.

Pagination

All list operations in the Marketplace SSP API support pagination. Pagination helps you manage large sets of data by returning results in smaller, more manageable chunks.

Use the following query parameters to control pagination:

In the API response:

• The returned results appear in a subobject named after the queried resource (for example, creatives).
• The total_size field provides the total number of matching results.

Example

On the List Advertisers endpoint, this request returns the first 10 results:

GET https://platform-api.vistarmedia.com/advertisers?page_size=10&page=0

Sample JSON response

On the List Advertisers endpoint, this request returns the first 10 results:

GET https://platform-api.vistarmedia.com/advertisers?page_size=10&page=0

Sample JSON Response

{
  "advertisers": [
    {
      "id": "000lYW0SSFSPuV32udyVpA",
      "name": "Nimbus Homeware Co."
    },
    {
      "id": "000_VIH2QaqVN9di7H4AEA",
      "name": "Everpure Essentials"
    },
    {
      "id": "002_g3BbQ50xaom0w8xX5w",
      "name": "Flicker & Bloom"
    },
    {
      "id": "0039nqXKTO0deVpn4M3pPw",
      "name": "Zyra Consumer Labs"
    },
    {
      "id": "003pYILFT6W1wvyQxF10ug",
      "name": "Auric Living Products"
    },
    {
      "id": "00460k62StS3kQrLbtdlaQ",
      "name": "Velvo Household Inc."
    },
    {
      "id": "004FAc_6TiSm_BPgfGNF6A",
      "name": "Plentique Goods"
    },
    {
      "id": "0_08AwjXRfKLOYaqby0pGw",
      "name": "Ravica Solutions"
    },
    {
      "id": "008nP3LgSI6DU3oU96Xneg",
      "name": "Solvanta Home Care"
    },
    {
      "id": "008SCUXpRP6g_SSI8_G5vw",
      "name": "Kinterra Brands"
    }
  ],
  "total_size": 55829
}

Filtering

Use the filter query parameter to narrow the results returned by most list operations in the Marketplace SSP API. Filtering helps you focus on the data that matters most—such as creatives pending review or associated with specific advertisers.

It’s worth noting:

• Not all fields support filtering. The Endpoint Document specifies which fields you can filter.
• All filters are case-sensitive unless noted otherwise.

Filter Format

Each filter follows this format:

filter=field:<value>

You can apply multiple filters by including the filter parameter more than once in your request. For example:

Filter Logic

The API supports two types of logic when combining filters:

1. AND logic (intersection across different fields).
   When you use filters for different fields, the result includes only records that match all conditions. For example, return creatives that are unapproved and from a specific advertiser:

   GET https://platform-api.vistarmedia.com/api/ssp/v1/creatives?filter=audit.status:pending&filter=advertiser_id:000lYW0SSFSPuV32udyVpA

2. OR logic (union across the same field).
   When you use multiple filters for the same field, the result includes records that match any of the values. For example, return creatives associated with either of two advertisers:

   GET https://platform-api.vistarmedia.com/api/ssp/v1/creatives?filter=advertiser_id:000lYW0SSFSPuV32udyVpA&filter=advertiser_id:008SCUXpRP6g_SSI8_G5vw

Search

Some Marketplace SSP API list operations support search using the search query parameter. This feature helps you find records by performing substring searches on supported string fields—useful when you don’t have an exact match.

It’s worth noting that not all fields allow searching. The Marketplace SSP API documentation specifies which fields support search.

Search Format

Search queries follow this format:

search=field:<value>

Example

Return all advertisers where the name contains the substring “foo”.

https://platform-api.vistarmedia.com/api/ssp/v1/advertisers?search=name%3Afoo

Sorting

Use the order and asc parameters to sort the results of a list operation. Sorting lets you control the display order of returned records. The order parameter specifies the field to sort on, and asc is a boolean that controls sort direction. Using asc=false applies descending (Z–A) order. Using asc=true applies ascending (A–Z) order. By default, descending order applies when asc isn’t included.

Not all fields allow sorting. You can only sort on fields listed in the Marketplace SSP API documentation.

Sorting Format

order=<field>&asc=<true|false>

Example

Return all advertisers sorted by name in descending (Z–A) order.

https://platform-api.vistarmedia.com/api/ssp/v1/advertisers?order=name

Return all advertisers sorted by name in ascending (A–Z) order.

https://platform-api.vistarmedia.com/api/ssp/v1/advertisers?order=name&asc=true