Learn About General Adform API Structure

Greta
Greta
  • Updated

Adform's API is designed to seamlessly support Adform suite of products by providing structured endpoints that enable efficient data access, integration, and automation across its advertising platform.

In general, each Adform API has are six elements that make up its structure:

Endpoints

Endpoints are specific URLs that users can use to access resources and perform operations, for example, https://api.adform.com/v1/buyer/campaigns. Each endpoint corresponds to a specific function of the API. An endpoint consists of:

  • Base URL: The path prefix that is common for all endpoints. The base URL is typically omitted from Swagger documentation, but the user still needs 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, /v1/buyer/campaigns or /v3/buyer/tags/directtags/{id}.

    In a resource path, {} means the user must replace it with the value (without the curly brackets). For example, {id} must be replaced with a direct tag ID.

In Adform, every endpoint has a version. 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.

HTTP Methods

APIs use different HTTP methods to perform operations on resources. These methods are color-coded in Swagger documentation to make them easier to distinguish. 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, we recommend passing over the whole model. Minimum requirement is the mandatory fields.

  • PATCH method: Partially updates an existing resource.

  • DELETE method: Removes a resource from the server.

Example of HTTP methods with endpoints

HTTP methods

POST, PUT, and PATCH methods require specific body parameters to be sent with the API request. Swagger documentation provides these parameters and their structure in “Model” and “Example Value” fields under each endpoint:

Example of model value fields in Swagger documentation

model and example value fields

GET and DELETE methods can be used without providing body parameters with the API request.

Request Headers

Headers in Adform APIs provide additional information 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.

Example of request headers

request header

Request Parameters

Parameters allow users to customize their requests:

  • Path parameters: Embedded in the URL path. For example, in /campaigns/{id}, the {id} is the path parameter. Path parameters are mandatory for the API call.

  • Query parameters: Appended to the URL after the ? sign. For example, in /users?role=admin, the role=admin is the query parameter. Query parameters are optional and must be added before making the API call to be included in the resource path. Rules for using query parameters:

    • 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 is implemented for 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).

  • Body parameters: Included in the request body for POST, PUT, and PATCH methods. See the details of the body parameters:

    • 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.

Examples of request parameters

path parameters
query parameters
body parameters

Response Structure

Adform API response typically includes:

  • 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, these errors can also be caused by changes to the API.

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

  • 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.

Example of status codes in Swagger documentation

response status

Error Handling

Standardized error responses help users understand what went wrong:

  • Error codes: Application-specific codes to identify errors.

  • Messages: Descriptive error messages.

  • Details (Params): Additional information about the error (optional).

For more information about Adform error messaging, see Learn about API Errors.

Example of error responses

error codes

API Structure of Adform Products

To learn more about the structure of each Adform product API, see the articles:

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!