Overview 

With the Activation API, developers can create, update and manage the resources of the Activation module: advertisers, campaigns, line items, creatives, and budgets. 

The API adheres to the JSON API specification for consistency and ease of integration. 

Authentication

The authentication workflow involves Equativ’s authentication provider (Auth0) and Equativ’s Activation API.

Swagger UI

The Swagger UI for Activation API provides documentation of all methods and operations, as well as a composer to build requests.  

Required information

To authenticate and use the Activation API, you need the following credentials, which will be provided by your Equativ contact:

• the client_id and client_secret
• the username and password used to access the Maestro platform

Authentication workflow

Step 1: Request the access token from Auth0

Request the access token from Equativ’s authentication provider Auth0:  

curl --request POST \
  --url 'https://´smartadserver.eu.auth0.com/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=http://auth0.com/oauth/grant-type/password-realm' \
  --data 'realm=Username-Password-Authentication' \
  --data 'audience=api.demand.smartadserver.com' \
  --data-urlencode 'username={username}' \
  --data-urlencode 'password={password}' \
  --data 'client_id={client id}' \
  --data 'client_secret={client secret}'

In the response, you will receive the access token, which has a time to live of 10 hours (36000 seconds):  

{
"access_token":"<access token>",
"expires_in": 36000,
"token_type": "Bearer"
}

Step 2: Request the user token

With the access token obtained in Step 1, you must now request the user token, which you will use in all future API requests:   

curl --request GET \
--url https://buyerconnectapis.smartadserver.com/authorize \
--header 'Authorization: Bearer <access token>'

The response body will only contain the user token which has a time to live of 10 hours.  

Step 3: Use the user token in API requests

Use the user token obtained in Step 2 in the Authorization header of all your API requests:   

curl --request GET \
--url  https://buyerconnectapis.smartadserver.com/selfServe \
--header 'Authorization: Bearer <user token>'

Work with Activation API

Endpoint

https://buyerconnectapis.smartadserver.com/selfServe  

Setup sequence for Activation resources 

To efficiently set up your Activation resources, it is important to follow the correct sequence, as illustrated in the following chart. Deviating from this order can lead to discovering that some elements should have been created first. While revisions are possible, starting with the right sequence from the beginning ensures a more efficient process. 

Available resources

The table outlines the Activation module resources you can create, update, and manage. ⚠️ Warning: it is highly recommended to create these resources in the order presented in the table to ensure proper configuration.

Available methods 

For each of the available resources mentioned above, you can use the following HTTP methods:

Single item and all items

In case of the GET method, you can retrieve a single item of a resource, for example, a single advertiser or all items of a resource, for example, all advertisers. The distinction is made by either specifying the ID of the item (for retrieval of a single item) or by specifying no ID at all (for retrieval of all items).

In case of the DELETE and PATCH methods, you can only operate on a single item of a resource; you must specify the ID to be deleted or patched. Bulk deletion or bulk patching of all items of a resource isn't supported.

Filter, sort, and apply pagination   

You can set filters, sort the results, and apply pagination. 

Examples

GET all advertisers

curl -X 'GET' \
'https://buyerconnectapis.smartadserver.com/selfServe/advertisers' \

GET a single advertiser

Request

curl -X 'GET' \
'https://buyerconnectapis.smartadserver.com/selfServe/advertisers/2' \

Response   

HTTP 200

{
  "links": {
    "self": "string"
  },
  "data": {
    "attributes": {
      "createdAt": "2024-06-10T14:10:38.990Z",
      "description": "string",
      "domain": "string",
      "id": 2,
      "lastUpdatedAt": "2024-06-10T14:10:38.990Z",
      "name": "string",
      "status": "Active"
    },
    "id": "string",
    "included": [
      {
        "id": "string",
        "type": "iabCategories",
        "attributes": {},
        "relationships": {}
      }
    ],
    "relationships": {
      "campaigns": [
        {
          "data": {
            "id": "string",
            "type": "standardCampaigns"
          }
        }
      ],
      "creatives": [
        {
          "data": {
            "id": "string",
            "type": "bannerCreatives"
          }
        }
      ],
      "iabCategory": {
        "data": {
          "id": "string",
          "type": "iabCategories"
        }
      }
    },
    "type": "advertisers"
  }
}

GET all campaigns

curl -X 'GET' \
'https://buyerconnectapis.smartadserver.com/selfServe/campaigns' \

POST a campaign

Request   

curl -X 'POST' \
  'https://buyerconnectapis.smartadserver.com/selfServe/campaigns' \
  -H 'accept: application/vnd.api+json' \
  -H 'Authorization: Bearer xxxxx
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "standardCampaigns",
    "attributes": {
      "currencyCode": "EUR",
      "endDate": "2023-02-01T15:00:00",
      "fcImpressionsPerInterval": 100,
      "fcInterval": 480,
      "name": "My new campaign",
      "startDate": "2023-01-04T11:00:00",
      "timezone": "Europe/Paris"
    },
    "relationships": {
      "advertiser": {
        "data": {
          "id": "1",
          "type": "advertisers"
        }
      }
    }
  }
}'

Response

