Campaign API

How could I use the Campaign API?

With the Campaign API, you can get tracker, subtracker, and partner information without having to use the Adjust dashboard. With this functionality, you can also remotely create multiple trackers and access all of your app’s network, campaign, adgroup, and creative level trackers.

To demonstrate a use case scenario for this function, imagine that a travelling client is rolling out a new offer for their users in different regions and they’re planning to run a new campaign for that with AppLovin and AdColony. For those campaigns, they would definitely need new trackers broken down per region. They’d also like to track ad spend for those campaigns and our Campaign API will allow them to do so. Here's how:

  • To check if there’re any existing trackers with AppLovin and AdColony, they need to use GET Network Trackers

  • For this scenario, let's say there aren’t any trackers already in place. They need to use CREATE Network Tracker (level 1) for those two partners.

  • Then, they might want to GET Partner List to find out Partner IDs associated with those partners to be able to link to those.

  • Now that they already have the partner IDs, with UPDATE Tracker, they can now link created trackers to the partners and set their cost parameters on.

Now there will be a full tracker in place with default AppLovin and AdColony campaign structures, with Adcolony having their cost parameters and any other default parameters that a network is appending to a tracker.

The following documentation explains how to create and receive tracker and campaign information using queries to the Campaign API.

Versioning

The Campaign API version updates with major releases; minor releases without breaking changes don't require new versions. The API version is set in the URL paths for all of the requests.

Version 1 example:  https://api.adjust.com/public/v1/apps/{app_token}/trackers

The following documentation is specific to the API V1.

API Authentication

To access the Campaign API, specify the API token associated with your user (located in the Adjust dashboard under "Account Settings > User Details > API Token"). This documentation refers to this user token as your authentication token.

The user token and its dashboard user have the same user permissions.

To authenticate requests when using the API, provide the following HTTP Header to the requests:

Authorization: Token token=user_token_here

Response Format

Requests to the Campaign API are in application/json format and return json responses.

The response structure is loosely based off of Google's JSON API style guide: https://google.github.io/styleguide/jsoncstyleguide.xml

Success Response

To help ensure that you're on the right path, here is the Campaign API response structure for successful requests:

{
  "data": {
    "api_version": //request_api_version,
    "request_id": //alphanumeric_request_id,
    "timestamp": //server_timestamp,
    "paging": {
      "page_size": //page_size,
      "collection_size": //total_elements_on_current_page,
      "total": //total_elements,
      "next": //url_for_next_page,
      "previous": //url_for_previous_page,
      "cursors": {
        "after": //after_cursor,
        "before": //before_cursor
      },
    },
    "items": [
     /// The list of elements requested
    ]
  }
}
Field Definitions:
FieldFormatDescriptionExample
api_versionstringVersion of the API response (this will match the version specified by the user when making the request)1
request_idstringUnique identifier for the request made by the userFcK55-tdJUDOWQIAABsB
timestampstring YYYY-MM-DDTHH:MM:MMZDate on the server at time of request2019-09-09T09:07:06Z
pagingobjectContains the fields for the pagination 
paging.totalstring (numeric)Total size of the elements in the database1000
paging.page_sizestring (numeric)Maximal amount of elements in the current page50
paging.collection_sizestring (numeric)Amount of elements in the current page49
paging.nextstring (url)Link for getting the next page of the results. If the current page is the last one, the value will be nilhttps://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?after=g2wAAAACYhW1_gxkAANuaWxq&limit=50
paging.previousstring (url)Link for getting the previous page of the results. If the current page is the first one, the value will be nilhttps://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?before=g2wAAAACYhW1_gxkAANuaWxq&limit=50
paging.cursorsobjectContains the cursors used for pagination (more information about pagination in the next chapter) 
paging.cursors.afterstringCursor to specify for getting the next pageg2wAAAACYhW1_gxkAANuaWxq
paging.cursors.beforestringCursor to specify for getting the next pageg2wAAAACYhW1_gxkAANuaWxq
itemsarrayList of elements requested from the API (refer to the corresponding endpoint documentation for item description) 

 

Error Response

If, however, something may have gone astray, here is the Campaign API response structure for erroneous requests:

{
  "error": {
    "api_version": //request_api_version,
    "request_id": //alphanumeric_request_id,
    "timestamp": //server_timestamp,
    "message": //error_message
  }
}

Field Definitions:
 
