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": "xyz456",
"label": "SpringCampaign",
"level": 2,
"archived": false,
"has_subtrackers": false,
"partner_id": 3,
"cost_data_enabled": false,
"url": "https://app.adjust.com/xyz456",
"click_url": "https://app.adjust.com/xyz456?idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
"impression_url": "https://s2s.adjust.com/impression/xyz456?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": "xyz456",
"label": "SpringCampaign",
"level": 2,
"archived": false,
"has_subtrackers": false,
"partner_id": 3,
"cost_data_enabled": false,
"url": "https://app.adjust.com/xyz456",
"click_url": "https://app.adjust.com/xyz456?idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
"impression_url": "https://s2s.adjust.com/impression/xyz456?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/xyz456 |
url | string | URL of the tracker for tracking | https://view.adjust.com/impression/xyz456 |
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": "xyz456",
"label": "SpringCampaign",
"level": 2,
"archived": false,
"has_subtrackers": false,
"partner_id": 3,
"cost_data_enabled": false,
"url": "https://app.adjust.com/xyz456",
"click_url": "https://app.adjust.com/xyz456?campaign={campaign_name}&idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
"impression_url": "https://s2s.adjust.com/impression/xyz456?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
}
]
}
}