Read this article to find general information about the API.
The process to set up Smart AdServer's API consists in the following steps:
- Discuss with your service contact if the API makes sense for your specific use case
- Request a developer account from your service contact
- Perform tests
- If tests comply with Smart AdServer's fair use policy, request a production account from your service contact
- 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
The developer environment works similarly to the production environment. To access its resources documentation and composer, click here.
The Base URL for the API is:
where ZZZ represents the specific API. Its valid values are:
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
the encoded result is
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:
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:
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:
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:
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.