This page explains the semantics of our REST API. It includes information on:
- How to ask a service about itself: what fields it supports, which fields are filterable
- How to get only the information you want by filtering and sorting
- The "shape" of our JSON responses in different scenarios
This document assumes you have completed the API Onboarding Process.
The AppNexus API supports HTTP Protocol version 1.1 or later. While some calls may work with the deprecated 1.0 version, this is not guaranteed. Please ensure that your client communicates using at least version 1.1.
The URL for the production API endpoint is: https://api.appnexus.com. Please note that non-secure access to the product API (HTTP) is not available.
Changes made with this API affect the production AppNexus Console. Only authorized users should alter information or settings in this environment.
The URL for the testing API endpoint is: https://api-test.appnexus.com.
This environment replicates the production codebase and is kept up to date on a monthly or shorter release schedule. The environment is made available expressly for clients to test their integrations without having to interfere with production data. See Client Testing Environment for details.
Our API services are RESTful. REST (Representational State Transfer) is a type of software architecture in which requests model the communication from a web browser to a web server. Below are the central REST methods used in our API services, and their uses:
When making a
PUT request, you must include a JSON file with the data to create or update.
PUT overwrites arrays unless 'append=true' is added to query string
PUT requests, only the fields included in the JSON file will be updated, except in the case of arrays. When updating an array using
PUT, all fields in the array are overwritten with the contents of the new array you upload, unless you append the following to your request query string:
PUT request for updating an array
This example walks you through the process of properly updating the
pixels array of creative ID 503577 using the "legacy" method; in other words, with the "overwrite arrays on
PUT" behavior that occurs unless you append the string
"append=true" to the query string of your request.
First, let's look at the creative. Note that the
pixels array already includes one pixel.
Next, we create the JSON file for adding a new pixel to the creative. In the file, we include both the new pixel that we want to add and the pixel that was already attached to the creative.
If we don't include the existing pixel in the JSON file, our update will delete that pixel from the creative.
Then we make a
PUT call to update the creative with the information in the JSON file. Note that the
pixels array in the response includes both the new and old pixels.
In our documentation we use curl to make HTTP requests. Curl is a command-line tool for transferring files with URL syntax, supporting FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, LDAP, LDAPS, and more. Example scripts have been provided on each API wiki page to illustrate the structure of the
curl commands you will need to run AppNexus API services. In addition, an example of how to a make a generic
POST request is shown below. This example uses the Authentication Service:
Chunk of Request
What it Means
Creates a text file called "cookies" and stores your session token (assigned by the Authentication Service). This is not a required argument to
Retrieves the authentication token that you previously stored in the "cookies" text file.
Indicates that you are going to make a certain type of request, in this case "POST".
Indicates that you are going to upload a file, in this case "auth.json".
The URL of the service you are making the request to. Use quotes in case you have any special characters in your URL.
Use Single Quotes Around Your Request URL
Some requests require single quotes around your request URL, as in the above
curl request. If you get an error message from your UNIX shell, make sure your request URL has single quotes before troubleshooting further. For more information on how UNIX shell quotes and escaping work, see this documentation on quotes and escaping in shells.
Filtering and Sorting
Most API Services support filtering and sorting. Filtering allows you to specify a subset of objects to be returned. Sorting allows you to control the order of the objects returned.
Get Multiple Objects by ID
You can get multiple specific objects by ID by passing a comma-separated list of IDs. The result object will contain an array holding just those specific objects. In the example below, we ask the Campaign Service for just the campaigns with IDs 1, 2, and 3.
Filter by IDs
Pass a query string parameter for the field with a comma-separated list of IDs.
Example: Request all campaigns for certain line items.
Example: Request certain advertisers
Only 100 objects will be returned per request
The maximum number of objects that can be returned, regardless of pagination, is 100. If you request over 100 objects, we will only return the first 100 and will not provide an error message. For more information on how to paginate API results, see Paging.
Filter by Min and Max Values
Fields that are of the type
money can be filtered by
max. For example:
Fields of the type
date can be filtered by
nmax as well. The
nmin filter lets you find dates that are either
null or after the specified date, and the
nmax filter lets you find dates that are either
null or before the specified date. For example:
Note the required date/time syntax in the preceding example: YYYY-MM-DD+HH:MM:SS
Another option for filtering by date is to use the
Filter by Field Names
To limit the response to specific fields of an object, pass the
fields query string parameter with a comma-separated list of field names. For example:
Misc Filters on Field
We support the following additional field-based filters on API responses:
Some services support
search as a query string parameter to look for ID or name. For example:
To sort use the
sort query string parameter and pass in a list of fields you'd like to sort by and whether you want them ascending (
asc) or descending (
desc). For example:
To page, use the
num_elements parameters. If
num_elements is not supplied, it defaults to 100 (which is also the maximum value).
append=true in the query string of a
PUT call, a user can update only a particular child object instead of replacing all child objects. In other words, rather than overwriting an entire array with a new one on a
PUT call, you can use
append=true on the query string to add a single element to a long array.
In this example, we'll use
append=true on a
PUT call to toggle the
is_available flag of an object in the
member_availabilities array of the Plugin Service. Without the
append=true flag on the query string, the new item would replace the entire array. In this example, it's only added.
We'll send the following JSON to turn off the
is_available flag on one of the
Normally, sending the JSON above on a
PUT call would overwrite the whole
member_availabilities array. However, this time we'll add
"append=true" to the query string of the call. This tells the API to change just the object whose
4. We can verify that it's done so by inspecting the output.
JSON Basic Structure
Below are the syntax of the components of a JSON object and what they mean.
Associate a key with an alphanumeric string value:
Associate a key with a numeric value:
An example that puts them together:
JSON Field Types
Different fields require different types of values. The table of types below extends those defined in the JSON standard.
True or false.
A string of 100 characters or less.
A generic decimal number.
A floating-point number with 32-bit precision.
A floating-point number with 64-bit precision.
One of a number of predetermined values.
A floating-point numeric value used to represent money. For more information, see Vertica's Numeric Data Types.
A date and time string in the form YYYY-MM-DD HH:MM:SS. All timezones are in UTC unless otherwise noted.
A wrapper for any sub-fields under the current field. In the example that follows, the field
A list containing one or more values. In our API, arrays most often contain lists of objects, integers, or strings.
How and Why Reporting APIs are Different
The reporting APIs available via the Report Service work differently than our other APIs. They have their own multi-step request and response flow. This is required because they process large amounts of data; this processing needs to be performed asynchronously.
For instructions on how to retrieve reports, see the Report Service.
For a tutorial that explains how to use our reporting APIs effectively, see Report Pagination.
A Note on Underscores and Hyphens
JSON fields and values use underscores, e.g.,
API service names in URLs are hyphenated, e.g.,
All API Services return JSON data. When Service calls are successful, the JSON response will include a
"status" field set to
"OK". The response to
PUT calls will also include the ID of the relevant object, as well as any relevant attributes of that object. Every response will include a
"dbg_info" object that conveys information about the API call and response, such as the API machine that processed the request and the version of the API you're using.
In the example below, we are using cookies to store our authentication token and adding the file "creative" to advertiser 123 with the Creative Service.
The table below lists the fields of the
dbg_info object and their definitions:
The API machine which processed the request.
Whether or not the API machine ran SQL queries on a database slave.
The database the query was executed on.
The number of reads made.
The limit on the number of reads.
The time period over which the
The number of writes made.
The limit on the number of writes.
The time period over which the
The amount of time it took to process the API request, expressed in milliseconds.
The POSIX timestamp of the start time of processing, including milliseconds (right side of the decimal point).
The version of the API.
When invalid input is sent to the API (for example, an incorrect password), a JSON response will be returned with
"error" field is useful for debugging purposes, as it contains a verbose description of the error. The
"error_id" field can be used programmatically as described in the table below.
For an in-depth discussion of the errors that your API script should be able to handle, see KB - API Authentication (customer login required).
How to Respond
A client request is inconsistent; for example, a request attempts to delete a default creative attached to an active placement.
Check the request logic for consistency.
|The user has reached the maximum number of allowed objects of a certain type.||Delete unnecessary objects to get under the limit. If you cannot delete any object, please contact your AppNexus representative.|
The user is not logged in, or the login credentials are invalid.
Use the Authentication Service to get a token, or check the username and password in your request.
|The user's account has been deactivated.||Login with a different user, or create a user account specifically for API access.|
|The user's password has expired and needs to be reset.||Use the Authentication Service to get a new token.|
The syntax of the request is incorrect.
A system error has occurred.
Contact your AppNexus representative.
The user is not authorized to take the requested action.