Contact support
    • Maestro
    • Developers

    Manage campaigns with the API

    Table of Contents

    Overview Authentication Swagger UI Required information Authentication workflow Step 1: Request the access token from Auth0 Step 2: Request the user token Step 3: Use the user token in API requests Work with Activation API Endpoint Setup sequence for Activation resources Available resources Available methods Single item and all items Filter, sort, and apply pagination Examples GET all advertisers GET a single advertiser Request Response GET all campaigns POST a campaign Request Response

    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

    Treat any received credentials as confidential and don't share them with third parties.

     

    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.

    Resource Description
    advertisers Creating an advertiser is the very first step since it can be linked to campaigns and creatives.
    creatives Creatives must be linked to an advertiser and a line item. Adding trackers to creatives is optional.
    trackers Trackers (optional) are used for measurement purposes. They are linked to creatives, TcfVendor, and TcfPurpose. Use GET TcfVendor and GET TcfPurpose to retrieve them.
    campaigns Campaigns contain information about the associated advertiser and the allocated period of time.
    campaign budgets Campaign budgets are created and linked to an existing campaign.
    line items Line items contain information about the advertiser’s targeting (mandatory) and a dedicated budget (optional). A line item must be linked to an existing campaign and to a creative.
    line item budgets Optionally, line item budgets can be added to existing line items for a more granular budget management.

    Available methods 

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

    Method Description
    POST Creates an item 
    GET Retrieves one or all items
    PATCH Updates an item
    DELETE Deletes an item

    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. For more information about the available parameters and operators, see Swagger UI of the Activation API. 

    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' \

    ⓘ Note: this request retrieves the advertiser with the advertiser ID: 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": 8,
          "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"
      }
    }

    RELATED ARTICLES