FieldFormatDescriptionExample
api_versionstringVersion of the API response (this will match the version specified by the user when making the request)1
request_idstringUnique identifier for the request made by the userFcK55-tdJUDOWQIAABsB
timestampstring "YYYY-MM-DDTHH:MM:MMZ"Date on the server at time of request2019-09-09T09:07:06Z
messagestringCorresponding error message indicating why the request has failed"User not authenticated"

Requests for data (GET requests) return paginated results that include next and previous URLs. The Campaign API uses cursor-based pagination: every GET response includes the after and before cursors. Additionally, every request accepts the after and before parameters with their cursor value. To customize the page limit, use the parameter: limit(otherwise the default page limit is 50 elements).

Pagination flow example:

To get trackers for the app_token yxs12pfewq, send this initial request:

GET https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers

The response will have a paging section like this:
 

"paging": {
      "page_size": "50",
      "collection_size": "49",
      "total": "199"
      "cursors": {
        "after": "g2wAAAACYhW1_gxkAANuaWxq",
        "before": nil // (the first page has no previous page)
      },
      "next": "https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?after=g2wAAAACYhW1_gxkAANuaWxq&limit=50",
      "previous": nil // (the first page has no previous page)
    }

To go to the second page, add the after value (located inside cursors) to the next GET request in the parameters (with the corresponding parameter name). For example:

GET https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?after=g2wAAAACYhW1_gxkAANuaWxq

Or, simply use the URL in the next attribute in the paging element:

GET https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?after=g2wAAAACYhW1_gxkAANuaWxq&limit=50

To go to previous pages, follow the same flow but use the before value or the URL set to previous.

Endpoints

Get Network Trackers

Use this endpoint to get the network-level trackers for your specified app.

Endpoint

GET https://api.adjust.com/public/v1/apps/{app_token}/trackers

URL Parameters

ParameterFormatDescriptionExample
app_tokenstringApplication Tokenyxs12pfewg

Query Parameters

ParameterFormatDescriptionExample
afterstringCursor to get elements from the next page (optional)g2wAAAACYhW1_gxkAANuaWxq
beforestringCursor to get elements from the previous page (optional)g2wAAAACYhYGiAhkAANuaWxq
limitnumeric 0 and aboveMaximum amount of elements for the requested page50
For more details, see pagination.

Response Format

Item Definition

FieldFormatDescriptionExample
namestringThe tracker's nameAdroll
labelstringThe last level part of the name of the trackerAdroll
levelintegerLevel of the tracker where according to adjust campaign structure Network = 1, Campaign = 2, Adgroup = 3, and Creative = 41
archivedboolean (true/false)Specifies whether the tracker was archived or nottrue
has_subtrackersboolean (true/false)Indicates if the tracker has subtrackers or nottrue
partner_idintegerIndicates the ID of the partner attached to the tracker, for example, our partner Adroll's ID is 33
cost_data_enabledboolean (true/false)Indicates if the tracker has cost_data enabled or notfalse
impression_urlstringURL of the tracker for impression trackinghttps://view.adjust.com/impression/abc123
urlstringURL of the tracker for trackinghttps://app.adjust.com/abc123
click_urlstringURL of the tracker for click trackinghttps://app.adjust.com/abc123


Item example:

{
  "name": "Adroll",
  "token": "abc123",
  "label": "Adroll",
  "level": 1,
  "archived": false,
  "has_subtrackers": false,
  "partner_id": 3,
  "cost_data_enabled": false,
  "url": "https://app.adjust.com/abc123",
  "click_url": "https://app.adjust.com/abc123?campaign={campaign_name}&idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
  "impression_url": "https://s2s.adjust.com/impression/abc123?campaign={campaign_name}&idfa={idfa}&s2s=1",
 }

Example response (including only one tracker):

GET https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?limit=1
{
  "data": {
    "api_version": "1",
    "request_id": "FcK55-tdJUDOWQIAABsB",
    "timestamp": "2019-09-09T09:07:06Z",
    "paging": {
      "page_size": "1",
      "collection_size": "1",
      "total": "199",
      "next": "https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?after=g2wAAAACYhW1_gxkAANuaWxq&limit=1",
      "previous": nil,
      "cursors": {
        "after": "g2wAAAACYhW1_gxkAANuaWxq",
        "before": nil
      }
    },
    "items": [
      {
        "archived": false,
        "has_subtrackers": false,
        "partner_id": 3,
        "cost_data_enabled": false,
        "label": "Adroll",
        "level": 1,
        "name": "Adroll",
        "token": "abc123",
        "url": "https://app.adjust.com/abc123",
        "click_url": "https://app.adjust.com/abc123?campaign={campaign_name}&idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
        "impression_url": "https://s2s.adjust.com/impression/abc123?campaign={campaign_name}&idfa={idfa}&s2s=1",
        }
        ]
  }
}

