Getting started with Smart AdServer's APIs

Read this article to find general information about the API.

Overview

The process to set up Smart AdServer's API consists in the following steps:

  1. Discuss with your service contact if the API makes sense for your specific use case
  2. Request a developer account from your service contact
  3. Perform tests
  4. If tests comply with Smart AdServer's fair use policy, request a production account from your service contact
  5. Use the API in production

Fair use policy

The APIs are subject to limits to prevent API performance issues caused by large scale modifications (intended or accidental).

Limits per day

  • 10,000 read operations
  • 1,000 write operations

Resources documentation and composer

Access the resources documentation here and enter your network ID to load the resources.

For each resource, you will find:

  • (1) The resource name
  • (2) A label for the component (manage, rtb or forecast)
  • (3) A link to the composer (request building tool) for testing
Resources documentation and composer

Developer environment

The developer environment works similarly to the production environment. To access its resources documentation and composer, click here.

Base URL

The Base URL for the API is:

https://ZZZ.smartadserverapis.com/XXX

where ZZZ represents the specific API. Its valid values are:

  • manage
  • rtb
  • forecast

XXX represents the ID of your network.

Requests headers and Authentication

Here are the mandatory keys, to be used in all requests:

Authorization: Basic YYY
Content-Type: application/json; charset=utf-8

YYY represents your base64-encoded credentials.

The user name has the format: myUserName@myCompanyName

To generate your base64-encoded credentials, use a UTF-8 base64 encoder (example here).

For instance, if your string is

myUserName@myCompanyName:myPassword

the encoded result is

bXlVc2VyTmFtZUBteUNvbXBhbnlOYW1lOm15UGFzc3dvcmQ=

Hence, you would add this to all of your request headers:

Authorization: Basic bXlVc2VyTmFtZUBteUNvbXBhbnlOYW1lOm15UGFzc3dvcmQ=
Content-Type: application/json; charset=utf-8

 

Pagination of responses

API responses are paginated. Each page can hold a maximum of 100 items. The response header includes the pagination information.

The following response header contains the total amount of items matching your request:

X-Pagination-Total-Count

If this total exceeds 100, the response headers will also contain information to retrieve the next page and the previous pages.

The "Link" response header contains the link to the next page. It looks as follows:

<NextPageUrl>; rel="next"

To retrieve the next page’s results, make the same request again (same headers and body), but replace the called url with the value of <NextPageUrl>.

If a page has a previous page, the "Link" response header contains the link to the previous page. It looks as follows:

<PreviousPageUrl>; rel="prev"

If a page has both a previous and a next page, the "Link" response header contains both links, separated by a comma (,).

To customize the page size (max. number of items per page), add the "limit" parameter in the called URL. The value must not exceed 100.

Example for a request with a page size of 10 items:

https://forecast.smartadserverapis.com/XXX/forecast/?offset=10&limit=10

Example response headers:

X-Pagination-Total-Count: 89
Link: <https://forecast.smartadserverapis.com/XXX/forecast/?offset=20&limit=10>; rel="next", <https://forecast.smartadserverapis.com/XXX/forecast/?offset=0&limit=10>; rel="prev"

Note: Calls which always return a single item (e. g.: /criteria/10) are not concerned.

Was this article helpful?
0 out of 0 found this helpful
Powered by Zendesk