SiteScout API

A comprehensive guide to the SiteScout API

Introduction

SiteScout API is a RESTful web service that enables programmatic access into the SiteScout RTB Infrastructure. By means of this web service, SiteScout clients are now able to automate numerous activities and build web, mobile, and desktop applications that interact directly with our systems. The API implements a wide range of features, which can be classified under the following categories (each category constitutes a so-called scope of access):

In order to feel comfortable examining this documentation, the reader must be familiar with basic principles of the REST architectural style. The central principle of REST is the notion of resource, which is an abstract entity that acts as the source of information (e.g., Campaign is a resource). Resources are addressable by Uniform Resource Indentifiers (URIs) and are materialized in the form of representations. A representation, in this context, is the actual document (formatted in JSON, for example) that is communicated across the network. We have attempted to draw from the best practices with regard to building a RESTful API. As such, the SiteScout API

  • Makes extensive use of the headers and status codes of the Hypertext Transfer Protocol (HTTP),
  • Sports predictable and friendly URIs (e.g., /advertisers/1/campaigns/99999)
  • Does not maintain any state on the server (stateless server),
  • Relies on JSON as the media type of choice for exchanging resource representations, with CSV being an option for the reporting scope,
  • Is self-descriptive and fully navigable by machines, thanks to content negotiation and HATEOAS support,
  • Employs OAuth 2 for authentication and authorization.

To use the SiteScout API, an existing SiteScout RTB user must register an API Client. During the registration process there will be issued a client ID and client secret, cumulatively called the client credentials. Client credentials are required to gain access to the SiteScout API.

The SiteScout API can be reached at http://api.sitescout.com/{version}, where {version} is the version of the API the client would like to interact with.

Versioning

Our industry evolves at the speed of light and we strive to stay on top of it. Thus, the SiteScout API will be updated frequently. While most updates will be backward-compatible, some can cause nuisance for the already-integrated clients. To avoid any unnecessary risks, we highly recommend directing all API requests to http://api.sitescout.com/{version}.

The current version of the API is v2; that is, one should direct requests to http://api.sitescout.com/v2. Requests that are missing the version number will be redirected to the latest version of the API.

In addition to the above global versioning mechanism, the SiteScout API will soon also support fine-grained versioning of resource representations by means of specifying the version number in the Accept header of an HTTP request.

Documentation Conventions

The client registration and authentication sections of this documentation outline the preliminary steps required to get started with the SiteScout API. The sections that follow will provide the reader with detailed descriptions of the API resources. In illustrations and resource descriptions, certain paths include a segment enclosed in curly braces (e.g., /advertisers/{advertiserId}); such a segment denotes a variable substituted at runtime for the actual value (e.g., /advertisers/1). While the descriptions of resources include exhaustive usage details, for organizational purposes the definitions of JSON resource representations reside in a separate section. If any error occurs, the API client will be notified with the most appropriate HTTP status code and a SiteScout Error JSON representation will be returned. Lastly, all GET requests should employ the query string for transferring parameters, if any.

Disallowed HTTP Methods

The SiteScout API employs the full spectrum of HTTP methods, including PUT, PATCH, and DELETE. We realize that certain user agents and environments restrict applications to GET and POST methods. That is why, we support tunneling of any of the aforementioned HTTP methods over a POST request with header X-HTTP-Method-Override set to the desired method (e.g., X-HTTP-Method-Override: PUT).

Rate Limiting

In order to prevent Denial-of-Service (DoS) attacks and provide all clients with a consistent experience, there has been implemented a rate limiting policy in the SiteScout API. The following hourly request limits are in effect per API client:

  • Reporting requests (scope STATS): 10,000
  • Campaign managements and audience requests (scopes CONTROL and AUDIENCES): 10,000
  • Campaign creations, also counted as campaign management requests: 100
  • Banner uploads, also counted as campaign management requests: 20
  • Archive uploads, also counted as campaign management requests: 20

Should you require a higher request limit than listed above, please contact your account manager.
A client’s rate limiting status is communicated using the following headers in each API response:

  • X-RateLimit-Limit: Currently set request limit
  • X-RateLimit-Remaining: Remaining requests
  • X-RateLimit-Reset: Next counter reset timestamp in milliseconds since midnight of January 1, 1970 UTC

Note that certain resources are protected with rate limiting rules that are based on the parameters submitted in a specific request. Such policies are mentioned in the request descriptions.

Legal

Usage of the SiteScout API is subject to the Terms and Conditions outlined on the following page: http://www.sitescout.com/legal/api-terms-of-service/
Back to top

Client Registration

Client registration is a mandatory step toward gaining access to the SiteScout API. This step allows us to keep track of the API usage and ensure a high-level of security. When registering, one will have to specify the intended use of the web service (application type), enter the application name, select the desired scopes of access, and accept the terms and conditions.

As a result of successful client registration, the user will be provided with client ID and client secret, both of which can then be employed to access the API.

At the moment, client registration can only be performed with the help of your account manager.

Back to top

API Sample Code and Libraries

An example JSF application which accesses the SiteScout Application Programming Interface is available via git at the following address:

Java (JSF)

If you have usage examples or code libraries in other languages that you are willing to share with the community, please let us know.

Back to top

Authentication

OAuth 2

In order to access any part of the SiteScout API, an API client must be authenticated. With the goal of adhering to the industry standards, the authentication and authorization processes are performed in accordance with the OAuth 2 specification. Even though this documentation does familiarize the reader with the basics of OAuth 2, we highly recommend reading the specification itself and studying one of the numerous tutorials found on the Internet.

In short, OAuth 2 defines a number of authentication flows that handle most use cases of publicly accessible online APIs. All these flows involve the notion of authorization grant, which is a user’s permission to access resources on their behalf. Having obtained an authorization grant from the user, the API client submits it to generate an access token. Both authorization grant and access token are retrieved from the authorization server using an encrypted connection (HTTPS). Once the access token has been generated, it must be used to authenticate with the resource server (i.e., the SiteScout API).

OAuth 2 defines four authorization grant types: Authorization Code, Implicit, Resource Owner Password Credentials, and Client Credentials. At this time we only support the Client Credentials grant type.

Client Credentials Grant

The Client Credentials grant type is ideal for API clients that require access to their own resources (as opposed to the client acting as a third-party and requesting access on behalf of another user). One of the key advantages of this grant type is a simplified authentication flow that allows the client to proceed directly to token generation with the authorization grant being assumed. It must be well noted that the Client Credentials grant type must exclusively be implemented with applications that guarantee the security of their client credentials.

SiteScout Authorization Server

The SiteScout Authorization Server is located at https://api.sitescout.com/oauth. Please note that all non-secure requests (HTTP) will be redirected to the secure channel (HTTPS) with the help of HTTP status code 302; one should keep in mind that POST requests will not be automatically redirected by most HTTP clients.

When communicating with the authorization server, an API client has the ability to request access to a particular set of scopes, provided these scopes were included in the client registration. The values for all supported scopes are defined as follows:

  • STATS for Reporting,
  • AUDIENCES for Audience Management,
  • CONTROL for Campaign Management.

How do I generate an access token using the Client Credentials grant?

Step 1
Build Authorization header by

  • Combining the client credentials as shown: clientID:clientSecret (e.g., beethoven:letmein)
  • Encoding the combined credentials using Base64 (e.g., YmVldGhvdmVuOmxldG1laW4=)
  • Prepending the encoded value with “Basic” (e.g., Basic YmVldGhvdmVuOmxldG1laW4=)

Step 2
Submit a POST request to https://api.sitescout.com/oauth/token with Authorization header set to the resulting value from Step 1 and form parameter grant_type set to “client_credentials”. Optionally, you can add form parameter scope to indicate which scopes you are requesting access to; the scope values must be space delimited (e.g., STATS AUDIENCES). If parameter scope is not submitted, the client will be issued an access token for all scopes selected at the client registration time. Below is an example request:

POST https://api.sitescout.com/oauth/token HTTP/1.1
Host: api.sitescout.com
Authorization: Basic YmVldGhvdmVuOmxldG1laW4=
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Content-Length: 41

grant_type=client_credentials&scope=STATS

Step 3
If the authorization server is able to authenticate the client and confirm its eligibility to access the requested scopes, a successful JSON response will be returned in the following format:

Field Type Required Description
scope String Yes Space delimited scope values of the access token
access_token String Yes Access token issued by the authorization server
token_type String Yes Type of the token issued (the only supported value is “bearer”)
expires_in Integer Yes Lifetime in seconds of the access token (default value is 3600, i.e., one hour)

{

    "scope": "STATS",
    "access_token": "7ebe55b54ee12a8ee07329f1cefd6de6",
    "token_type": "bearer",
    "expires_in": 3600

}

In case the authorization server cannot process the token generation request, the following errors may be returned:

Status Code Error Body Description
302 None Request was directed to the non-secure endpoint (HTTP)
400 OAuth 2 Error There was a problem with the client’s request. Response body will clarify the error type.
401 OAuth 2 Error No Authorization header was provided

An OAuth 2 error has the following, simplistic JSON format:

Field Type Required Description
error String Yes Error code. Possible values include: invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, and invalid_scope. Complete descriptions of these error codes can be found at http://tools.ietf.org/html/rfc6749#section-5.2
error_description String No Additional, human-readable information about the error

How do I authenticate with the SiteScout API using an access token?

Once a successful response is received from the authorization server for the token generation request, the SiteScout API can now be at the client’s disposal. Every request submitted to the API must contain an Authorization header set to “Bearer [access_token]“, where [access_token] is the value of field access_token from the token generation response. Below is an example Authorization header containing an access token:

Authorization: Bearer 7ebe55b54ee12a8ee07329f1cefd6de6

An access token is only valid for the scopes listed in field scope from the token generation response and it will expire in one hour, but a new token can be generated at any time. The API will respond with an error, if a client cannot be authenticated or is not authorized to access a certain resource:

Status Code Error Body Description
401 SiteScout Error Authorization header is missing or access token is missing, invalid, or has expired
403 SiteScout Error Client is not authorized to access the requested resource

Back to top

Reporting

This part of the SiteScout API provides clients with an ability to retrieve real-time and historical statistics for advertising campaigns. Various types of campaign statistics are available; for instance, one can retrieve campaign statistics per site, per creative, or per offer. Furthermore, several types of statistics can be retrieved on an hourly basis and most of them are provided in both JSON and CSV formats. An API client indicates an intention to receive statistics in the CSV format by either appending “.csv” to path of the resource URI or setting the Accept header to “text/csv”. Below we present the map of the resources associated with the reporting scope of the SiteScout API.

Map of Reporting API

Map of the Reporting API

METHODS

Retrieve Statistics for All Campaigns

Path: /advertisers/{advertiserId}/campaigns/stats
HTTP Method: GET
Accept: application/json and text/csv
Rate limiting: 10 requests per minute, if date range exceeds 14 days
Query Parameters:

Parameter Type Required Description
dateFrom String No Start date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
dateTo String No End date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
timezone String No Timezone to serve statistics in, expressed as either UTC offset (“+-HH:mm”) or timezone name (“CET”). If not provided, defaults to EST.
page Integer No Page number. If not provided, defaults to 1.
pageSize Integer No Number of records per page. If not provided, defaults to 20. Maximum value is 100.
sortBy String No Field to sort the returned list of items by. Valid values are virtually all values present in the returned representation.
sortDirection String No Sorting direction. Two values are accepted: “asc” for ascending and “desc” for descending. If not provided, defaults to “desc”.
status String No Indicates if only campaigns with a certain status should be returned. Accepted values are “online”, “offline”, and “archived”.
campaignIds String No Comma-separated list of campaign IDs to retrieve the statistics for. If provided, filter and status will be ignored.
filter String No Value used to filter campaign names by.
useCache Boolean No Indicates if cached items are permissible. This field should be set to “true” when retrieving paginated results, since it dramatically improves performance. If not provided, defaults to “false”.

Successful Response:

Status Code Content-Type Representation
200 application/json Statistics List (Entity is Campaign with Basic View)
200 text/csv Comma-separated campaignId, name, and statistics

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Statistics for a Campaign

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/stats
HTTP Method: GET
Accept: application/json and text/csv (only for hourly and daily)
Query Parameters:

Parameter Type Required Description
dateFrom String No Start date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
dateTo String No End date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
timezone String No Timezone to serve statistics in, expressed as either UTC offset (“+-HH:mm”) or timezone name (“CET”). If not provided, defaults to EST.
by String No Time slice to aggregate statistics by: “day” or “hour”. If not provided, defaults to none (statistics will be aggregated over the provided date range).
hourly (Deprecated) Boolean No Indicates if hourly statistics should be retrieved or not. If not provided, defaults to “false”. Value will be overridden by parameter “by” if specified.

Successful Response:

Status Code Content-Type Representation
200 application/json Entity Statistics or Hourly Entity Statistics or Daily Entity Statistics (Entity is Campaign with Basic View)
200 text/csv Comma-separated hour or date and statistics

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
406 None Client attempted to retrieve a general stats in CSV format
500 SiteScout Error An unexpected error has occurred

Retrieve Statistics for a Campaign, per Site

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/stats/sites
HTTP Method: GET
Accept: application/json and text/csv
Query Parameters:

Parameter Type Required Description
dateFrom String No Start date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
dateTo String No End date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
timezone String No Timezone to serve statistics in, expressed as either UTC offset (“+-HH:mm”) or timezone name (“CET”). If not provided, defaults to EST.
page Integer No Page number. If not provided, defaults to 1.
pageSize Integer No Number of records per page. If not provided, defaults to 20. Maximum value is 100.
sortBy String No Field to sort the returned list of items by. Valid values are virtually all values present in the returned representation.
sortDirection String No Sorting direction. Two values are accepted: “asc” for ascending and “desc” for descending. If not provided, defaults to “desc”.
status String No Indicates if only site rules with a certain status should be returned. Accepted values are “online”, “offline”, and “archived”.
filter String No Value used to filter domains and site references by.
useCache Boolean No Indicates if cached items are permissible. This field should be set to “true” when retrieving paginated results, since it dramatically improves performance. If not provided, defaults to “false”.

Successful Response:

Status Code Content-Type Representation
200 application/json Statistics List (Entity is Site Rule)
200 text/csv Comma-separated siteRef, domain, and statistics

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Statistics for a Campaign, for a Particular Site

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/stats/sites/{siteRef}
HTTP Method: GET
Accept: application/json and text/csv (only for hourly)
Query Parameters:

Parameter Type Required Description
dateFrom String No Start date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
dateTo String No End date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
timezone String No Timezone to serve statistics in, expressed as either UTC offset (“+-HH:mm”) or timezone name (“CET”). If not provided, defaults to EST.
by String No Time slice to aggregate statistics by: “day” or “hour”. If not provided, defaults to none (statistics will be aggregated over the provided date range).
hourly (Deprecated) Boolean No Indicates if hourly statistics should be retrieved or not. If not provided, defaults to “false”. Value will be overridden by parameter “by” if specified.

Successful Response:

Status Code Content-Type Representation
200 application/json Entity Statistics or Hourly Entity Statistics or Daily Entity Statistics (Entity is Site Rule)
200 text/csv Comma-separated hour or date and statistics

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
406 None Client attempted to retrieve a general stats in CSV format
500 SiteScout Error An unexpected error has occurred

Retrieve Statistics for a Campaign, for a Particular Site, per Placement

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/stats/sites/{siteRef}/placements
HTTP Method: GET
Accept: application/json
Query Parameters:

Parameter Type Required Description
dateFrom String No Start date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
dateTo String No End date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
timezone String No Timezone to serve statistics in, expressed as either UTC offset (“+-HH:mm”) or timezone name (“CET”). If not provided, defaults to EST.

Successful Response:

Status Code Content-Type Representation
200 application/json Statistics List (Entity is Site Rule)

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Statistics for a Campaign, for a Particular Site, per Creative

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/stats/sites/{siteRef}/creatives
HTTP Method: GET
Accept: application/json and text/csv
Query Parameters:

Parameter Type Required Description
dateFrom String No Start date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
dateTo String No End date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
timezone String No Timezone to serve statistics in, expressed as either UTC offset (“+-HH:mm”) or timezone name (“CET”). If not provided, defaults to EST.

Successful Response:

Status Code Content-Type Representation
200 application/json Statistics List (Entity is Creative)
200 text/csv Comma-separated creativeId, width, height, format, and statistics

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Statistics for a Campaign, per Creative

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/stats/creatives
HTTP Method: GET
Accept: application/json and text/csv
Query Parameters:

Parameter Type Required Description
dateFrom String No Start date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
dateTo String No End date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
timezone String No Timezone to serve statistics in, expressed as either UTC offset (“+-HH:mm”) or timezone name (“CET”). If not provided, defaults to EST.
page Integer No Page number. If not provided, defaults to 1.
pageSize Integer No Number of records per page. If not provided, defaults to 20. Maximum value is 100.
sortBy String No Field to sort the returned list of items by. Valid values are virtually all values present in the returned representation.
sortDirection String No Sorting direction. Two values are accepted: “asc” for ascending and “desc” for descending. If not provided, defaults to “desc”.
status String No Indicates if only creatives with a certain status should be returned. Accepted values are “online”, “offline”, and “archived”.
dimensions String No Value used to filter creative dimensions by, expressed as width x height (e.g., “300×250″).
useCache Boolean No Indicates if cached items are permissible. This field should be set to “true” when retrieving paginated results, since it dramatically improves performance. If not provided, defaults to “false”.

Successful Response:

Status Code Content-Type Representation
200 application/json Statistics List (Entity is Creative)
200 text/csv Comma-separated creativeId, width, height, format, and statistics

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Statistics for a Campaign, for a Particular Creative

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/stats/creatives/{creativeId}
HTTP Method: GET
Accept: application/json and text/csv (only for hourly)
Query Parameters:

Parameter Type Required Description
dateFrom String No Start date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
dateTo String No End date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
timezone String No Timezone to serve statistics in, expressed as either UTC offset (“+-HH:mm”) or timezone name (“CET”). If not provided, defaults to EST.
by String No Time slice to aggregate statistics by: “day” or “hour”. If not provided, defaults to none (statistics will be aggregated over the provided date range).
hourly (Deprecated) Boolean No Indicates if hourly statistics should be retrieved or not. If not provided, defaults to “false”. Value will be overridden by parameter “by” if specified.

Successful Response:

Status Code Content-Type Representation
200 application/json Entity Statistics or Hourly Entity Statistics or Daily Entity Statistics (Entity is Creative)
200 text/csv Comma-separated hour or date and statistics

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or creative cannot be found
406 None Client attempted to retrieve a general stats in CSV format
500 SiteScout Error An unexpected error has occurred

Retrieve Statistics for a Campaign, per Offer

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/stats/offers
HTTP Method: GET
Accept: application/json and text/csv
Query Parameters:

Parameter Type Required Description
dateFrom String No Start date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
dateTo String No End date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
timezone String No Timezone to serve statistics in, expressed as either UTC offset (“+-HH:mm”) or timezone name (“CET”). If not provided, defaults to EST.

Successful Response:

Status Code Content-Type Representation
200 application/json Statistics List (Entity is Offer)
200 text/csv Comma-separated offerId, name, and statistics

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Back to top

Audience Management

This part of the SiteScout API is concerned with (1) managing user audiences—retrieval, creation, and modification of audiences—and (2) retrieving audience statistics. Below we present the map of the resources associated with the audience management scope of the SiteScout API.

Map of the Audience Management API

Map of the Audience Management API

METHODS

Retrieve Audiences

Path: /advertisers/{advertiserId}/audiences
HTTP Method: GET
Accept: application/json
Query Parameters:

Parameter Type Required Description
page Integer No Page number. If not provided, defaults to 1.
pageSize Integer No Number of records per page. If not provided, defaults to 20. Maximum value is 100.
sortBy String No Field to sort the returned list of items by. Valid values are virtually all values present in the returned representation.
sortDirection String No Sorting direction. Two values are accepted: “asc” for ascending and “desc” for descending. If not provided, defaults to “desc”.
filter String No Value used to filter audience names by.
visible Boolean No Indicates if only visible audiences should be retrieved. If not provided, both active and archived audiences will be retrieved.

Successful Response:

Status Code Content-Type Representation
200 application/json Paginated List of Audiences

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser cannot be found
500 SiteScout Error An unexpected error has occurred

Create an Audience

Path: /advertisers/{advertiserId}/audiences
HTTP Method: POST
Content-Type: application/json
Accept: application/json
Body: Audience

Successful Response:

Status Code Content-Type Representation
201 application/json Audience

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve an Audience

Path: /advertisers/{advertiserId}/audiences/{audienceId}
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Audience

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or audience cannot be found
500 SiteScout Error An unexpected error has occurred

Update an Audience (Partial representation allowed)

Path: /advertisers/{advertiserId}/audiences/{audienceId}
HTTP Method: PATCH
Content-Type: application/json
Body: Audience

Successful Response:

Status Code Content-Type Representation
200 application/json Audience

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or audience cannot be found
500 SiteScout Error An unexpected error has occurred

Update an Audience (Full representation required)

Path: /advertisers/{advertiserId}/audiences/{audienceId}
HTTP Method: PUT
Content-Type: application/json
Body: Audience

Successful Response:

Status Code Content-Type Representation
200 application/json Audience

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or audience cannot be found
500 SiteScout Error An unexpected error has occurred

Delete an Audience

Path: /advertisers/{advertiserId}/audiences/{audienceId}
HTTP Method: DELETE
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Audience

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or audience cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve HTML Tag for an Audience