Get Subtrackers

Use this endpoint to get the subtrackers of your specified tracker,

Endpoint

GET https://api.adjust.com/public/v1/apps/{app_token}/trackers/{tracker_token}/children
ParameterFormatDescriptionExample
app_tokenstringApplication tokenyxs12pfewq
tracker_tokenstringTracker tokenabc123

Query Parameters

ParameterFormatDescriptionExample
afterstringCursor to get elements from the next page (optional)g2wAAAACYhW1_gxkAANuaWxq
beforestringCursor to get elements from the previous page (optional)g2wAAAACYhYGiAhkAANuaWxq
limitnumeric 0 and aboveMaximum amount of elements for the requested page50

For more details, see pagination

Response

The return will list subtrackers using the Response Format

Item Definition

FieldFormatDescriptionExample
namestringThe tracker's nameAdroll::SpringCampaign
labelstringThe last level part of the name of the trackerSpringCampaign
levelintegerLevel of the tracker2
archivedboolean (true/false)Specifies whether the tracker was archived or nottrue
has_subtrackersboolean (true/false)Indicates if the tracker has subtrackers or nottrue
partner_idintegerIndicates the id of the partner attached to the tracker3
cost_data_enabledboolean (true/false)Indicates if the tracker has cost_data enabled or notfalse
impression_urlstringURL of the tracker for impression trackinghttps://view.adjust.com/impression/abc123
urlstringURL of the tracker for trackinghttps://view.adjust.com/impression/abc123

Item example:
{
  "name": "Adroll::SpringCampaign",
  "token": "def456",
  "label": "SpringCampaign",
  "level": 2,
  "archived": false,
  "has_subtrackers": false,
  "partner_id": 3,
  "cost_data_enabled": false,
  "url": "https://app.adjust.com/def456",
  "click_url": "https://app.adjust.com/def456?idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
  "impression_url": "https://s2s.adjust.com/impression/def456?idfa={idfa}&s2s=1",
 }

Example response (including one tracker):

GET https://api.adjust.com/public/v1/apps/yxs12pfew/trackers/abc123/children?limit=1
{
  "data": {
    "api_version": "1",
    "request_id": "FcK55-tdJUDOWQIAABsB",
    "timestamp": "2019-09-09T09:07:06Z",
    "paging": {
      "page_size": "1",
      "collection_size": "1",
      "total": "199",
      "next": "https://api.adjust.com/public/v1/apps/yxs12pfew/trackers/abc123/children?after=g2wAAAACYhW1_gxkAANuaWxq&limit=1",
      "previous": nil,
      "cursors": {
        "after": "g2wAAAACYhW1_gxkAANuaWxq",
        "before": nil
      }
    },
    "items": [
      {
        "name": "Adroll::SpringCampaign",
        "token": "def456",
        "label": "SpringCampaign",
        "level": 2,
        "archived": false,
        "has_subtrackers": false,
        "partner_id": 3,
        "cost_data_enabled": false,
        "url": "https://app.adjust.com/def456",
        "click_url": "https://app.adjust.com/def456?idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
        "impression_url": "https://s2s.adjust.com/impression/def456?idfa={idfa}&s2s=1",
      }
    ]
  }
}

Create Tracker

Use this endpoint to create new trackers or subtrackers.

Endpoint: POST https://api.adjust.com/public/v1/apps/{app_token}/trackers

URL Parameters

ParameterFormatDescriptionExample
app_tokenstringApplication tokenyxs12pfewg

Request Body

The request body can be sent as query parameters or application/json content.
ParameterFormatDescriptionExample
namestringName for the new trackerAdroll
parent_tokenstringTracker token for the parent tracker (only necessary when creating a subtracker)abc123
Request Example:

Network Tracker

json payload example:
POST https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers
{
  "name": "Adroll"
}
Subtracker (at any level)

json payload example:
POST https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers
{
  "name": "Adroll"
  "parent_token": "abc123"
}

Response:

The return will include your new tracker using the Response Format

Item Definition
 