{
  "links": {
    "self": "string"
  },
  "data": {
    "attributes": {
      "createdAt": "2024-06-10T14:03:28.075Z",
      "currencyCode": "string",
      "endDate": "2024-06-10T14:03:28.075Z",
      "fcImpressionsPerInterval": 0,
      "fcInterval": 0,
      "id": 0,
      "lastUpdatedAt": "2024-06-10T14:03:28.075Z",
      "name": "string",
      "startDate": "2024-06-10T14:03:28.075Z",
      "status": "Active",
      "timezone": "string"
    },
    "id": "string",
    "included": [
      {
        "id": "string",
        "type": "iabCategories",
        "attributes": {},
        "relationships": {}
      }
    ],
    "relationships": {
      "advertiser": {
        "data": {
          "id": "string",
          "type": "advertisers"
        }
      },
      "budgets": [
        {
          "data": {
            "id": "string",
            "type": "campaignBudgets"
          }
        }
      ],
      "lineItems": [
        {
          "data": {
            "id": "string",
            "type": "lineItems"
          }
        }
      ]
    },
    "type": "standardCampaigns"
  }
}

Update a campaign

Use the PATCH method to update a single campaign. To update a campaign, you must include the Content-Type: application/vnd.api+json header and provide a full JSON:API envelope containing data.type, data.id, and the specific attributes you want to change.

Request

curl -X 'PATCH' \
  'https://buyerconnectapis.smartadserver.com/selfServe/campaigns/42' \
  -H 'accept: application/vnd.api+json' \
  -H 'Authorization: Bearer xxxxx' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "standardCampaigns",
    "id": "42",
    "attributes": {
      "name": "Renamed campaign"
    }
  }
}'

Campaign types

The type field on a campaign is a discriminator with two values:

Programmatic Guaranteed campaigns

PG campaigns require the following additional fields:

Campaign duplication

You can duplicate standard campaigns by passing the duplicateDependenciesFromCampaignId attribute in a POST request. This action copies budgets, line items, and their dependencies from the source campaign. This field is create-only and applies only to standard campaigns.

Computed properties

Campaigns include a read-only computedProperties relationship that contains derived values. These values include the effective startDate, endDate, and the overall and daily unit and spend totals. You cannot write to these properties directly.

Goals

You can attach goals to campaigns using the goals relationship. 

Campaign budgets

To link a budget to an existing campaign, use a POST request.

Field reference

The following table describes the fields for campaign budgets. All tables are ordered alphabetically by the field name.

Line items

Core fields

The following table describes the core fields for line items. All tables are ordered alphabetically by the field name.

Targeting fields

Line item targeting settings propagate to SSP deal targeting. Key targeting fields include:

• countryCodes
• platformIds
• impressionTypeIds
• isCTV
• audienceSegmentsTargeting
• semanticSegmentsTargeting
• domainListId
• viewabilityTargetingPercentage
• videoCompletionTargetingPercentage
• CTV targeting arrays

Line item budgets

Line item budgets use the same structure as campaign budgets, but they must comply with the following constraints:

• The unitType must match the unitType of the parent campaign budget.
• The budget startDate and endDate must fall within the date range of the parent campaign.

Goals

Goals are separate CRUD resources for campaigns and line items.

Field reference

The following table describes the fields for goals. All tables are ordered alphabetically by the field name.

Creatives

Atomic operations for write actions

Creatives don't use standard REST methods for creation, update, or deletion. All write operations use atomic operations with the following endpoint and header:

POST /v1/operations
Content-Type: application/vnd.api+json; ext="https://jsonapi.org/ext/atomic"

List and get creatives

To list or retrieve creatives, use a standard GET request with filters. For example:

• GET /v1/creatives?filter[advertiser.id]=123
• GET /v1/creatives?filter[lineItems.id]=456
• GET /v1/creatives?filter[name]=MyCr

Creative types

You can set six different creative types using the type discriminator:

Optional fields

The following optional fields are common to all creative types. The table is ordered alphabetically by the field name.

Link a creative to a line item

To link a creative to a line item, use the lineItems relationship on the creative object. You can perform this action when you create the creative or by using a PATCH update.

Native creative assets

Setting up native creatives is a two-step process:

1. Create the nativeCreative shell using atomic operations.
2. Attach each asset by sending a POST request to /selfServe/nativeAssets.

Asset types

Specify the asset type using the type field. All asset types link to their parent nativeCreative through the creative relationship.

Trackers

Trackers are impression or click pixels attached to a creative. To create a tracker, send a POST request to /v1/trackers.

Tracker modes

The following table describes the available tracker modes. The table is ordered alphabetically by the mode name.

Optional GDPR relationships

You can include the following optional GDPR relationships:

• tcfVendor: Links to a TCF vendor. To retrieve a list of vendors, use GET /v1/tcfVendors.
• tcfPurpose: Links to a TCF purpose. To retrieve a list of purposes, use GET /v1/tcfPurposes.

Delete a tracker

To delete a tracker, send a DELETE request to /v1/trackers/{id}.

Validation rules

The API enforces the following validation rules. If a request violates these rules, the API returns a 422 Unprocessable Entity error.

Enum reference

The following table provides the allowed values for the enumerations used in the API. The table is ordered alphabetically by the enum name.