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:

Field	Format	Description	Example
api_version	string	Version of the API response (this will match the version specified by the user when making the request)	1
request_id	string	Unique identifier for the request made by the user	FcK55-tdJUDOWQIAABsB
timestamp	string YYYY-MM-DDTHH:MM:MMZ	Date on the server at time of request	2019-09-09T09:07:06Z
paging	object	Contains the fields for the pagination
paging.total	string (numeric)	Total size of the elements in the database	1000
paging.page_size	string (numeric)	Maximal amount of elements in the current page	50
paging.collection_size	string (numeric)	Amount of elements in the current page	49
paging.next	string (url)	Link for getting the next page of the results. If the current page is the last one, the value will be nil	https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?after=g2wAAAACYhW1_gxkAANuaWxq&limit=50
paging.previous	string (url)	Link for getting the previous page of the results. If the current page is the first one, the value will be nil	https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?before=g2wAAAACYhW1_gxkAANuaWxq&limit=50
paging.cursors	object	Contains the cursors used for pagination (more information about pagination in the next chapter)
paging.cursors.after	string	Cursor to specify for getting the next page	g2wAAAACYhW1_gxkAANuaWxq
paging.cursors.before	string	Cursor to specify for getting the next page	g2wAAAACYhW1_gxkAANuaWxq
items	array	List 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:

Field	Format	Description	Example
api_version	string	Version of the API response (this will match the version specified by the user when making the request)	1
request_id	string	Unique identifier for the request made by the user	FcK55-tdJUDOWQIAABsB
timestamp	string "YYYY-MM-DDTHH:MM:MMZ"	Date on the server at time of request	2019-09-09T09:07:06Z
message	string	Corresponding error message indicating why the request has failed	"User not authenticated"

Pagination

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

Parameter	Format	Description	Example
app_token	string	Application Token	yxs12pfewg

Query Parameters

Parameter	Format	Description	Example
after	string	Cursor to get elements from the next page (optional)	g2wAAAACYhW1_gxkAANuaWxq
before	string	Cursor to get elements from the previous page (optional)	g2wAAAACYhYGiAhkAANuaWxq
limit	numeric 0 and above	Maximum amount of elements for the requested page	50

For more details, see pagination.

Response Format

Item Definition

Field	Format	Description	Example
name	string	The tracker's name	Adroll
label	string	The last level part of the name of the tracker	Adroll
level	integer	Level of the tracker where according to adjust campaign structure Network = 1, Campaign = 2, Adgroup = 3, and Creative = 4	1
archived	boolean (true/false)	Specifies whether the tracker was archived or not	true
has_subtrackers	boolean (true/false)	Indicates if the tracker has subtrackers or not	true
partner_id	integer	Indicates the ID of the partner attached to the tracker, for example, our partner Adroll's ID is 3	3
cost_data_enabled	boolean (true/false)	Indicates if the tracker has cost_data enabled or not	false
impression_url	string	URL of the tracker for impression tracking	https://view.adjust.com/impression/abc123
url	string	URL of the tracker for tracking	https://app.adjust.com/abc123
click_url	string	URL of the tracker for click tracking	https://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

Parameter	Format	Description	Example
app_token	string	Application token	yxs12pfewq
tracker_token	string	Tracker token	abc123

Query Parameters

Parameter	Format	Description	Example
after	string	Cursor to get elements from the next page (optional)	g2wAAAACYhW1_gxkAANuaWxq
before	string	Cursor to get elements from the previous page (optional)	g2wAAAACYhYGiAhkAANuaWxq
limit	numeric 0 and above	Maximum amount of elements for the requested page	50

For more details, see pagination

Response

The return will list subtrackers using the Response Format

Item Definition

Field	Format	Description	Example
name	string	The tracker's name	Adroll::SpringCampaign
label	string	The last level part of the name of the tracker	SpringCampaign
level	integer	Level of the tracker	2
archived	boolean (true/false)	Specifies whether the tracker was archived or not	true
has_subtrackers	boolean (true/false)	Indicates if the tracker has subtrackers or not	true
partner_id	integer	Indicates the id of the partner attached to the tracker	3
cost_data_enabled	boolean (true/false)	Indicates if the tracker has cost_data enabled or not	false
impression_url	string	URL of the tracker for impression tracking	https://view.adjust.com/impression/abc123
url	string	URL of the tracker for tracking	https://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

Parameter	Format	Description	Example
app_token	string	Application token	yxs12pfewg

Request Body

The request body can be sent as query parameters or application/json content.

Parameter	Format	Description	Example
name	string	Name for the new tracker	Adroll
parent_token	string	Tracker 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

Field	Format	Description	Example
name	string	The tracker's name	Adroll::Spring Campaign::PubID123
label	string	The last level part of the name of the tracker	PubID123
level	integer	Level of the tracker where according to adjust campaign structure Network is 1, Campaign is 2, Adgroup is 3, and Creative is 4	3
archived	boolean (true/false)	Specifies whether the tracker was archived or not	true
has_subtrackers	boolean (true/false)/td>	Indicates if the tracker has subtrackers or not	true
partner_id	integer	Indicates the id of the partner attached to the tracker, for example, our partner Adroll's ID is 3	3
cost_data_enabled	boolean (true/false)	Indicates if the tracker has cost_data enabled or not	true
impression_url	string	URL of the tracker for impression tracking	https://view.adjust.com/impression/def456
url	string	URL of the tracker for tracking	https://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

Parameter	Format	Description	Example
app_token	string	Application token	yxs12pfewq
tracker_token	string	Tracker token	abc123

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.

Parameter	Format	Description	Example
partner_id	integer	ID of the partner to be attached to the tracker	1
cost_data_enabled	boolean (true/false)	Indicates if the cost data should be enabled for the tracker	true

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

Field	Format	Description	Example
name	string	The tracker's name	AdColony
label	string	The last level part of the name of the tracker	AdColony
level	integer	Level of the tracker where according to adjust campaign structure Network is 1, Campaign is 2, Adgroup is 3, and Creative is 4	1
archived	boolean (true/false)	Specifies whether the tracker was archived or not	true
has_subtrackers	boolean (true/false)	Indicates if the tracker has subtrackers or not	true
partner_id	integer	Indicates the ID of the partner attached to the tracker, for example, our partner Adcolony's ID is 174	174
cost_data_enabled	boolean (true/false)	Indicates if the tracker has cost_data enabled or not	true
impression_url	string	URL of the tracker for impression tracking	https://view.adjust.com/impression/klm789
url	string	URL of the tracker for tracking	https://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

Parameter	Format	Description	Example
after	string	Cursor to get elements from the next page (optional)	g2wAAAACYhW1_gxkAANuaWxq
before	string	Cursor to get elements from the previous page (optional)	g2wAAAACYhYGiAhkAANuaWxq
limit	numeric 0 and above	Maximum amount of elements for the requested page	50

For more details, see pagination

Response:

The return will list partners using the Response Format.

Item Definition:

Field	Format	Description	Example
id	integer	The partner's ID	174
display_name	string	The partner's name	AdColony
support_cost_data	boolean (true/false)	Indicate if partner support cost data parameters	true

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
      }
    ]
  }
}