Path: /advertisers/{advertiserId}/audiences/{audienceId}/tag
HTTP Method: GET
Accept: text/html
Query Parameters:

Parameter Type Required Description
type String No Type of the tag requested: “script”, “link”, or “image”. If not provided, defaults to “script”.
secure Boolean No Indicates if a secure URL is requested for link or image tag. Defaults to false.
redirect String No Redirect URL for a anchor tag.
text String No Text that will be placed inside of the anchor tag.

Successful Response:

Status Code Content-Type Representation
200 text/html HTML Tag

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or audience cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Statistics for All Audiences

Path: /advertisers/{advertiserId}/audiences/stats
HTTP Method: GET
Accept: application/json and text/csv
Query Parameters:

Parameter Type Required Description
dateFrom String No Start date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
dateTo String No End date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
page Integer No Page number. If not provided, defaults to 1.
pageSize Integer No Number of records per page. If not provided, defaults to 20. Maximum value is 100.
sortBy String No Field to sort the returned list of items by. Valid values are virtually all values present in the returned representation.
sortDirection String No Sorting direction. Two values are accepted: “asc” for ascending and “desc” for descending. If not provided, defaults to “desc”.
filter String No Value used to filter audience names by.
visible Boolean No Indicates if only statistics for visible audiences should be retrieved. If not provided, statistics for both active and archived audiences will be retrieved.

Successful Response:

Status Code Content-Type Representation
200 application/json Statistics List (Entity is Audience)
200 text/csv Comma-separated audienceId, name, and statistics

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Statistics for an Audience

Path: /advertisers/{advertiserId}/audiences/{audienceId}/stats
HTTP Method: GET
Accept: application/json
Query Parameters:

Parameter Type Required Description
dateFrom String No Start date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.
dateTo String No End date of the statistics collection, formatted as yyyyMMdd. If not provided, defaults to today’s date.

Successful Response:

Status Code Content-Type Representation
200 application/json Entity Statistics (Entity is Audience)

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or audience cannot be found
500 SiteScout Error An unexpected error has occurred

Back to top

Campaign Management

The Campaign Management part of the SiteScout API provides clients access to the miscellaneous root sources and all advertiser-level resources, excluding audiences and statistics. Among the root sources are active exchanges, sites, advertisers, and data providers. Advertiser-level resources include offers, domain lists, creatives, and campaigns. In addition, API clients have an ability to retrieve an advertiser’s balance. This part of the API is also known as the Control API. Below you will find the following API maps: Map of Root Resources, Map of Advertiser-Level Resources, Map of Campaign Resources, and Map of Targeting Resources.
 

Map of Root Resources

Map of Root Resources

Map of Advertiser-Level Resources

Map of Advertiser-Level Resources

Map of Campaign Resources

Map of Campaign Resources

Map of Targeting Resources

Map of Targeting Resources

 

METHODS

Retrieve Active Ad Exchanges

Path: /exchanges
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Array of Exchanges

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
500 SiteScout Error An unexpected error has occurred

Retrieve a Site

Path: /sites/{siteRef}
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Site

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Site cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Denied Attributes for a Site

Path: /sites/{siteRef}/deniedAttributes
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Denied Attributes

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Site cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Data Providers

Path: /providers
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Array of Data Providers

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
500 SiteScout Error An unexpected error has occurred

Retrieve Contextual Entries for a Provider

Path: /providers/{providerId}/contextual
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Paginated List of Contextual Entries

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Data Provider cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Demographic Audiences for a Provider

Path: /providers/{providerId}/demographic
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Paginated List of Demographic Audiences

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Data Provider cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Advertiser’s Balance

Path: /advertisers/{advertiserId}/balance
HTTP Method: GET
Accept: text/plain

Successful Response:

Status Code Content-Type Representation
200 text/plain Double, formatted as “0.00″

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Offers

Path: /advertisers/{advertiserId}/offers
HTTP Method: GET
Accept: application/json
Query Parameters:

Parameter Type Required Description
page Integer No Page number. If not provided, defaults to 1.
pageSize Integer No Number of records per page. If not provided, defaults to 20. Maximum value is 100.
sortBy String No Field to sort the returned list of items by. Valid values are virtually all values present in the returned representation.
sortDirection String No Sorting direction. Two values are accepted: “asc” for ascending and “desc” for descending. If not provided, defaults to “desc”.
filter String No Value used to filter offer names by.

Successful Response:

Status Code Content-Type Representation
200 application/json Paginated List of Offers

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser cannot be found
500 SiteScout Error An unexpected error has occurred

Create an Offer

Path: /advertisers/{advertiserId}/offers
HTTP Method: POST
Content-Type: application/json
Accept: application/json
Body: Offer

Successful Response:

Status Code Content-Type Representation
201 application/json Offer

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve an Offer

Path: /advertisers/{advertiserId}/offers/{offerId}
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Offer

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or offer cannot be found
500 SiteScout Error An unexpected error has occurred

Update an Offer (Partial representation allowed)

Path: /advertisers/{advertiserId}/offers/{offerId}
HTTP Method: PATCH
Content-Type: application/json
Body: Offer

Successful Response:

Status Code Content-Type Representation
200 application/json Offer

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or offer cannot be found
500 SiteScout Error An unexpected error has occurred

Update an Offer (Full representation required)

Path: /advertisers/{advertiserId}/offers/{offerId}
HTTP Method: PUT
Content-Type: application/json
Body: Offer

Successful Response:

Status Code Content-Type Representation
200 application/json Offer

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or offer cannot be found
500 SiteScout Error An unexpected error has occurred

Delete an Offer

Path: /advertisers/{advertiserId}/offers/{offerId}
HTTP Method: DELETE
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Offer

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or offer cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Conversion Tag for an Offer

Path: /advertisers/{advertiserId}/offers/{offerId}/conversionTag
HTTP Method: GET
Accept: text/html
Query Parameters:

Parameter Type Required Description
secure Boolean No Indicates if a secure URL for the image tag is requested. Defaults to false.
usePostback Boolean No Indicates if the postback query parameter should be added to the pixel URL. Defaults to false.

Successful Response:

Status Code Content-Type Representation
200 text/html HTML Image Tag

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or offer cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Clickthru Tag for an Offer

Path: /advertisers/{advertiserId}/offers/{offerId}/clickthruTag
HTTP Method: GET
Accept: text/html
Query Parameters:

Parameter Type Required Description
type String Yes Type of the clickthru tag requested: “script” or “redirect”.
secure Boolean No Indicates if a secure URL for the anchor tag is requested. Defaults to false.
link String No The link that the user’s browser will be directed to upon a click.
text String No Text that will be placed inside of the anchor tag.

Successful Response:

Status Code Content-Type Representation
200 text/html HTML Anchor Tag

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or offer cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Domain Lists

Path: /advertisers/{advertiserId}/domainLists
HTTP Method: GET
Accept: application/json
Query Parameters:

Parameter Type Required Description
page Integer No Page number. If not provided, defaults to 1.
pageSize Integer No Number of records per page. If not provided, defaults to 20. Maximum value is 100.
sortBy String No Field to sort the returned list of items by. Valid values are virtually all values present in the returned representation.
sortDirection String No Sorting direction. Two values are accepted: “asc” for ascending and “desc” for descending. If not provided, defaults to “desc”.
filter String No Value used to filter domain list names by.
type String No Indicates if only domain lists of provided type should be retrieved. Allowed values are: “whitelist” and “blacklist”.

Successful Response:

Status Code Content-Type Representation
200 application/json Paginated List of Domain Lists

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve a Domain List

Path: /advertisers/{advertiserId}/domainLists/{domainListId}
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Domain List

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or domain list cannot be found
500 SiteScout Error An unexpected error has occurred

Add or replace a Domain List (Partial representation allowed)

Path: /advertisers/{advertiserId}/domainLists/{domainListId}
HTTP Method: PATCH
Content-Type: application/json
Body: Domain List

Successful Response:

Status Code Content-Type Representation
200 application/json Domain List

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or domain list cannot be found
500 SiteScout Error An unexpected error has occurred

Update a Domain List (Full representation required)

Path: /advertisers/{advertiserId}/domainLists/{domainListId}
HTTP Method: PUT
Content-Type: application/json
Body: Domain List

Successful Response:

Status Code Content-Type Representation
200 application/json Domain List

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or domain list cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Domains for a Domain List

Path: /advertisers/{advertiserId}/domainLists/{domainListId}/domains
HTTP Method: GET
Accept: application/json
Query Parameters:

Parameter Type Required Description
page Integer No Page number. If not provided, defaults to 1.
pageSize Integer No Number of records per page. If not provided, defaults to 20. Maximum value is 100.

Successful Response:

Status Code Content-Type Representation
200 application/json Paginated List of Strings

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or domain list cannot be found
500 SiteScout Error An unexpected error has occurred

Add a Domain to a Domain List

Path: /advertisers/{advertiserId}/domainLists/{domainListId}/domains
HTTP Method: POST
Content-Type: text/plain
Body: String

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
400 SiteScout Error Empty or null string is provided
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or domain list cannot be found
500 SiteScout Error An unexpected error has occurred

Replace Domains in a Domain List

Path: /advertisers/{advertiserId}/domainLists/{domainListId}/domains
HTTP Method: PUT
Content-Type: application/json
Body: Array of Strings

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or domain list cannot be found
500 SiteScout Error An unexpected error has occurred

Delete a Domain from a Domain List

Path: /advertisers/{advertiserId}/domainLists/{domainListId}/domains/{domain}
HTTP Method: DELETE

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or domain list cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Creatives

Path: /advertisers/{advertiserId}/creatives
HTTP Method: GET
Accept: application/json
Query Parameters:

Parameter Type Required Description
page Integer No Page number. If not provided, defaults to 1.
pageSize Integer No Number of records per page. If not provided, defaults to 20. Maximum value is 100.
sortBy String No Field to sort the returned list of items by. Valid values are virtually all values present in the returned representation.
sortDirection String No Sorting direction. Two values are accepted: “asc” for ascending and “desc” for descending. If not provided, defaults to “desc”.
filter String No Value used to filter creative labels by.
type String No Creative type to filter creatives by. Allowed values are: “banner”, “tag”, “expandable”, “ad_builder”, or “video”.
dimensions String No Indicates if only creatives that are of the provided dimensions should be returned.
vaultPath String No Indicates if only creatives that reside in a certain AdVault folder should be returned.

Successful Response:

Status Code Content-Type Representation
200 application/json Paginated List of Creatives

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser cannot be found
500 SiteScout Error An unexpected error has occurred

Add a Creative

Path: /advertisers/{advertiserId}/creatives
HTTP Method: POST
Content-Type: application/json
Accept: application/json
Body: Creative
Special Notes: When adding a banner creative or a video creative, the image, movie, or video must first be uploaded using this method and communicated via field “assetUrl”.

Successful Response:

Status Code Content-Type Representation
201 application/json Creative

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve a Creative

Path: /advertisers/{advertiserId}/creatives/{creativeId}
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Creative

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or creative cannot be found
500 SiteScout Error An unexpected error has occurred

Update a Creative (Partial representation allowed)

Path: /advertisers/{advertiserId}/creatives/{creativeId}
HTTP Method: PATCH
Content-Type: application/json
Body: Creative

Successful Response:

Status Code Content-Type Representation
200 application/json Creative

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or creative cannot be found
500 SiteScout Error An unexpected error has occurred

Update a Creative (Full representation required)

Path: /advertisers/{advertiserId}/creatives/{creativeId}
HTTP Method: PUT
Content-Type: application/json
Body: Creative

Successful Response:

Status Code Content-Type Representation
200 application/json Creative

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or creative cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Creative Assets

Path: /advertisers/{advertiserId}/creatives/assets
HTTP Method: GET
Accept: application/json
Query Parameters:

Parameter Type Required Description
page Integer No Page number. If not provided, defaults to 1.
pageSize Integer No Number of records per page. If not provided, defaults to 20. Maximum value is 100.
sortBy String No Field to sort the returned list of items by. Valid values are virtually all values present in the returned representation.
sortDirection String No Sorting direction. Two values are accepted: “asc” for ascending and “desc” for descending. If not provided, defaults to “desc”.
dimensions String No Indicates if only creative assets that are of the provided dimensions should be returned.

Successful Response:

Status Code Content-Type Representation
200 application/json Paginated List of Creative Assets

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser cannot be found
500 SiteScout Error An unexpected error has occurred

Upload a Creative Asset

Path: /advertisers/{advertiserId}/creatives/assets
HTTP Method: POST
Content-Type: image/jpeg, image/png, image/gif, application/x-shockwave-flash, video/mp4, application/zip
Accept: application/json
Body: Image, Flash Movie, MP4 Video, or ZIP Archive

Successful Response:

Status Code Content-Type Representation
201 application/json Creative Asset or Array of Creative Assets, if multiple files were submitted in an archive

Error Responses:

Status Code Error Body Description
400 SiteScout Error Submitted file is invalid or corrupted
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Campaigns

Path: /advertisers/{advertiserId}/campaigns
HTTP Method: GET
Accept: application/json
Query Parameters:

Parameter Type Required Description
page Integer No Page number. If not provided, defaults to 1.
pageSize Integer No Number of records per page. If not provided, defaults to 20. Maximum value is 100.
sortBy String No Field to sort the returned list of items by. Valid values are virtually all values present in the returned representation.
sortDirection String No Sorting direction. Two values are accepted: “asc” for ascending and “desc” for descending. If not provided, defaults to “desc”.
filter String No Value used to filter campaign names by.
status String No Indicates if only campaigns with a certain status should be returned. Accepted values are “online”, “offline”, and “archived”.

Successful Response:

Status Code Content-Type Representation
200 application/json Paginated List of Campaigns with Basic View

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser cannot be found
500 SiteScout Error An unexpected error has occurred

Create a Campaign

Path: /advertisers/{advertiserId}/campaigns
HTTP Method: POST
Content-Type: application/json
Accept: application/json
Body: Campaign

Successful Response:

Status Code Content-Type Representation
201 application/json Campaign with Complete View

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, audience (from “audienceCapture”), or offer (from “viewthruConfig”) cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve a Campaign

Path: /advertisers/{advertiserId}/campaigns/{campaignId}
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Campaign with Complete View

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Update a Campaign (Partial representation allowed)

Path: /advertisers/{advertiserId}/campaigns/{campaignId}
HTTP Method: PATCH
Content-Type: application/json
Body: Campaign

Successful Response:

Status Code Content-Type Representation
200 application/json Campaign with Complete View

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, audience (from “audienceCapture”), or offer (from “viewthruConfig”) cannot be found
500 SiteScout Error An unexpected error has occurred

Update a Campaign (Full representation required)

Path: /advertisers/{advertiserId}/campaigns/{campaignId}
HTTP Method: PUT
Content-Type: application/json
Body: Campaign

Successful Response:

Status Code Content-Type Representation
200 application/json Campaign with Complete View

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, audience (from “audienceCapture”), or offer (from “viewthruConfig”) cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Campaign’s Creatives

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/creatives
HTTP Method: GET
Accept: application/json
Query Parameters:

Parameter Type Required Description
page Integer No Page number. If not provided, defaults to 1.
pageSize Integer No Number of records per page. If not provided, defaults to 20. Maximum value is 100.
sortBy String No Field to sort the returned list of items by. Valid values are virtually all values present in the returned representation.
sortDirection String No Sorting direction. Two values are accepted: “asc” for ascending and “desc” for descending. If not provided, defaults to “desc”.
filter String No Value used to filter creative labels by.
status String No Indicates if only creatives with a certain status should be returned. Accepted values are “online”, “offline”, and “archived”.
type String No Creative type to filter creatives by. Allowed values are: “banner”, “tag”, “expandable”, “ad_builder”, or “video”.
dimensions String No Indicates if only creatives that are of the provided dimensions should be returned.
vaultPath String No Indicates if only creatives that reside in a certain AdVault folder should be returned.

Successful Response:

Status Code Content-Type Representation
200 application/json Paginated List of Creatives

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Add a Creative to a Campaign

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/creatives
HTTP Method: POST
Content-Type: application/json
Accept: application/json
Body: Creative
Special Notes: In order to add an AdVault creative to a campaign, submit the creative’s “creativeId” in the representation. When adding a new banner creative, the image or movie must first be uploaded using this method and communicated via field “assetUrl”.

Successful Response:

Status Code Content-Type Representation
201 application/json Creative

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or creative cannot be found
409 SiteScout Error Submitted creative already exists in campaign
500 SiteScout Error An unexpected error has occurred

Retrieve a Campaign’s Creative

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/creatives/{creativeId}
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Creative

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or creative cannot be found
500 SiteScout Error An unexpected error has occurred

Update a Campaign’s Creative (Partial representation allowed)

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/creatives/{creativeId}
HTTP Method: PATCH
Content-Type: application/json
Body: Creative

Successful Response:

Status Code Content-Type Representation
200 application/json Creative

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or creative cannot be found
500 SiteScout Error An unexpected error has occurred

Update a Campaign’s Creative (Full representation required)

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/creatives/{creativeId}
HTTP Method: PUT
Content-Type: application/json
Body: Creative

Successful Response:

Status Code Content-Type Representation
200 application/json Creative

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or creative cannot be found
500 SiteScout Error An unexpected error has occurred

Remove a Creative from a Campaign

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/creatives/{creativeId}
HTTP Method: DELETE
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Creative

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or creative cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Campaign’s Domain List

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/domainList
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Domain List

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or domain list cannot be found
500 SiteScout Error An unexpected error has occurred

Add Domain List to Campaign

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/domainList
HTTP Method: POST
Content-Type: application/json
Accept: application/json
Body: Domain List
Special Notes: In order to add an existing domain list to a campaign, submit the domain list’s “domainListId” in the representation.

Successful Response:

Status Code Content-Type Representation
200 application/json Domain List
201 application/json Domain List

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or domain list cannot be found
500 SiteScout Error An unexpected error has occurred

Update Campaign’s Domain List (Partial representation allowed)

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/domainList
HTTP Method: PATCH
Content-Type: application/json
Body: Domain List

Successful Response:

Status Code Content-Type Representation
200 application/json Domain List

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or domain list cannot be found
500 SiteScout Error An unexpected error has occurred

Remove Domain List from Campaign

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/domainList
HTTP Method: DELETE
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Domain List

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Domains for Campaign’s Domain List

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/domainList/domains
HTTP Method: GET
Accept: application/json
Query Parameters:

Parameter Type Required Description
page Integer No Page number. If not provided, defaults to 1.
pageSize Integer No Number of records per page. If not provided, defaults to 20. Maximum value is 100.

Successful Response:

Status Code Content-Type Representation
200 application/json Paginated List of Strings

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or domain list cannot be found
500 SiteScout Error An unexpected error has occurred

Add a Domain to Campaign’s Domain List

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/domainList/domains
HTTP Method: POST
Content-Type: text/plain
Body: String

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
400 SiteScout Error Empty or null string is provided
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or domain list cannot be found
500 SiteScout Error An unexpected error has occurred

Replace Domains in Campaign’s Domain List

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/domainList/domains
HTTP Method: PUT
Content-Type: application/json
Body: Array of Strings

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or domain list cannot be found
500 SiteScout Error An unexpected error has occurred

Delete a Domain from Campaign’s Domain List

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/domainList/domains/{domain}
HTTP Method: DELETE

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or domain list cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Campaign’s Ad Exchanges (Run-Of-Network)

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/sources/exchanges
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Array of Exchanges

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Add an Ad Exchange to a Campaign

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/sources/exchanges
HTTP Method: POST
Content-Type: application/json
Body: Exchange
Special Notes: The submitted representation must contain “exchangeId”.

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or exchange cannot be found
500 SiteScout Error An unexpected error has occurred

Replace Campaign’s Ad Exchanges

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/sources/exchanges
HTTP Method: PUT
Content-Type: application/json
Body: Array of Exchanges
Special Notes: The submitted representations must contain “exchangeId”.

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or exchange cannot be found
500 SiteScout Error An unexpected error has occurred

Remove Ad Exchanges from a Campaign

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/sources/exchanges
HTTP Method: DELETE

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Remove an Ad Exchange from a Campaign

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/sources/exchanges/{exchangeId}
HTTP Method: DELETE

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or exchange cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Site Rules

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/sources/siteRules
HTTP Method: GET
Accept: application/json
Query Parameters:

Parameter Type Required Description
page Integer No Page number. If not provided, defaults to 1.
pageSize Integer No Number of records per page. If not provided, defaults to 20. Maximum value is 100.
sortBy String No Field to sort the returned list of items by. Valid values are virtually all values present in the returned representation.
sortDirection String No Sorting direction. Two values are accepted: “asc” for ascending and “desc” for descending. If not provided, defaults to “desc”.
status String No Indicates if only site rules with a certain status should be returned. Accepted values are “online”, “offline”, and “archived”.
filter String No Value used to filter domains/app names and site references by.

Successful Response:

Status Code Content-Type Representation
200 application/json Paginated List of Site Rules

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of query parameters has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Add a Site Rule

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/sources/siteRules
HTTP Method: POST
Content-Type: application/json
Accept: application/json
Body: Site Rule

Successful Response:

Status Code Content-Type Representation
201 application/json Site Rule

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or site cannot be found
409 SiteScout Error Site rule already exists in campaign
500 SiteScout Error An unexpected error has occurred

Replace Site Rules

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/sources/siteRules
HTTP Method: PUT
Content-Type: application/json
Accept: application/json
Body: Array of Site Rules

Successful Response:

Status Code Content-Type Representation
200 application/json Array of Site Rules

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or site cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve a Site Rule

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/sources/siteRules/{ruleId}
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Site Rule

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or site rule cannot be found
500 SiteScout Error An unexpected error has occurred

Update a Site Rule (Partial representation allowed)

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/sources/siteRules/{ruleId}
HTTP Method: PATCH
Content-Type: application/json
Body: Site Rule

Successful Response:

Status Code Content-Type Representation
200 application/json Site Rule

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or site rule cannot be found
500 SiteScout Error An unexpected error has occurred

Update a Site Rule (Full representation required)

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/sources/siteRules/{ruleId}
HTTP Method: PUT
Content-Type: application/json
Body: Site Rule

Successful Response:

Status Code Content-Type Representation
200 application/json Site Rule

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or site rule cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Traffic Type Targeting

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/trafficType
HTTP Method: GET
Accept: text/plain

Successful Response:

Status Code Content-Type Representation
200 text/plain Traffic Type

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Set Traffic Type Targeting

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/trafficType
HTTP Method: PUT
Content-Type: text/plain
Accept: text/plain
Body: Traffic Type

Successful Response:

Status Code Content-Type Representation
200 text/plain Traffic Type

Error Responses:

Status Code Error Body Description
400 SiteScout Error Invalid traffic type value is submitted
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Page Position Targeting

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/pagePositions
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Array of Page Positions

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Set Page Position Targeting

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/pagePositions
HTTP Method: PUT
Content-Type: application/json
Accept: application/json
Body: Array of Page Positions

Successful Response:

Status Code Content-Type Representation
200 application/json Array of Page Positions

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Dayparting Rules

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/dayparting
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Array of Dayparting Rules

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Add a Dayparting Rule

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/dayparting
HTTP Method: POST
Content-Type: application/json
Accept: application/json
Body: Dayparting Rule

Successful Response:

Status Code Content-Type Representation
200 application/json Dayparting Rule

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Replace Dayparting Rules

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/dayparting
HTTP Method: PUT
Content-Type: application/json
Accept: application/json
Body: Array of Dayparting Rules

Successful Response:

Status Code Content-Type Representation
200 application/json Array of Dayparting Rules

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Remove a Dayparting Rule

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/dayparting
HTTP Method: DELETE
Content-Type: application/json
Body: Dayparting Rule

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Retargeting Rules

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/audiences
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Array of Retargeting Rules

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Add a Retargeting Rule

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/audiences
HTTP Method: POST
Content-Type: application/json
Accept: application/json
Body: Retargeting Rule

Successful Response:

Status Code Content-Type Representation
200 application/json Retargeting Rule

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or audience cannot be found
500 SiteScout Error An unexpected error has occurred

Replace Retargeting Rules

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/audiences
HTTP Method: PUT
Content-Type: application/json
Accept: application/json
Body: Array of Retargeting Rules

Successful Response:

Status Code Content-Type Representation
200 application/json Array of Retargeting Rules

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or audience cannot be found
500 SiteScout Error An unexpected error has occurred

Remove Retargeting Rules

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/audiences
HTTP Method: DELETE
Content-Type: application/json
Body: Retargeting Rule

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser, campaign, or audience cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Geo Rules

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/geo
HTTP Method: GET
Accept: application/json
Query Parameters:

Parameter Type Required Description
page Integer No Page number. If not provided, defaults to 1.
pageSize Integer No Number of records per page. If not provided, defaults to 20. Maximum value is 100.
sortBy String No Field to sort the returned list of items by. Valid values are virtually all values present in the returned representation.
sortDirection String No Sorting direction. Two values are accepted: “asc” for ascending and “desc” for descending. If not provided, defaults to “desc”.

Successful Response:

Status Code Content-Type Representation
200 application/json Paginated List of Geo Rules

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Add a Geo Rule

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/geo
HTTP Method: POST
Content-Type: application/json
Accept: application/json
Body: Geo Rule

Successful Response:

Status Code Content-Type Representation
200 application/json Geo Rule

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Replace Geo Rules

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/geo
HTTP Method: PUT
Content-Type: application/json
Accept: application/json
Body: Array of Geo Rules

Successful Response:

Status Code Content-Type Representation
200 application/json Array of Geo Rules

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Remove a Geo Rule by Example

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/geo
HTTP Method: DELETE
Content-Type: application/json
Body: Geo Rule

Successful Response:

Status Code Content-Type Representation
200 application/json Array of Geo Rules

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Coordinates Rules

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/geo/coordinates
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Array of Coordinates Rules

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Add a Coordinates Rule

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/geo/coordinates
HTTP Method: POST
Content-Type: application/json
Accept: application/json
Body: Coordinates Rule

Successful Response:

Status Code Content-Type Representation
200 application/json Coordinates Rule

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Replace Coordinates Rules

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/geo/coordinates
HTTP Method: PUT
Content-Type: application/json
Accept: application/json
Body: Array of Coordinates Rules

Successful Response:

Status Code Content-Type Representation
200 application/json Array of Coordinates Rules

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Remove a Coordinates Rule

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/geo/coordinates
HTTP Method: DELETE
Content-Type: application/json
Body: Coordinates Rule

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Demographic Rules (v1)

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/demographic
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Array of Demographic Rules

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Add a Demographic Rule (v1)

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/demographic
HTTP Method: POST
Content-Type: application/json
Accept: application/json
Body: Demographic Rule

Successful Response:

Status Code Content-Type Representation
200 application/json Demographic Rule

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Replace Demographic Rules (v1)

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/demographic
HTTP Method: PUT
Content-Type: application/json
Accept: application/json
Body: Array of Demographic Rules

Successful Response:

Status Code Content-Type Representation
200 application/json Array of Demographic Rules

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Remove a Demographic Rule (v1)

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/demographic
HTTP Method: DELETE
Content-Type: application/json
Body: Demographic Rule

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Demographic Targeting (v2)

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/demographic
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Demographic Targeting

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found, or demographic targeting has not been set
500 SiteScout Error An unexpected error has occurred

Set Demographic Targeting (v2)

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/demographic
HTTP Method: PUT
Content-Type: application/json
Accept: application/json
Body: Demographic Targeting

Successful Response:

Status Code Content-Type Representation
200 application/json Demographic Targeting

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Remove Demographic Targeting (v2)

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/demographic
HTTP Method: DELETE
Content-Type: application/json

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Demographic Data CPM

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/demographic/price
HTTP Method: GET
Accept: text/plain

Successful Response:

Status Code Content-Type Representation
200 text/plain Double, formatted as “0.00″

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Contextual Targeting

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/contextual
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Contextual Targeting

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found, or contextual targeting has not been set
500 SiteScout Error An unexpected error has occurred

Set Contextual Targeting

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/contextual
HTTP Method: PUT
Content-Type: application/json
Accept: application/json
Body: Contextual Targeting

Successful Response:

Status Code Content-Type Representation
200 application/json Contextual Targeting

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Remove Contextual Targeting

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/contextual
HTTP Method: DELETE
Content-Type: application/json

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Contextual Data CPM

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/contextual/price
HTTP Method: GET
Accept: text/plain

Successful Response:

Status Code Content-Type Representation
200 text/plain Double, formatted as “0.00″

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Retrieve Device Targeting

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/device
HTTP Method: GET
Accept: application/json

Successful Response:

Status Code Content-Type Representation
200 application/json Device Targeting

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found, or device targeting has not been set
500 SiteScout Error An unexpected error has occurred

Set Device Targeting

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/device
HTTP Method: PUT
Content-Type: application/json
Accept: application/json
Body: Device Targeting

Successful Response:

Status Code Content-Type Representation
200 application/json Device Targeting

Error Responses:

Status Code Error Body Description
400 SiteScout Error Validation of the submitted JSON representation has failed
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Remove Device Targeting

Path: /advertisers/{advertiserId}/campaigns/{campaignId}/targeting/device
HTTP Method: DELETE
Content-Type: application/json

Successful Response:

Status Code Content-Type Representation
200 None None

Error Responses:

Status Code Error Body Description
403 SiteScout Error Client is not authorized to access the requested resource
404 SiteScout Error Advertiser or campaign cannot be found
500 SiteScout Error An unexpected error has occurred

Back to top

Representations

This section of the SiteScout API documentation enumerates all employed JSON representations. Please make note of the fact that we reserve the right to augment any representation with one or more fields of any type. Thus, clients must be capable of ignoring unrecognized JSON fields.

Atomic Contextual Rule

Field Type Required Description
type String Yes Contextual rule type, must always be set to “atomic”
blocked Boolean No Indicates if the contextual entry should be blocked or not
minWeight Integer Yes Minimal confidence level for a contextual entry
contextualEntryId Integer Yes Specifies the contextual target’s id in the contextual rule

{

    "type": "atomic",
    "blocked": false,
    "minWeight": 100,
    "contextualEntryId": 101

}

 

Atomic Demographic Rule

Field Type Required Description
type String Yes Demographic rule type, must always be set to “atomic”
blocked Boolean No Indicates if the demographic audience should be blocked or not
demographicId Integer Yes Specifies the ID of demographic audience to be targeted by the demographic rule

{

    "type": "atomic",
    "blocked": false,
    "demographicId": 99

}

 

Audience

Field Type Required Description
audienceId Integer GET Audience ID
name String GET, POST, PUT Audience’s name
visible Boolean GET, PUT Indicates if the audience is visible (active) or not
links Array of Links GET Array of appropriate links, enabling dynamic discovery for HATEOAS

{

    "links": [{
        "href": "http://api.sitescout.com/advertisers/1/audiences/9999",
        "rel": "self"
    }],
    "audienceId": 9999,
    "name": "Football Fans",
    "visible": true

}

 

Audience Capture

Field Type Required Description
clickAudience Integer No Audience ID for creative clicks
landingPageClickAudience Integer No Audience ID for secondary clicks
conversionAudience Integer No Audience ID for conversions

{

    "conversionAudience": 9999,
    "clickAudience": 9998

}

 

Audience Statistics

Field Type Required Description
newVisitors Integer Yes Number of new users added to this audience
totalVisitors Integer Yes Total number of users matched for this audience

{

    "newVisitors": 11,
    "totalVisitors": 15

}

 

Audio Playback Mode (Enum)

Value Description
auto Start audio playback automatically, i.e., on page load
on_rollover Start audio playback when user hovers over the video
user_initiated Start audio playback on user interaction (i.e., when user adjusts volume controls in the video player)
mute Disable audio

 

Browser (Enum)

Value Description
ie Microsoft Internet Explorer
chrome Google Chrome
firefox Firefox
safari Safari
opera Opera
unknown Other browsers

 

Budget

Field Type Required Description
amount Double Yes Budget amount
type String Yes Budget type, designated by either “daily” or “all_time”
evenDeliveryEnabled Boolean No Indicates if the selected budget amount should be delivered evenly throughout the day