FieldFormatDescriptionExample
namestringThe tracker's nameAdroll::Spring Campaign::PubID123
labelstringThe last level part of the name of the trackerPubID123
levelintegerLevel of the tracker where according to adjust campaign structure Network is 1, Campaign is 2, Adgroup is 3, and Creative is 43
archivedboolean (true/false)Specifies whether the tracker was archived or nottrue
has_subtrackersboolean (true/false)/td>Indicates if the tracker has subtrackers or nottrue
partner_idintegerIndicates the id of the partner attached to the tracker, for example, our partner Adroll's ID is 33
cost_data_enabledboolean (true/false)Indicates if the tracker has cost_data enabled or nottrue
impression_urlstringURL of the tracker for impression trackinghttps://view.adjust.com/impression/def456
urlstringURL of the tracker for trackinghttps://view.adjust.com/impression/def456

Item example:
{
  "name": "Adroll::SpringCampaign::PubID123",
  "token": "ghi789",
  "label": "PubId123",
  "level": 3,
  "archived": false,
  "has_subtrackers": false,
  "partner_id": 3,
  "cost_data_enabled": false,
  "url": "https://app.adjust.com/ghi789",
  "click_url": "https://app.adjust.com/ghi789?idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
  "impression_url": "https://s2s.adjust.com/impression/ghi789?idfa={idfa}&s2s=1",
 }


Example response (for network-level trackers):

POST https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers
{
  "name": "Adroll"
}
{
  "data": {
    "api_version": "1",
    "request_id": "FcK55-tdJUDOWQIAABsB",
    "timestamp": "2019-09-09T09:07:06Z",
    "items": [
      {
        "name": "Adroll",
        "token": "abc123",
        "label": "Adroll",
        "level": 1,
        "archived": false,
        "has_subtrackers": false,
        "partner_id": 3,
        "cost_data_enabled": false,
        "url": "https://app.adjust.com/abc123",
        "click_url": "https://app.adjust.com/abc123?campaign={campaign_name}&idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
        "impression_url": "https://s2s.adjust.com/impression/abc123?campaign={campaign_name}&idfa={idfa}&s2s=1",
      }
    ]
  }
}

Example response (for subtrackers):
POST https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers
{
  "parent_tracker": "Adroll"
  "name": "SpringCampaign"
}
{
  "data": {
    "api_version": "1",
    "request_id": "FcK55-tdJUDOWQIAABsB",
    "timestamp": "2019-09-09T09:07:06Z",
    "items": [
      {
        "name": "Adroll::SpringCampaign",
        "token": "def456",
        "label": "SpringCampaign",
        "level": 2,
        "archived": false,
        "has_subtrackers": false,
        "partner_id": 3,
        "cost_data_enabled": false,
        "url": "https://app.adjust.com/def456",
        "click_url": "https://app.adjust.com/def456?campaign={campaign_name}&idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
        "impression_url": "https://s2s.adjust.com/impression/def456?campaign={campaign_name}&idfa={idfa}&s2s=1",
      }
    ]
  }
}

Update Tracker

Using this endpoint users can update trackers.

Endpoint:

PATCH https://api.adjust.com/public/v1/apps/{app_token}/trackers/{tracker_token}

URL Parameters
ParameterFormatDescriptionExample
app_tokenstringApplication tokenyxs12pfewq
tracker_tokenstringTracker tokenabc123

Request Body

The request body can be sent both as query parameters, or as application/json content. None of the parameters are required - the API will only update the specified ones.
ParameterFormatDescriptionExample
partner_idintegerID of the partner to be attached to the tracker1
cost_data_enabledboolean (true/false)Indicates if the cost data should be enabled for the trackertrue
Request Example:

json payload example:
PATCH https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers/abc123
{
  "partner_id": 1,
  "cost_data_enabled": false
}

Response

It will return the updated tracker using the Response Format.

Item Definition
 
