# 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](https://help.vistarmedia.com/hc/en-us/categories/203254228-Integrations) - [Ad Serving Order Management API](https://help.vistarmedia.com/hc/en-us/articles/9368616347533-Order-Management-API) - [SSP Venue Management APIs](https://help.vistarmedia.com/hc/en-us/sections/205640607-API-documentation) - [SSP Reporting API](https://help.vistarmedia.com/hc/en-us/articles/360038654472-Ad-platform-reporting-API) - [DSP Reporting API](https://help.vistarmedia.com/hc/en-us/sections/205623687-API-documentation) ## What You'll learn In this topic, you'll learn about: - [Where and how to call the API](#calling-the-api). - [The authentication process](#authentication). - [API rate and access limits](#access-limits). - [Pagination using the `page` and `page_size` parameters](#pagination). - [Using the `filter` query parameter](#filtering). - [Using the `search` parameter](#search). - [Using the sorting parameters (`order` and `asc`)](#sorting). ## Calling the API Once you’ve reviewed how the API works and set up authentication, you're ready to start calling the endpoints. IMPORTANT Use this API only in secure, server-to-server environments. Don’t call it from applications that can’t safely store credentials—like browser-based single-page apps. ### 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](https://help.vistarmedia.com/hc/en-us/articles/115000717768-Admin-management). IMPORTANT Sessions are valid for 8 hours. Reuse your session token across requests rather than creating a new session each time. ### 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 ```http POST https://platform-api.vistarmedia.com/api/session Content-Type: application/json ``` ```json { "email": "username", "password": "mypassword" } ``` #### Sample HTTP Response Headers ```http 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: ```text tr-development=eyJfcGVybWFuZW50Ijp0cnVlLCJ1c2VyLmlkIjoiSkxPRklwOUJUOVNidFFvNXU1QlJ0USIsInVzZXIuaXNfYWRtaW4iOmZhbHNlfQ.G25kmQ.TIUV2Zvlm3dq5Ssl93mlKchG2QU ``` A subsequent request sends this back in the `Cookie` header: ```http 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. | Action | Limit | Enforced per | | --- | --- | --- | | Session creation | 10 requests per minute | IP address | | GET requests | 100 requests per minute | User | | PUT, POST, PATCH requests | 10 requests per minute | User | 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: | Parameter | Description | | --- | --- | | `page_size` | The maximum number of results to return.The default value is 25. The maximum value is 100. | | `page` | The page offset to return. This value is zero-indexed: 0 is the first page, 1 is the second page, and so on.If you don’t specify a page, the API returns the first page (0). | 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: ```http 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: ```http GET https://platform-api.vistarmedia.com/advertisers?page_size=10&page=0 ``` ### Sample JSON Response ```json { "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: ```text filter=field: ``` 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: ```http 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: ```http 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](https://www.vistarmedia.com/hubfs/ssp.html#tag/SSP) specifies which fields support search. ### Search Format Search queries follow this format: ```text search=field: ``` ### Example Return all advertisers where the name contains the substring “foo”. ```text 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](https://www.vistarmedia.com/hubfs/ssp.html#tag/SSP). ### Sorting Format ```text order=&asc= ``` ### Example Return all advertisers sorted by name in descending (Z–A) order. ```text https://platform-api.vistarmedia.com/api/ssp/v1/advertisers?order=name ``` Return all advertisers sorted by name in ascending (A–Z) order. ```text https://platform-api.vistarmedia.com/api/ssp/v1/advertisers?order=name&asc=true ```