Guide to Using Adform APIs

Vaida
Vaida
  • Updated

The purpose of Adform APIs is to support and facilitate the use of Adform suite of products. The APIs consist of structured endpoints that Adform clients can use to access their data, build integrations between their own and the Adform platform, and automate platform processes. To provide a visual representation of the API endpoints and make them easier to use, Adform documents the APIs using OpenAPI Specification.

Note

APIs should be used only for authorized purposes and in accordance with applicable contractual terms, security requirements, and privacy laws. Clients remain responsible for ensuring that any personal data processed through API integrations is handled in accordance with the applicable legal requirements.

To be able to use Adform APIs, you need to understand:

  1. The structure of the API document

  2. The structure of API endpoints

Once you know how to work with the API document, you can use a tool of your choice, such as Postman or cURL, to send a request to an Adform API.

Understand the Structure of the API Document

Adform API documentation is based on Swagger UI that is generated using OpenAPI Specification. Each Adform API has a technical document that's available in Adform Help. You can see those API documents when you open a Guide article and scroll to the end, or open an Endpoint article. An API document has the following elements:

API_document_structure.png

1: Title of the documented API

2: Link to the JSON version of the API document

3: Title of an API section (expandable, expanded by default)

4: Endpoints under an API section (expandable, collapsed by default)

5: Models section (expandable, collapsed by default)

The endpoints are color-coded based on the HTTP method that they use. Each endpoint in the API has the following elements:

API_endpoint_structure.png

1: HTTP method: Shows the operation that you can perform on a resource by using the endpoint.

HTTP Methods in Adform APIs

Adform APIs use the following HTTP methods:

  • GET method: Retrieves data from the server.

  • POST method: Sends data to the server to create a new resource.

  • PUT method: Updates an existing resource with new data.

    Note

    When using PUT method, pass over the whole model. Passing a partial model might lead to unexpected errors.

  • PATCH method: Partially updates an existing resource.

  • DELETE method: Removes a resource from the server.

    Note

    In some APIs, the DELETE method archives the resource instead of deleting it.

2: Endpoint: Shows the resource path of the endpoint URL.

Endpoints in Adform APIs

Adform API endpoints consist of:

  • Base URL: The path prefix that's common for all endpoints. The base URL is typically omitted from the API document, but you still need to specify the full URL when using the API. In Adform, the base URL is https://api.adform.com/.

  • Resource path: The path is appended to the base URL to specify a resource. The path always starts with /, for example, /v3/buyer/rtb/lineitems or /v3/buyer/rtb/lineitems/{id}.

    In a resource path, you must replace the {} part with the indicated value. For example, you must replace the {id} here with a programmatic (RTB) line item ID.

In Adform, every endpoint has a version. The version is applied on the API level and isn't universal for all Adform APIs.

The following rules are applicable for Adform APIs versioning:

  • All URLs start with https://api.adform.com/v1 or https://api.adform.com/api/v1 base part, where v1 is a current version of API.

  • We use v prefix and the whole number for every API. For example, v1, v2.

  • If one endpoint is announced to be deprecated, you will see two versions of the same endpoint. We always recommend using the latest version. See the deprecation schedule.

3: Endpoint description: Provides a brief overview of the endpoint's function.

4: OAuth scopes: Shows the access scopes that your OAuth client needs to use the endpoint.

Important

If an endpoint doesn't have access scopes provided next to it, check the list of required scopes in the Authentication section above the API document.

For more information about access scopes, see OAuth Scopes.

You can expand an endpoint to see all its details.

Understand the Structure of API Endpoints

An expanded endpoint has two separate sections under it:

API_endpoint_expanded_2.png

1: Parameters: This section includes all the information you need to send an API request using the endpoint.

2: Responses: This section provides examples of possible API responses to your request, including both success and error results.

To send a well-structured API request and receive a successful response, you need to follow the requirements provided in the Parameters section under the API endpoint.

Structure of Parameters Section

Depending on the HTTP method, an endpoint will have a list of different required parameters in the Parameters section. For example, all POST and PUT endpoints must include a body parameter, and all PUT and DELETE endpoints require one or more path parameters.

Adform APIs use four types of parameters:

  • path: Embedded in the resource path. For example, in /campaigns/{id}, the {id} is the path parameter. Path parameters are required for API requests.

  • query: Appended to the resource path after the ? sign. For example, in /campaigns?status=active, the status=active is the query parameter. Query parameters can be required or optional for API requests. To include a query parameter in the resource path, add it before sending the API request.

    Query parameters in Adform APIs

    Rules for using query parameters in Adform APIs:

    • Separate multiple query parameters with a & sign.

    • If you're passing arrays in queries, use commas to split them. For example, ?id=1,2,3.

    • Pagination applies to all data entity lists that don't have limits. The majority of them are offset-based, so you can pass the following parameters in the query:

      • limit: maximum number of items (positive integer). 100 is the default value.

      • offset: number of skipped items (non-negative integer). 0 is the default value.

      For example, your request might look like this:

      GET api.adform.com/v1/buyer/campaigns?limit=20&offset=20

      In case pagination is cursor-based, you can specify:

      • limit.

      • cursor: reference to the next or previous items page (string).

  • header: Added as a key-value pair to the API request. For example, Content-Type: application/json is a header parameter that specifies the format of the request body. Header parameters can be required or optional for API requests.

    Header parameters in Adform APIs

    In Adform APIs, header parameters provide metadata about the request, such as:

    • Authorization: Used for authentication tokens, for example, Bearer <token>. Authentication tokens provide the credentials to authenticate a user with a server, allowing them access to a protected resource. For more information about authorization, see which authorization methods Adform supports and read about bearer token authentication.

    • Content-Type: Specifies the format of the request body, for example, application/json.

    • Accept: Specifies the expected format of the response body, for example, application/json.

    • CorrelationId: Specifies the UUID to identify a chain of requests, for example, A1234.

  • body: Included in the API request body. A body parameter specifies the data to send to the API. Body parameters are required for most API requests that use POST, PUT, and PATCH methods.

    Body parameters in Adform APIs

    Details of the body parameters in Adform APIs:

    • Adform APIs use JSON as the Body Payload. It follows the RFC-7159 standard.

    • Dates in Adform APIs are passed as strings which follow ISO-8601 format. For example, midnight of January 25th, 2019 in UTC time zone will look like this: 2019-01-25T00:00:00. In turn, switching time zone to +2 UTC will look like this: 2019-01-25T00:00:00+02:00.

    • Objects in Adform APIs are singular. Arrays, in turn, are pluralized. For example:

      GET / HTTP/ 1.1