{

    "amount": 25.0,
    "type": "daily",
    "evenDeliveryEnabled": true

}

 

Campaign

Field Type Required View Description
campaignId Integer GET Basic Campaign ID
name String GET, POST, PUT Basic Campaign’s name
status String GET, PUT Basic Campaign’s status, designated by one the following values: “online”, “offline”, or “archived”
defaultBid Double GET, POST, PUT Basic Default bid
reviewStatus String GET Complete Campaign’s review status, designated by one of the following values: “pending”, “eligible”, “review”, “hold”, “denied”, or “blocked”
clickUrl String GET, POST, PUT Complete Destination click URL
budget Budget No Complete Budget configuration; includes budget amount and delivery details
frequencyCapping Frequency Capping No Complete Frequency capping configuration, which defines the constraints for impressions per user
flightDates Date Range No Complete Campaign’s running dates
audienceCapture Audience Capture No Complete Audience capture configuration; defines which audiences users get added to after certain campaign events (e.g., after a click)
viewthruConfig Viewthru Config No Complete Viewthru Conversions (VTC) tracking configuration; specifies eligible offers, conversion window, and interplay with regular conversions
videoConfig Video Config No Complete Configuration for video campaigns; specifies delivery types, start delays for in-stream opportunities and audio playback modes for in-banner opportunities
winNotificationUrl String GET Complete URL, to which notifications of won auctions are submitted. This is a premium feature available to select advertisers only.
links Array of Links Yes Complete Array of appropriate links, enabling dynamic discovery for HATEOAS

{

    "links": [...],
    "campaignId": 52337,
    "name": "Mega Campaign",
    "status": "online",
    "defaultBid": 1.7,
    "reviewStatus": "eligible",
    "clickUrl": "http://sitescout.com",
    "budget": {
        "amount": 25.0,
        "type": "daily",
        "evenDeliveryEnabled": true
    }

}

 

Campaign Statistics

Field Type Required Description
impressionsBid Integer No Number of impressions that the campaign bid on
impressionsWon Integer No Number of impressions that the campaign won
effectiveCPM Double No Effective Cost Per Mille (CPM)
auctionsSpend Double No Amount that the campaign spent on auctions
clicks Integer No Number of advertisement clicks
clickthruRate Double No Click-through rate (CTR)
costPerClick Double No Cost-per-click (CPC)
offerClicks Integer No Number of offer (also known as secondary) clicks
offerClickthruRate Double No Click-through rate (CTR) for offer clicks
conversions Integer No Number of conversions
conversionRate Double No Conversion rate (ratio of conversions to clicks)
viewthruConversions Integer No Number of viewthru conversions. NB: Total viewthruConversions in per-site and per-creative campaign statistics will represent unique events and, thus, individual values may not add up.
profitPerClick Double No Profit-per-click (PPC)
costPerAcquisition Double No Cost per acquisition (CPA)
revenuePerMille Double No Revenue per mille (RPM)
revenue Double No Revenue
dataEffectiveCPM Double No Effective Cost Per Mille (CPM) for demographic data
dataSpend Double No Amount that the campaign spent on demographic data
totalEffectiveCPM Double No Total effective Cost Per Mille (CPM), equal to effectiveCPM + dataEffectiveCPM
totalSpend Double No Total amount that the campaign spent, equal to auctionsSpend + dataSpend

{

    "impressionsBid": 43567,
    "impressionsWon": 4842,
    "effectiveCPM": 0.27183024889789575,
    "auctionsSpend": 1.3162020651636113,
    "clicks": 18,
    "clickthruRate": 0.0037174721189591076,
    "costPerClick": 0.07312233695353396,
    "offerClicks": 0,
    "offerClickthruRate": 0.0,
    "conversions": 0,
    "conversionRate": 0.0,
    "viewthruConversions": 0,
    "profitPerClick": 0.0,
    "costPerAcquisition": 0.0,
    "revenuePerMille": 0.0,
    "revenue": 0.0,
    "totalEffectiveCPM": 0.27183024889789575,
    "totalSpend": 1.3162020651636113,
    "dataEffectiveCPM": 0.0,
    "dataSpend": 0.0

}

 

Composite Contextual Rule

Field Type Required Description
type String Yes Contextual rule type, must always be set to “composite”
logicalOperator String Yes Type of the logical relationship among the contained rules: “and” or “or”
rules Array of Contextual Rules(Composite Contextual Rule and Atomic Contextual Rule) Yes Contextual rules, combined using the logical operator. Note that this field may include both atomic and composite contextual rules (i.e., mixed rules are accepted).

{

    "type": "composite",
    "logicalOperator": "or",
    "rules": [
    	{
    		"type": "atomic",
    		"blocked": false,
    		"minWeight": 100,
    		"contextualEntryId": 101
    	},
    	{
    		"type": "atomic",
    		"blocked": true,
    		"minWeight": 100,
    		"contextualEntryId": 102
    	}
    ]

}

 

Composite Demographic Rule

Field Type Required Description
type String Yes Demographic rule type, must always be set to “composite”
logicalOperator String Yes Type of the logical relationship among the contained rules: “and” or “or”
rules Array of Demographic Rules(Composite Demographic Rule and Atomic Demographic Rule) Yes Demographic rules, combined using the logical operator. Note that this field may include both atomic and composite demographic rules (i.e., mixed rules are accepted).

{

    "type": "composite",
    "logicalOperator": "or",
    "rules": [
    	{
    		"type": "atomic",
    		"blocked": false,
    		"demographicId": 101
    	},
    	{
    		"type": "atomic",
    		"blocked": true,
    		"demographicId": 102
    	}
    ]

}

 

Contextual Entry

Field Type Required Description
contextualId Integer Yes ID of the contextual entry
name String Yes Name of the contextual entry
description String No Description of the contextual entry
parentId Integer No ID of the contextual entry’s parent entry
externalId String Yes Provider’s ID of the contextual entry

{

    "name": "Electric Vehicles",
    "parentId": 107,
    "externalId": "116",
    "contextualId": 116

}

 

Contextual Targeting

Field Type Required Description
providerIds Array of Integers Yes IDs of providers, whose data is employed by this contextual targeting
compositeContextualRule Composite Contextual Rule No Composite contextual rule that combines various contextual rules using a logical operator
languageTarget String No Language target, specified as a two-letter code

{

    "providerIds": [4, 5],
    "compositeContextualRule": {
    	"type": "composite",
    	"logicalOperator": "or",
    	"rules": [{
    		"type": "atomic",
    		"blocked": false,
    		"minWeight": 100,
    		"contextualEntryId": 101
    	}]
    },
    "languageTarget": "EN"

}

 

Coordinates Rule

Field Type Required Description
latitude Double Yes Latitude (from -90 to 90)
longitude Double Yes Longitude (from -180 to 180)
distance Integer Yes Targeting radius from the point identified by “latitude” and “longitude”
unit String Yes Distance unit, designated by either “meters” or “feet”
blocked Boolean No Indicates if this rule blocks traffic that originates within the specified distance from the provided geo point. Defaults to “false”.

{

    "latitude": 51.5033,
    "longitude": -0.1275,
    "distance": 100,
    "unit": "meters",
    "blocked": false

}

 

Creative

Field Type Required Description
creativeId Integer GET Creative ID
label String GET, POST, PUT Creative’s label
status String For campaign creatives: GET, PUT Creative’s status within a campaign, designated by one the following values: “online”, “offline”, or “archived”
reviewStatus String GET Creative’s review status, designated by one of the following values: “pending”, “eligible”, “review”, “hold”, “denied”, or “blocked”
width Integer GET, For types “tag” and “expandable”: POST Creative’s width
height Integer GET, For types “tag” and “expandable”: POST Creative’s height
format (Deprecated) String GET Creative format, designated by “image”, “flash”, “expandable”, “html”, “video”, or “text”
type String GET Creative type, designated by “banner”, “tag”, “expandable”, “ad_builder”, or “video”
vaultPath String For AdVault creatives: GET, PUT AdVault folder, in which the creative resides (for campaign creatives, this can be null)
assetUrl String For type “banner”: GET, POST URL of the image, Flash movie, or video for creatives of types “banner” and “video”
vastUrl String No URL of the VAST XML for creatives of type “video”
code String For types “tag” and “expandable”: GET, POST, PUT HTML code for creatives of type “tag” and “expandable”, or VAST XML code for creatives of type “video”
apis Array of Strings No Array of frameworks/APIs required by the creative. Accepted values are: “mraid_1″ and “mraid_2″.
vendor String For type “expandable”: GET, POST, PUT Rich Media vendor for creatives of type “expandable”. Supported values are: “double_click”, “eye_wonder”, “media_mind”, “point_roll”, “unicast”, “flashtalking”, “video_egg”, “eye_return”, “say_media”, “pictela”, “spongecell”, “adrime”, “oggifinogi”, and “other_vendor”.
expandingDirection String For type “expandable”: GET, PUT Expanding direction for creatives of type “expandable”. Supported values are: “up”, “down”, “left”, “right”, “up_left”, “up_right, “down_left”, “down_right”, “up_or_down”, “left_or_right”, “any_diagonal”, and “none”.
previewUrl String GET URL at which the creative can be viewed
companionUrls Array of Strings GET Companion URLs for the video creative
links Array of Links GET Array of appropriate links, enabling dynamic discovery for HATEOAS

{

    "links": [{
        "href": "http://api.sitescout.com/advertisers/1/creatives/42618",
        "rel": "self"
    }],
    "creativeId": 42618,
    "label": "160x600 Blue SWF",
    "width": 160,
    "height": 600,
    "type": "banner",
    "reviewStatus": "eligible",
    "previewUrl": "http://preview.sitescout.ad/preview?ad=/a61ceae3aed8557d&adOnly=1",
    "vaultPath": "/",
    "assetUrl": "http://cdn1sitescout.edgesuite.net/100/1/160x600_blue-E01685D.swf",
    "format": "flash"

}

 

Creative Asset

Field Type Required Description
width Integer Yes Creative asset’s width
height Integer Yes Creative asset’s height
assetUrl String Yes Creative asset’s URL
created String Yes Indicates when and at what time a creative asset was uploaded. Formatted as “yyyyMMdd HH:mm:ss”.
bitrateInKbps Integer Yes, for videos only Total bit rate of a video file in kilobits per second
frameRate Double Yes, for videos only Frame rate of a video file
durationInMs Integer Yes, for videos only Duration of a video file in milliseconds

{

    "assetUrl": "http://cdn1sitescout.edgesuite.net/3400/3337/5c03b36048086393.jpg",
    "width": 300,
    "height": 250,
    "created": "20130603 17:15:27"

}

 

Daily Entity Statistics

Field Type Required Description
entity Object Yes Entity corresponding to the associated statistics
statsList Array of Daily Statistics Yes Array of per-date statistics
totals Campaign Statistics Yes Calculated total values for all statistics, for all days
dateRange Date Range Yes Range of dates for the retrieved statistics
links Array of Links Yes Array of appropriate links, enabling dynamic discovery for HATEOAS