FieldFormatDescriptionExample
namestringThe tracker's nameAdColony
labelstringThe last level part of the name of the trackerAdColony
levelintegerLevel of the tracker where according to adjust campaign structure Network is 1, Campaign is 2, Adgroup is 3, and Creative is 41
archivedboolean (true/false)Specifies whether the tracker was archived or nottrue
has_subtrackersboolean (true/false)Indicates if the tracker has subtrackers or nottrue
partner_idintegerIndicates the ID of the partner attached to the tracker, for example, our partner Adcolony's ID is 174174
cost_data_enabledboolean (true/false)Indicates if the tracker has cost_data enabled or nottrue
impression_urlstringURL of the tracker for impression trackinghttps://view.adjust.com/impression/klm789
urlstringURL of the tracker for trackinghttps://view.adjust.com/impression/klm789
Item example:
{
  "name": "Adcolony",
  "token": "klm789",
  "label": "Adcolony",
  "level": 1,
  "archived": false,
  "has_subtrackers": false,
  "partner_id": 174,
  "cost_data_enabled": true,
  "url": "https://app.adjust.com/klm789",
  "impression_url": "https://s2s.adjust.com/impression/klm789?s2s=1&idfa=[IDFA]&gps_adid=[GOOGLE_AD_ID]&ip_address=  [IP_ADDRESS]&adcolony_click_id=[CLICK_ID]&android_id_upper_sha1=[SHA1_ANDROID_ID]&cost_id=[CLICK_ID]&cost_type=[BID_TYPE]&cost_amount=[BID]&cost_currency=USD,
   "click_url": "https://s2s.app.adjust.com/klm789?s2s=1&idfa=[IDFA]&gps_adid=[GOOGLE_AD_ID]&ip_address=[IP_ADDRESS]&adcolony_click_id=[CLICK_ID]&android_id_upper_sha1=[SHA1_ANDROID_ID]&cost_id=[CLICK_ID]&cost_type=[BID_TYPE]&cost_amount=[BID]&cost_currency=USD"
 }

Example response:

PATCH https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers/klm789?partner_id=174&cost_data_enabled=true
{
  "data": {
    "api_version": "1",
    "request_id": "FcK55-tdJUDOWQIAABsB",
    "timestamp": "2019-09-09T09:07:06Z",
    "items": [
      {
        "name": "Adcolony",
        "token": "klm789",
        "label": "Adcolony",
        "level": 1,
        "archived": false,
        "has_subtrackers": false,
        "partner_id": 174,
        "cost_data_enabled": true,
        "url": "https://app.adjust.com/klm789",
        "impression_url": "https://s2s.adjust.com/impression/klm789?s2s=1&idfa=[IDFA]&gps_adid=[GOOGLE_AD_ID]&ip_address=  [IP_ADDRESS]&adcolony_click_id=[CLICK_ID]&android_id_upper_sha1=[SHA1_ANDROID_ID]&cost_id=[CLICK_ID]&cost_type=[BID_TYPE]&cost_amount=[BID]&cost_currency=USD,
        "click_url": "https://s2s.app.adjust.com/klm789?s2s=1&idfa=[IDFA]&gps_adid=[GOOGLE_AD_ID]&ip_address=[IP_ADDRESS]&adcolony_click_id=[CLICK_ID]&android_id_upper_sha1=[SHA1_ANDROID_ID]&cost_id=[CLICK_ID]&cost_type=[BID_TYPE]&cost_amount=[BID]&cost_currency=USD"
      }
    ]
  }
}

Get Partners

Use this endpoint to get a list of partners.

Endpoint: GET https://api.adjust.com/public/v1/partners


Query Parameters

ParameterFormatDescriptionExample
afterstringCursor to get elements from the next page (optional)g2wAAAACYhW1_gxkAANuaWxq
beforestringCursor to get elements from the previous page (optional)g2wAAAACYhYGiAhkAANuaWxq
limitnumeric 0 and aboveMaximum amount of elements for the requested page50
For more details, see pagination

Response: 

The return will list partners using the Response Format.

Item Definition:
 
FieldFormatDescriptionExample
idintegerThe partner's ID174
display_namestringThe partner's nameAdColony
support_cost_databoolean (true/false)Indicate if partner support cost data parameterstrue

Item example:
{
  "id": 174,
  "display_name": "Adcolony",
  "supports_cost_data": true
 }

Example response (including one partner):

GET https://api.adjust.com/public/v1/partners?limit=1
 
{
  "data": {
    "api_version": "1",
    "request_id": "FcK55-tdJUDOWQIAABsB",
    "timestamp": "2019-09-09T09:07:06Z",
    "paging": {
      "page_size": "1",
      "collection_size": "1",
      "total": "199",
      "next": "https://api.adjust.com/public/v1/partners?after=g2wAAAACYhW1_gxkAANuaWxq&limit=1",
      "previous": nil,
      "cursors": {
        "after": "g2wAAAACYhW1_gxkAANuaWxq",
        "before": nil
      }
    },
    "items": [
      {
        "id": 174,
        "display_name": "Adcolony",
        "supports_cost_data": true
      }
    ]
  }
}

On this topic