Host: api.adform.com/v1/seller/globalbuyers/advertiserDomains

[
{
"categoryIds": [
        0
      ],
"recognitionSource": {
        "type": "Manual",
        "id": 0
      }
}
]

    • Enumerations are strings which are using camelCase for naming.

    • The auditing fields are consistent across all platform: createdAt, updatedAt, lastActionAt, createdBy, updatedBy.

You can see each parameter's name, format, and type in the Name column:

API_endpoint_parameters_-_name.png

Note

All required parameters are marked with * or * required tag.

The Description column provides additional information about each parameter. For the body parameter, this column provides a request code example and a model of all objects and values that you must define in it:

API_endpoint_parameters_-_description.png

To switch between the code example and the model, click Example Value or Model. You can also find a combined list of all endpoint models in the Models section at the end of the API document.

Structure of Responses Section

After you send a request, the API responds with either a success or an error message. You can see the list of possible API responses in the Responses section.

Adform API response typically includes:

  • HTTP status code: Indicates the result of the request, for example, 200 Success, 404 Not Found, 500 Server Error. There are three response status types:

    • The 2XX Success status code is typically not shown in the response. Instead, the response body provides the resource that was requested.

    • The 4XX status codes indicate errors on the user's side. In rare cases, changes to the API can also cause these errors.

    • The 5XX status codes indicate errors on the server side. In rare cases, an invalid API request that normally triggers an 4XX error might instead result in an 5XX error if the server doesn't properly handle the request.

  • Headers: Provide metadata about the response, for example, Content-Type.

  • Body: Contains the data that was requested, usually in JSON format, if the API request was successful. If unsuccessful, the body contains a message and optional details about what went wrong.

You can see the possible response status codes in the Code column:

API_response_structure_-_code.png

The Description column provides examples of the response body and information about the included header parameters for each status code:

API_response_structure_-_description_2.png

Same as in the Parameters section, you can switch between the response code example and the model by clicking Example Value or Model.

Send an API Request

Once you understand the structure of the API document, you can start sending requests to Adform APIs.

To send an API request:

  1. Identify the APIs and endpoints that you need to use to complete your task.

    If you're just starting to work with Adform APIs, read the Guides articles to learn more about how Adform APIs work together and when to use each one.

    If you're already familiar with Adform APIs, see the Endpoints articles for specific API documents.

  2. Request access to the needed APIs and endpoints.

    Important

    Make sure your Adform account already has permissions and data access to the needed resources.

    See which scopes you need in the Authentication section above the API document. To get access, contact Adform Support (technical@adform.com) with your OAuth client and a list of needed scopes.

    If you need to work with multiple APIs, request access to all of them at once.

    Note

    If you don't have an OAuth client yet, follow the procedure in Get Authentication Credentials for Adform APIs to register one.

  3. Get an access token to use the APIs.

    Depending on the authorization method that you use, follow the instructions in Get Authentication Credentials for Adform APIs to request an access token. You can use a tool of your choice, for example, Postman or cURL, to send the POST request for the token.

  4. Prepare your API request.

    Note

    Adform doesn't provide a testing environment for APIs. To test Adform APIs, use a tool of you choice, such as Postman or cURL. To help you get started, see Authenticate and Test Adform APIs With Postman.

    In the tool that you chose, write your API request using the parameters and models in the API document:

    1. Specify the HTTP method and the full endpoint URL, including any path and query parameters.

    2. Provide the access token either as an Authorization header or in a separate authorization section of your chosen tool.

    3. Provide any required header parameters in code or in a separate headers section of your chosen tool.

    4. If you're using a POST, PUT, or PATCH endpoint, copy the example request code provided next to the body parameter into your chosen tool and replace the values. For information about which values are required, switch to Model.

  5. Send your API request.

  6. Check the API response and troubleshoot, if needed.

    Ideally, the API response is a success message with the needed response code. If you receive an error message, check the Overview of API Errors article for troubleshooting information.

  7. Repeat steps 4 to 6 to send API requests to each endpoint that you have identified in step 1.

    To renew your access token once it expires, follow the instructions in Get Authentication Credentials for Adform APIs.

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!