{

   "links": [...],
    "entity": {
        "links": [{
            "href": "http://api.sitescout.com/advertisers/1/campaigns/99999",
            "rel": "self"
        }],
        "campaignId": 99999,
        "name": "Mega Campaign",
        "status": "online",
        "reviewStatus": "eligible",
        "defaultBid": 1.6
    },
    "statsList": [{
        "date": "20130318",
        "stats": {
            "impressionsBid": 43632,
            "impressionsWon": 4855,
            "effectiveCPM": 0.2718482643189781,
            "auctionsSpend": 1.3198233232686387,
            "clicks": 18,
            "clickthruRate": 0.0037075180226570545,
            "costPerClick": 0.07332351795936881,
            "offerClicks": 0,
            "offerClickthruRate": 0.0,
            "conversions": 0,
            "conversionRate": 0.0,
            "viewthruConversions": 0,
            "profitPerClick": 0.0,
            "costPerAcquisition": 0.0,
            "revenuePerMille": 0.0,
            "revenue": 0.0,
            "totalEffectiveCPM": 0.2718482643189781,
            "totalSpend": 1.3198233232686387,
            "dataEffectiveCPM": 0.0,
            "dataSpend": 0.0
        }
    }],
    "totals": {
        ...
    },
    "dateRange": {
        "from": "20130315",
        "to": "20130315",
        "timezone": "America/Toronto"
    }

}

 

Daily Statistics

Field Type Required Description
date String Yes Date that corresponds to the associated statistics, formatted as “yyyyMMdd”
stats Campaign Statistics Yes Various statistical data points

{

    "date": "20130318",
    "stats": {
        "impressionsBid": 43632,
        "impressionsWon": 4855,
        "effectiveCPM": 0.2718482643189781,
        "auctionsSpend": 1.3198233232686387,
        "clicks": 18,
        "clickthruRate": 0.0037075180226570545,
        "costPerClick": 0.07332351795936881,
        "offerClicks": 0,
        "offerClickthruRate": 0.0,
        "conversions": 0,
        "conversionRate": 0.0,
        "viewthruConversions": 0,
        "profitPerClick": 0.0,
        "costPerAcquisition": 0.0,
        "revenuePerMille": 0.0,
        "revenue": 0.0,
        "totalEffectiveCPM": 0.2718482643189781,
        "totalSpend": 1.3198233232686387,
        "dataEffectiveCPM": 0.0,
        "dataSpend": 0.0
    }

}

 

Data Provider

Field Type Required Description
providerId Integer Yes ID of the data provider
name String Yes Name of the data provider

{

    "providerId": 1,
    "name": "Lotame"

}

 

Date Range

Field Type Required Description
from String Yes Start date in the following format: yyyyMMdd
to String Yes End date in the following format: yyyyMMdd
timezone String No Timezone, which can be either UTC offset (“+-HH:mm”) or timezone name (“CET”)

{

    "from": "20130318",
    "to": "20130318",
    "timezone": "America/Toronto"

}

 

Dayparting Rule

Field Type Required Description
fromTime String Yes Starting time, formatted as “HH:mm”
toTime String Yes Ending time, formatted as “HH:mm”
daysOfWeek Array of Strings Yes Specifies which days of week should be included in this dayparting rule. The following values are accepted: “monday”, “tuesday”, “wednesday”, “thursday”, “friday”, “saturday”, and “sunday”.

{

    "fromTime": "11:00",
    "toTime": "12:30",
    "daysOfWeek": ["monday", "friday"]

}

 

Demographic Audience

Field Type Required Description
demographicId Integer Yes ID of the demographic audience
name String Yes Name of the demographic audience
description String No Description of the demographic audience
parentId Integer No ID of the demographic audience’s parent audience
externalId String No Provider’s ID of the demographic audience

{

    "name": "Declared Moms",
    "description": "Those who have declared themselves as a Mom via registration",
    "parentId": 4,
    "externalId": "3493",
    "demographicId": 5

}

 

Demographic Rule (v1)

Field Type Required Description
providerId Integer Yes ID of the provider, whose data is employed by this rule
demographicIds Array of Integers Yes IDs of demographic audiences

{

    "providerId": 1,
    "demographicIds": [10, 100]

}

 

Demographic Targeting

Field Type Required Description
compositeDemographicRule Composite Demographic Rule No Composite demographic rule that combines various demographic rules using a logical operator

{

    "compositeDemographicRule": {
    	"type": "composite",
    	"logicalOperator": "or",
    	"rules": [{
    		"type": "atomic",
    		"blocked": false,
    		"demographicId": 101
    	}]
    }

}

 

Denied Attributes

Field Type Required Description
verticals Array of Strings Yes Denied verticals (content categories)
creativeTypes Array of Strings Yes Denied types of creatives (values do not correspond to field “type” from Creative)

{

    "verticals": [],
    "creativeTypes": ["SystemWarning/WindowsBox", "Adult/Provocative/Suggestive"]

}

 

Connection

Field Type Required Description
carrierCodes Array of Strings No Mobile carriers (operators), communicated using MCC and MNC codes in the following format: “MCC-MNC”. A list of all available carriers and their respective codes can be found at the ITU website.
wifiBlocked Boolean No Indicates if WiFi traffic should be blocked or not. The default value of this field is “false”.

{

    "carrierCodes": ["302-72", "302-64"],
    "wifiBlocked": true

}

 

Operating System Targeting

Field Type Required Description
desktopTargets Array of Operating System Families No Operating system targets for desktop traffic
tabletTargets Array of Operating System Families No Operating system targets for tablet traffic
phoneTargets Array of Operating System Families No Operating system targets for phone traffic

{

    "desktopTargets": ["Google", "Apple"],
    "tabletTargets": ["Google", "Apple"],
    "phoneTargets": ["Google", "Apple"]

}

 

Device Targeting

Field Type Required Description
operatingSystemTargeting Operating System Targeting No Operating system targeting
browsers Array of Browsers No List of targeted Internet browsers
makes Array of Makes No List of targeted device makes
models Array of Strings No List of targeted device models
connection Connection No Internet connection targeting, including the ability to target mobile carriers and WiFi traffic

{

    "operatingSystemTargeting": {
        "phoneTargets": ["Google"]
    },
    "browsers": ["Chrome"],
    "makes": ["Sony"],
    "models": ["Xperia Ion", "Xperia Z"],
    "connection": {
    	"carrierCodes": ["302-72", "302-64"],
    	"wifiBlocked": true
    }

}

 

Domain List

Field Type Required Description
domainListId Integer GET Domain list ID
name String GET, POST, PUT Domain list’s name
domains Array of Strings No Domains associated with this domain list
type String GET, POST, PUT Domain list’s type, designated by either “whitelist” or “blacklist”
links Array of Links GET Array of appropriate links, enabling dynamic discovery for HATEOAS

{

    "links": [{
        "href": "http://api.sitescout.com/advertisers/1/domainLists/23/domains",
        "rel": "domains"
    }, {
        "href": "http://api.sitescout.com/advertisers/1/domainLists/23",
        "rel": "self"
    }],
    "domainListId": 23,
    "name": "Bad Domains",
    "type": "blacklist"

}

 

Entity Statistics

Field Type Required Description
entity Object Yes Entity corresponding to the associated statistics
stats Campaign Statistics or Audience Statistics Yes Various statistical data points
links Array of Links Yes Array of appropriate links, enabling dynamic discovery for HATEOAS

{

    "links": [{
        "href": "http://api.sitescout.com/advertisers/1/campaigns/99999/stats",
        "rel": "self"
    }],
    "entity": {
        "links": [{
            "href": "http://api.sitescout.com/advertisers/1/campaigns/99999",
            "rel": "self"
        }],
        "campaignId": 99999,
        "name": "Mega Campaign",
        "status": "online",
        "reviewStatus": "eligible",
        "defaultBid": 1.6
    },
    "stats": {
        "impressionsBid": 43567,
        "impressionsWon": 4842,
        "effectiveCPM": 0.27183024889789575,
        "auctionsSpend": 1.3162020651636113,
        "clicks": 18,
        "clickthruRate": 0.0037174721189591076,
        "costPerClick": 0.07312233695353396,
        "offerClicks": 0,
        "offerClickthruRate": 0.0,
        "conversions": 0,
        "conversionRate": 0.0,
        "viewthruConversions": 0,
        "profitPerClick": 0.0,
        "costPerAcquisition": 0.0,
        "revenuePerMille": 0.0,
        "revenue": 0.0,
        "totalEffectiveCPM": 0.27183024889789575,
        "totalSpend": 1.3162020651636113,
        "dataEffectiveCPM": 0.0,
        "dataSpend": 0.0
    }

}

 

Exchange

Field Type Required Description
exchangeId Integer Yes Exchange ID
name String Yes Name of ad exchange

{

    "exchangeId": "1",
    "name: "Rubicon"

}

 

Frequency Capping

Field Type Required Description
impressions Integer Yes Maximum number of times that an ad can be shown to a user
periodInHours Integer Yes Specifies a period in hours during which impressions from a user must not exceed the value provided in “impressions”
type String Yes Frequency capping type identifies the granularity for counting impressions; designated by “campaign”, “site”, or “zone”

{

    "impressions": 3,
    "periodInHours": 12,
    "type": "campaign"

}

 

Geo Rule

Field Type Required Description
countryCode String Yes Two-letter country code, see ISO 3166-1 for reference
region String No Region code, as specified by ISO 3166-2
city String No City
postalCode String No Postal code, at the moment only ZIP codes are accepted
dmaCode Integer No Designated Market Area (DMA) code
areaCode Integer No Telephone area code
blocked Boolean No Indicates if the given geo parameters should be blocked. Defaults to “false”.

{

    "countryCode": "CA",
    "city": "Toronto",
    "blocked": false

}

 

Hourly Entity Statistics

Field Type Required Description
entity Object Yes Entity corresponding to the associated statistics
statsList Array of Hourly Statistics Yes Array of per-hour statistics
totals Campaign Statistics Yes Calculated total values for all statistics, for all hours
dateRange Date Range Yes Range of dates for the retrieved statistics
links Array of Links Yes Array of appropriate links, enabling dynamic discovery for HATEOAS

{

   "links": [...],
    "entity": {
        "links": [{
            "href": "http://api.sitescout.com/advertisers/1/campaigns/99999",
            "rel": "self"
        }],
        "campaignId": 99999,
        "name": "Mega Campaign",
        "status": "online",
        "reviewStatus": "eligible",
        "defaultBid": 1.6
    },
    "statsList": [{
        "hour": 0,
        "stats": {
            "impressionsBid": 43632,
            "impressionsWon": 4855,
            "effectiveCPM": 0.2718482643189781,
            "auctionsSpend": 1.3198233232686387,
            "clicks": 18,
            "clickthruRate": 0.0037075180226570545,
            "costPerClick": 0.07332351795936881,
            "offerClicks": 0,
            "offerClickthruRate": 0.0,
            "conversions": 0,
            "conversionRate": 0.0,
            "viewthruConversions": 0,
            "profitPerClick": 0.0,
            "costPerAcquisition": 0.0,
            "revenuePerMille": 0.0,
            "revenue": 0.0,
            "totalEffectiveCPM": 0.2718482643189781,
            "totalSpend": 1.3198233232686387,
            "dataEffectiveCPM": 0.0,
            "dataSpend": 0.0
        }
    }],
    "totals": {
        ...
    },
    "dateRange": {
        "from": "20130315",
        "to": "20130315",
        "timezone": "America/Toronto"
    }

}

 

Hourly Statistics

Field Type Required Description
hour Integer Yes Hour that corresponds to the associated statistics, with values ranging from 0 to 23
stats Campaign Statistics Yes Various statistical data points

{

    "hour": 0,
    "stats": {
        "impressionsBid": 43632,
        "impressionsWon": 4855,
        "effectiveCPM": 0.2718482643189781,
        "auctionsSpend": 1.3198233232686387,
        "clicks": 18,
        "clickthruRate": 0.0037075180226570545,
        "costPerClick": 0.07332351795936881,
        "offerClicks": 0,
        "offerClickthruRate": 0.0,
        "conversions": 0,
        "conversionRate": 0.0,
        "viewthruConversions": 0,
        "profitPerClick": 0.0,
        "costPerAcquisition": 0.0,
        "revenuePerMille": 0.0,
        "revenue": 0.0,
        "totalEffectiveCPM": 0.2718482643189781,
        "totalSpend": 1.3198233232686387,
        "dataEffectiveCPM": 0.0,
        "dataSpend": 0.0
    }

}

 

In-Banner Video Options

Field Type Required Description
audioPlaybackModes Array of Audio Playback Modes Yes Allowed audio playback modes

{

    "audioPlaybackModes": ["auto", "mute", "on_rollover"]

}

 

In-Stream Video Options

Field Type Required Description
startDelays Array of Video Start Delays Yes Allowed video start delays

{

    "startDelays": ["pre_roll", "mid_roll"]

}

 

Link

Field Type Required Description
href String Yes Link URI
rel String Yes Type of the link, designated by the following possible values: “self”, “next”, “prev”, “stats_per_site”, “stats_per_creative”, “stats_per_offer”, “stats_per_placement”

{

    "href": "http://api.sitescout.com/advertisers/1/campaigns/99999",
    "rel": "self"

}

 

Make (Enum)

Value Description
apple Apple
samsung Samsung
lg LG
google Google
amazon Amazon
nokia Nokia
sony Sony
htc HTC
motorola Motorola
asus Asus
blackberry BlackBerry
huawei Huawei
unknown Other makes

 

Offer

Field Type Required Description
offerId Integer GET Offer ID
name String GET, POST, PUT Offer’s name
defaultRevenue Double No Default revenue (value) assigned to this offer
links Array of Links GET Array of appropriate links, enabling dynamic discovery for HATEOAS

{

    "links": [{
        "href": "http://api.sitescout.com/advertisers/1/offers/9999",
        "rel": "self"
    }],
    "offerId": 9999,
    "name": "Mega Offer",
    "defaultRevenue": 56.80

}

 

Operating System Family (Enum)

Value Description
google Operating Systems produced by Google: Android for mobile devices and Chrome OS for desktop devices
apple Operating Systems produced by Apple: iOS for mobile devices and OS X for desktop devices
blackberry BlackBerry OS
microsoft Operating Systems produced by Microsoft: Windows Mobile for mobile devices and Windows for desktop devices
linux Various Linux distributions, only available for targeting desktop devices
unknown Other operating systems

 

Page Position (Enum)

Value Description
above_the_fold Above The Fold (ATF)
below_the_fold Below The Fold (BTF)
unknown Unknown

 

Paginated List

Field Type Required Description
totalCount Integer Yes Total number of items in the list, for all pages
pagination Pagination Yes Pagination information
sorting Sorting No Sorting information, if provided in the request
filter String No Filter value, if provided in the request
status String No Status value, if provided in the request
results Array of Objects Yes Array of requested objects
links Array of Links Yes Array of appropriate links, enabling dynamic discovery for HATEOAS

{

    "links": [{
        "href": "http://api.sitescout.com/advertisers/1/audiences",
        "rel": "self"
    }],
    "totalCount": 2,
    "pagination": {
        "page": 1,
        "pageSize": 20
    },
    "results": [{
        "links": [{
            "href": "http://api.sitescout.com/advertisers/1/audiences/9999",
            "rel": "self"
        }],
        "audienceId": 9999,
        "name": "Football Fans",
        "visible": true
    }, ...]

}

 

Pagination

Field Type Required Description
page Integer Yes Page number
pageSize Integer Yes Number of items per page

{

    "page": 1,
    "pageSize": 20

}

 

Retargeting Rule

Field Type Required Description
audienceId Integer Yes Audience ID, also known as a retargeting list
blocked Boolean No Indicates if this audience is untargeted as opposed to targeted. Defaults to “false”.
accessType String No Used in conjunction with “daysAfterAccess”, indicates if the given number of days must pass after either “first_access” or “last_access”
daysAfterAccess Integer No Number of days that must pass after a user was added to a given audience

{

    "audienceId": 9999,
    "blocked": true,
    "accessType": "first_access",
    "daysAfterAccess": 7

}

 

Site

Field Type Required Description
siteRef String Yes Site reference
exchange Exchange Yes Ad exchange corresponding to this site
type String Yes Type of the site, designated by one of the following values: “site”. “app”, or “email”
name String Yes Name of the site. This value can either be a domain name, name of a mobile app, or a newsletter title.
category String Yes Category (channel) that the site belongs to.
links Array of Links Yes Array of appropriate links, enabling dynamic discovery for HATEOAS

{

    "links": [{
        "href": "http://api.sitescout.com/sites/1-16794/deniedAttributes",
        "rel": "denied_attributes"
    }],
    "siteRef": "1-16794",
    "exchange": {
        "exchangeId": 1,
        "name": "Rubicon"
    },
    "type": "site",
    "name": "ebay.co.uk",
    "category": "Shopping"

}

 

Site Rule

Field Type Required Description
ruleId Integer GET Site Rule ID
siteRef String GET, POST Site reference
status String GET, PUT Site rule’s status, designated by one the following values: “online”, “offline”, or “archived”
reviewStatus String GET Site rule’s review status, designated by one of the following values: “pending”, “eligible”, “review”, “hold”, “denied”, or “blocked”
dimensions String No Dimensions of an advertisement slot, expressed as width x height (e.g., “300×250″)
pagePosition Page Position No Position of an advertisement slot on a site’s page
siteName String GET Either a domain name, human-readable site name, or app name
domain (Deprecated) String GET Domain name
bid Double No Bid assigned to this site rule
links Array of Links GET Array of appropriate links, enabling dynamic discovery for HATEOAS

{

    "links": [{
        "href": "http://api.sitescout.com/advertisers/1/campaigns/99999/sources/siteRules/999999",
        "rel": "self"
    }],
    "ruleId": 999999,
    "siteRef": "4-95781",
    "status": "online",
    "reviewStatus": "eligible",
    "domain": "apps.facebook.com",
    "bid": 0.71

}

 

SiteScout Error

Field Type Required Description
errorCode String Yes Error code
message String No Human-readable description of the error

{

    "errorCode": "AE00000",
    "message": "Access token required"

}

 

Sorting

Field Type Required Description
sortBy String Yes Value to sort by
sortDirection String Yes Sorting direction, designated by “asc” for ascending and “desc” for descending.

{

    "sortBy": "impressionsWon",
    "sortDirection": "desc"

}

 

Statistics List

Field Type Required Description
totalCount Integer Yes Total number of items in the list, for all pages
pagination Pagination Yes Pagination information
sorting Sorting No Sorting information, if provided in the request
filter String No Filter value, if provided in the request
status String No Status value, if provided in the request
results Array of Entity Statistics Yes Array of returned statistics paired with respective entities
totals Campaign Statistics or Audience Statistics Yes Calculated total values for all statistics, for all pages
dateRange Date Range Yes Range of dates for the retrieved statistics
fromCache Boolean Yes Indicates if the statistics have been retrieved from cache or not
links Array of Links Yes Array of appropriate links, enabling dynamic discovery for HATEOAS

{

    "links": [{
        "href": "http://api.sitescout.com/advertisers/1/campaigns/stats",
        "rel": "self"
    }, {
        "href": "http://api.sitescout.com/advertisers/1/campaigns/stats?page=2",
        "rel": "next"
    }],
    "totalCount": 21,
    "pagination": {
        "page": 1,
        "pageSize": 20
    },
    "results": [...],
    "totals": {...},
    "dateRange": {
        "from": "20130315",
        "to": "20130315",
        "timezone": "America/Toronto"
    },
    "fromCache": false

}

 

Traffic Type (Enum)

Value Description
all All traffic
all_web All traffic sources, except for mobile apps
all_mobile Traffic that originates from mobile devices
app Mobile app traffic
mobile_web Web sites viewed from a mobile device
web Regular web sites and newsletters

 

Video Config

Field Type Required Description
deliveryTypes Array of Video Delivery Type Yes Specifies the video delivery type: “in_stream”, “in_banner” or both
inStreamOptions In-Stream Video Options No Targeting options for in-stream video opportunities
inBannerOptions In-Banner Video Options No Targeting options for in-banner video opportunities

{

    "deliveryTypes": ["in_stream", "in_banner"],
    "inStreamOptions": {
    	["pre_roll", "mid_roll"]
    },
    "inBannerOptions": {
    	["mute"]
    }

}

 

Video Delivery Type (Enum)

Value Description
in_stream In-stream video ad opportunities
in_banner In-banner video ad opportunities

 

Video Start Delay (Enum)

Value Description
pre_roll Play the ad before the video content
mid_roll Play the ad in the midst of the video playback
post_roll Play the ad after the video content
unknown Unknown

 

Viewthru Config

Field Type Required Description
conversionWindowInDays Integer Yes Lookback window in days (How many days after a creative was seen by the user, a conversion is allowed to happen?)
offers Array of Integers Yes A list of offers to watch for Viewthru Conversions
payoutRate Double No Payout rate relative to the conversion revenue defined by an offer. The value of this field can range from 0 to 1. If not provided, defaults to 1 (i.e., 100%).
deduplicationEnabled Boolean No Indicates if viewthru conversions should be de-duplicated against regular conversions. If set to true, when a conversion occurs after a click, a viewthru conversion will not be counted. Defaults to “true”.

{

    "conversionWindowInDays": 15,
    "offers": [5064],
    "payoutRate": 1.0,
    "deduplicationEnabled": true

}

 

Back to top