Self-Serve Data Upload

Last updated March 21, 2024

Upload data directly through the API and view the data together in reports.

Ad Spend Data

Directly upload impressions, clicks, and cost data for media sources that don't report spend by API.

Metric Data

Upload new metric data directly and view the status of your uploads.

Upload Ad Spend Data

POST

https://api.airbridge.io/self-serve-data/v1/ad-spend/requests

Try API Request

Request to upload ad spend data in CSV format.

The Content-Type in the Request Header uses multipart/form-data.

header-multipart

1
Content-Type: multipart/form-data; charset=utf-8

CSV file format and schema

Content rules and schema of ad spend CSV files

Category	Column Name	Type	Description	Required
Group by	date	string	The date the spend was incurred. The date must be in the format 'YYYY-MM-DD' This date should correspond with the timezone set in the Airbridge app. Future dates are not permitted. Upload requests that violate this condition will not be processed.	Required
Group by	channel	string	The channel name. Integration channel matches the one used in the Airbridge dashboard with a unique lowercase latter. Note that channels already provided by Airbridge cannot be uploaded.	Required
Group by	currency	string	The currency. Must use capitalized, three-letter currency codes that comply with ISO 4217. e.g. KRW, USD	Required
Group by	campaign	string	The campaign name	Required
Metric	impressions	int	The impression count. Note that comma (,) cannot be used as a delimiter for numeric data.	Required
Metric	clicks	int	The click count. Note that comma (,) cannot be used as a delimiter for numeric data.	Required
Metric	cost	float	The ad spend. Note that comma (,) cannot be used as a delimiter for numeric data.	Required
Group by	campaign_id	string	The ID of campaign.	Optional
Group by	ad_group	string	The ad group.	Optional
Group by	ad_group_id	string	The ID of ad group.	Optional
Group by	ad_creative	string	The ad creative.	Optional
Group by	ad_creative_id	string	The ID of ad creative.	Optional
Group by	term	string	The term.	Optional
Group by	term_id	string	The ID of term.	Optional
Group by	ad_account	string	The ad account.	Optional
Group by	ad_account_id	string	The ID of ad account.	Optional
Group by	sub_publisher	string	The sub publisher	Optional
Group by	sub_sub_publisher_1	string	The sub-sub publisher 1	Optional
Group by	sub_sub_publisher_2	string	The sub-sub publisher 2	Optional
Group by	sub_sub_publisher_3	string	The sub-sub publisher 3	Optional
Group by	country	string	2-digit lowercase country value. e.g. kr, us, gb, fr	Optional
Group by	os_name	string	The OS Name Be aware that data in columns with a type defined as 'string' is case-sensitive. e.g. Android, iOS	Optional

Sample CSV File

Example CSV File

🚧 Case Sensitivity

Please be aware that data in columns with a type defined as 'string' is case-sensitive.

Note that Airbridge records mobile OS names as 'Android' and 'iOS'. When uploading your data, it's essential to use 'Android' and 'iOS' for OS names. Failure to do so may result in separate rows in the dashboard when data is grouped by results. Please adhere to this naming convention for consistency and accurate data representation.

Overwrite (correct) Previously Ingested Ad Spend

Previously ingested ad spend can be overwritten by using CSV files that contain data with the identical key of data previously ingested.

The key is formed from the 'date', 'channel', and 'campaign' fields. If the keys match, data ingested last overwrites data previously ingested.

[Example A]

1. 2022-08-03: Upload data for date, channel, campaign, and ad_group.

date	channel	campaign	ad_group	currency	clicks	impressions	cost
2022-08-01	owned_website	retargeting_campaign	2030_female	KRW	1000	10000	100000
2022-08-01	owned_website	retargeting_campaign	2030_male	KRW	800	12000	80000

2. 2022-08-04: Upload data for date, channel and campaign.

date	channel	campaign	currency	clicks	impressions	cost
2022-08-01	owned_website	retargeting_campaign	KRW	2000	20000	150000

3. Result: Spend data from '2022-08-03' was overwritten by spend data from '2022-08-04' because '2022-08-04' was last ingested and the identical key is the same. (ad group is overwritten null)

date	channel	campaign	currency	clicks	impressions	cost
2022-08-01	owned_website	retargeting_campaign	KRW	2000	20000	150000

[Example B]

1. 2022-08-03: Upload data for date, channel and campaign.

date	channel	campaign	currency	clicks	impressions	cost
2022-08-01	owned_website	retargeting_campaign	KRW	1000	10000	100000

2. 2022-08-04: Upload data for date, channel, campaign and ad_group.

date	channel	campaign	ad_group	currency	clicks	impressions	cost
2022-08-01	owned_website	retargeting_campaign	2030_female	KRW	2000	20000	150000

3. Result: Spend data from '2022-08-03' was overwritten by spend data from '2022-08-04' because '2022-08-04' was last ingested and the identical key is the same.

date	channel	campaign	ad_group	currency	clicks	impressions	cost
2022-08-01	owned_website	retargeting_campaign	2030_female	KRW	2000	20000	150000

[Example C]

1. 2022-08-03: Upload data for date, channel, campaign and ad_group

date	channel	campaign	ad_group	currency	clicks	impressions	cost
2022-08-01	owned_website	promotion_campaign	2030_female	KRW	1200	15000	10000
2022-08-01	owned_website	retargeting_campaign	2030_female	KRW	1000	10000	100000
2022-08-01	owned_website	retargeting_campaign	2030_male	KRW	800	12000	80000

2. 2022-08-04: Upload data for date, channel, campaign and ad_group

date	channel	campaign	ad_group	currency	clicks	impressions	cost
2022-08-01	owned_website	retargeting_campaign	2030_male	KRW	900	15000	90000
2022-08-01	owned_website	ua_campaign	2030_female	KRW	1200	15000	120000

3. Result: Based on the values 'date', 'channel', and 'campaign', the data was overwritten by '2022-08-04'

date	channel	campaign	ad_group	currency	clicks	impressions	cost
2022-08-01	owned_website	promotion_campaign	2030_female	KRW	1200	15000	10000
2022-08-01	owned_website	retargeting_campaign	2030_male	KRW	900	15000	90000
2022-08-01	owned_website	ua_campaign	2030_female	KRW	1200	15000	120000

Delete Previously Ingested Ad Spend

To delete previously uploaded cost data, re-upload the clicks, impressions, and cost metrics for the same identity key with all values set to 0.

Note

Only be used as an API token for Owner, In-house Marketer permission accounts.
A maximum of 10000 rows are allowed in a CSV file for a single request.
The maximum size of a CSV file in a single request is 1 MB.
Column values of type string are limited to at least one character and up to 256 characters.
Ensure there are no spaces before or after the column name and value.

Request

Headers

Accept-Language

string

You can specify the language to use for API requests and responses. It follows the ISO-639-1 format.

Content-Type

string

Represents the media type of the resource. Defaults to application/json.

Authorization

string

The key value to use for API requests. Instructions for getting API keys are in "how to generate API Keys".

Request

1234
curl -X POST 'https://api.airbridge.io/self-serve-data/v1/ad-spend/requests' \
  -H 'Accept-Language: ko' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}'
curl -X POST 'https://api.airbridge.io/self-serve-data/v1/ad-spend/requests' \
  -H 'Accept-Language: ko' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}'

Response

200SUCCESS

Name	Description	Example
requestId	The request ID.	08844672-62d8-4da8-9d48-e14961651e0c
status	The progress for the upload request.	ingested
prevStatus	The status before the current status.	validated
reason	The reason the upload failed.	{"date": ["invalid date"]}
createdAt	The date that request was created.	2022-08-09T08:59:15
updatedAt	The date that request was updated.	2022-08-09T08:59:15

Response

12345678
{
  "reason": null,
  "status": "uploaded",
  "createdAt": "2023-01-01T09:00:00",
  "requestId": "08844672-62d8-4da8-9d48-e14961651e0c",
  "updatedAt": "2023-01-01T09:00:00",
  "prevStatus": null
}
{
  "reason": null,
  "status": "uploaded",
  "createdAt": "2023-01-01T09:00:00",
  "requestId": "08844672-62d8-4da8-9d48-e14961651e0c",
  "updatedAt": "2023-01-01T09:00:00",
  "prevStatus": null
}

Get Ad Spend Data Upload Progress

GET

https://api.airbridge.io/self-serve-data/v1/ad-spend/requests/{request_id}

Try API Request

Request status

The status of an asynchronous request can be checked with task.status in the API request result.

Status	Description
uploaded	Data has been uploaded to the server.
validated	Validation of the uploaded file is complete.
ingested	Uploaded files ingested to the database.
succeeded	Uploaded data are processed and available for viewing in reports. Available in dashboard reports in up to 10 minutes.
failed	The processing of the uploaded file has failed and needs to be re-uploaded with the correct file, referring to the 'reason' value in the response.

Request

Headers

Accept-Language

string

You can specify the language to use for API requests and responses. It follows the ISO-639-1 format.

Content-Type

string

Represents the media type of the resource. Defaults to application/json.

Authorization

string

The key value to use for API requests. Instructions for getting API keys are in "how to generate API Keys".

Path Params

request_id

Requiredstring

The request_id returned by the result of the 'Upload Data' API.

Request

1234
curl -X GET 'https://api.airbridge.io/self-serve-data/v1/ad-spend/requests/08844672-62d8-4da8-9d48-e14961651e0c' \
  -H 'Accept-Language: ko' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}'
curl -X GET 'https://api.airbridge.io/self-serve-data/v1/ad-spend/requests/08844672-62d8-4da8-9d48-e14961651e0c' \
  -H 'Accept-Language: ko' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}'

Response

200SUCCESS

Response

12345678
{
  "reason": "{\"date\": [\"invalid date\"]}",
  "status": "failed",
  "createdAt": "2022-08-24T11:54:18",
  "requestId": "846b78f9-1b6f-4ede-a253-619ca68fcebf",
  "updatedAt": "2022-08-24T11:54:17",
  "prevStatus": "uploaded"
}
{
  "reason": "{\"date\": [\"invalid date\"]}",
  "status": "failed",
  "createdAt": "2022-08-24T11:54:18",
  "requestId": "846b78f9-1b6f-4ede-a253-619ca68fcebf",
  "updatedAt": "2022-08-24T11:54:17",
  "prevStatus": "uploaded"
}

Response

12345678
{
  "reason": null,
  "status": "succeeded",
  "createdAt": "2023-01-01T09:00:00",
  "requestId": "08844672-62d8-4da8-9d48-e14961651e0c",
  "updatedAt": "2022-01-01T09:00:00",
  "prevStatus": "ingested"
}
{
  "reason": null,
  "status": "succeeded",
  "createdAt": "2023-01-01T09:00:00",
  "requestId": "08844672-62d8-4da8-9d48-e14961651e0c",
  "updatedAt": "2022-01-01T09:00:00",
  "prevStatus": "ingested"
}

Upload Metric Data

POST

https://api.airbridge.io/self-serve-data/v1/metric/requests

Try API Request

Request to upload metric data in CSV format.

The Content-Type in the Request Header uses multipart/form-data.

header-multipart

1
Content-Type: multipart/form-data; charset=utf-8

CSV file format and schema

Content rules and schema of ad spend CSV files

Category	Column Name	Type	Description	Required
Group by	date	string	The date the spend was incurred. The date must be in the format 'YYYY-MM-DD' This date should correspond with the timezone set in the Airbridge app. Future dates are not permitted. Upload requests that violate this condition will not be processed.	Required
Group by	channel	string	The channel.	Required
Group by	event_category	string	The event category. It is viewed as a metric name in the report.	Required
Metric	event_value	double	The event value.	Required
Group by	campaign	string	The campaign.	Optional
Group by	ad_group	string	The ad group.	Optional
Group by	ad_creative	string	The ad creative.	Optional
Group by	content	string	The content.	Optional
Group by	event_source	string	The event source. `app`, `web`, `tracking_link`, `sms_link` (case-sensitive)	Optional
Group by	os_name	string	The OS Name. Be aware that data in columns with a type defined as 'string' is case-sensitive. e.g. Android, iOS	Optional
Group by	term	string	The term.	Optional
Group by	country	string	2-digit lowercase country value. e.g. kr, us, gb, fr	Optional
Group by	currency	string	The currency. Must use capitalized, three-letter currency codes that comply with ISO 4217. e.g. KRW, USD	Optional
Group by	sub_publisher	string	The sub publisher.	Optional
Group by	sub_sub_publisher_1	string	The sub-sub publisher 1.	Optional
Group by	sub_sub_publisher_2	string	The sub-sub publisher 2.	Optional
Group by	sub_sub_publisher_3	string	The sub-sub publisher 3.	Optional
Group by	is_first_event_per_device_id	boolean	Whether the first event is based on device ID. true or false (case-sensitive)	Optional
Group by	is_first_event_per_user_id	boolean	Whether the first event is based on user ID. true or false (case-sensitive)	Optional

Sample CSV File

Example CSV File

🚧 Case Sensitivity

Please be aware that data in columns with a type defined as 'string' is case-sensitive.

Overwrite Previously Ingested Metric Data

Previously ingested metric data can be overwritten by using CSV files that contain data with the identical key of data previously ingested.

The key is formed from the 'date', 'channel', and 'event_category' fields. If the keys match, data ingested last overwrites data previously ingested.

[Example A]

1. 2022-08-03: Upload for date, channel, campaign and ad_group.

date	channel	campaign	ad_group	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	2030_female	self_event	100000
2022-08-01	owned_website	retargeting_campaign	2030_male	self_event	80000

2. 2022-08-04: Upload for date, channel and campaign.

date	channel	campaign	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	self_event	150000

3. Result: Spend data from '2022-08-03' was overwritten by data from '2022-08-04' because '2022-08-04' was last ingested and the identical key is the same. (ad group is overwritten null)

date	channel	campaign	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	self_event	150000

[Example B]

1. 2022-08-03: Upload for date, channel and campaign.

date	channel	campaign	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	self_event	100000

2. 2022-08-04: Upload for date, channel, campaign and ad_group.

date	channel	campaign	ad_group	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	2030_female	self_event	150000

3. Result: Based on the values 'date', 'channel', and 'campaign', the data was overwritten by '2022-08-04' (ad_group value are also updated.)

date	channel	campaign	ad_group	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	2030_female	self_event	150000

[Example C]

1. 2022-08-03: Upload for date, channel, campaign and ad_group.

date	channel	campaign	ad_group	event_category	event_value
2022-08-01	owned_website	promotion_campaign	2030_female	self_event	10000
2022-08-01	owned_website	retargeting_campaign	2030_female	self_event	100000
2022-08-01	owned_website	retargeting_campaign	2030_male	self_event2	80000

2. 2022-08-04: Upload for date, channel, campaign and ad_group.

date	channel	campaign	ad_group	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	2030_male	self_event	90000
2022-08-01	owned_website	ua_campaign	2030_female	self_event	120000

3. Result: Based on the values 'date', 'channel', and 'campaign', the data was overwritten by '2022-08-04'

date	channel	campaign	ad_group	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	2030_male	self_event2	80000
2022-08-01	owned_website	retargeting_campaign	2030_male	self_event	90000
2022-08-01	owned_website	ua_campaign	2030_female	self_event	120000

Archive Data

If you want a previously uploaded metric to be invisible in a report, please request it through your CSM.

Note

Only be used as an API token for Owner, In-house Marketer permission accounts.
The order of the columns in the CSV file does not affect the upload functionality.
The maximum size of a CSV file in a single request is 1 MB.
Column values of type string are limited to at least one character and up to 256 characters.
Ensure there are no spaces before or after the column name and value.
event_category can accept alphabets and numbers.
event_category cannot contain , " \.
New data registered during upload (e.g. self_serve_test_campaign for campaign) will not be visible in the selection options when using a filter. You can use it by entering it in freeform.
If the CSV file has rows where both the groupBy and the event category are the same, the data is displayed in the report as summed values for the same row.
Upload data

date	channel	campaign	event_category	event_Value
2022-08-01	owned_website	retargeting_campaign	self_event	150000
2022-08-01	owned_website	retargeting_campaign	self_event	100000
2022-08-01	owned_website	retargeting_campaign	self_event	10000

Display report

date	channel	campaign	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	self_event	251000

Request

Headers

Accept-Language

string

You can specify the language to use for API requests and responses. It follows the ISO-639-1 format.

Content-Type

string

Represents the media type of the resource. Defaults to application/json.

Authorization

string

The key value to use for API requests. Instructions for getting API keys are in "how to generate API Keys".

Request

1234
curl -X POST 'https://api.airbridge.io/self-serve-data/v1/metric/requests' \
  -H 'Accept-Language: ko' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}'
curl -X POST 'https://api.airbridge.io/self-serve-data/v1/metric/requests' \
  -H 'Accept-Language: ko' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}'

Response

200SUCCESS

Name	Description	Example
requestId	The request ID.	08844672-62d8-4da8-9d48-e14961651e0c
status	The progress for the upload request.	ingested
prevStatus	The status before the current status.	validated
reason	The reason the upload failed.	{"date": ["invalid date"]}
createdAt	The date that request was created.	2022-08-09T08:59:15
updatedAt	The date that request was updated.	2022-08-09T08:59:15

Response

12345678
{
  "reason": null,
  "status": "uploaded",
  "createdAt": "2023-01-01T09:00:00",
  "requestId": "08844672-62d8-4da8-9d48-e14961651e0c",
  "updatedAt": "2023-01-01T09:00:00",
  "prevStatus": null
}
{
  "reason": null,
  "status": "uploaded",
  "createdAt": "2023-01-01T09:00:00",
  "requestId": "08844672-62d8-4da8-9d48-e14961651e0c",
  "updatedAt": "2023-01-01T09:00:00",
  "prevStatus": null
}

Get Metric Data Upload Progress

GET

https://api.airbridge.io/self-serve-data/v1/metric/requests/{request_id}

Try API Request

Request status

The status of an asynchronous request can be checked with task.status in the API request result.

Status	Description
uploaded	Data has been uploaded to the server.
validated	Validation of the uploaded file is complete.
ingested	Uploaded files ingested to the database.
succeeded	Uploaded data are processed and available for viewing in reports. Available in dashboard reports in up to 10 minutes.
failed	The processing of the uploaded file has failed and needs to be re-uploaded with the correct file, referring to the 'reason' value in the response.

Request

Headers

Accept-Language

string

You can specify the language to use for API requests and responses. It follows the ISO-639-1 format.

Content-Type

string

Represents the media type of the resource. Defaults to application/json.

Authorization

string

The key value to use for API requests. Instructions for getting API keys are in "how to generate API Keys".

Path Params

request_id

Requiredstring

The request_id returned by the result of the 'Upload Data' API.

Request

1234
curl -X GET 'https://api.airbridge.io/self-serve-data/v1/metric/requests/08844672-62d8-4da8-9d48-e14961651e0c' \
  -H 'Accept-Language: ko' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}'
curl -X GET 'https://api.airbridge.io/self-serve-data/v1/metric/requests/08844672-62d8-4da8-9d48-e14961651e0c' \
  -H 'Accept-Language: ko' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}'

Response

200SUCCESS

Name	Description	Example
requestId	The request ID.	08844672-62d8-4da8-9d48-e14961651e0c
status	The progress for the upload request.	ingested
prevStatus	The status before the current status.	validated
reason	The reason the upload failed.	{"date": ["invalid date"]}
createdAt	The date that request was created.	2022-08-09T08:59:15
updatedAt	The date that request was updated.	2022-08-09T08:59:15

200SUCCESS

Response

12345678
{
  "reason": null,
  "status": "succeeded",
  "createdAt": "2023-01-01T09:00:00",
  "requestId": "08844672-62d8-4da8-9d48-e14961651e0c",
  "updatedAt": "2023-01-01T09:00:00",
  "prevStatus": "ingested"
}
{
  "reason": null,
  "status": "succeeded",
  "createdAt": "2023-01-01T09:00:00",
  "requestId": "08844672-62d8-4da8-9d48-e14961651e0c",
  "updatedAt": "2023-01-01T09:00:00",
  "prevStatus": "ingested"
}

Response

12345678
{
  "reason": "{\"date\": [\"invalid date\"]}",
  "status": "failed",
  "createdAt": "2022-08-24T11:54:18",
  "requestId": "846b78f9-1b6f-4ede-a253-619ca68fcebf",
  "updatedAt": "2022-08-24T11:54:17",
  "prevStatus": "uploaded"
}
{
  "reason": "{\"date\": [\"invalid date\"]}",
  "status": "failed",
  "createdAt": "2022-08-24T11:54:18",
  "requestId": "846b78f9-1b6f-4ede-a253-619ca68fcebf",
  "updatedAt": "2022-08-24T11:54:17",
  "prevStatus": "uploaded"
}

Was this helpful?

Any questions or suggestions?

Self-Serve Data Uploadself.__wrap_n!=1&&self.__wrap_b("_R_4ilubt5upfcqbsnjb_",0.5)

Ad Spend Data

Metric Data

Upload Ad Spend Data

Header

CSV file format and schema

Content rules and schema of ad spend CSV files

Sample CSV File

🚧 Case Sensitivity

Overwrite (correct) Previously Ingested Ad Spend

[Example A]

[Example B]

[Example C]

Delete Previously Ingested Ad Spend

Note

Request

Headers

Response

200SUCCESS

Get Ad Spend Data Upload Progress

Request status

Request

Headers

Path Params

Response

200SUCCESS

200SUCCESS

Upload Metric Data

Header

CSV file format and schema

Content rules and schema of ad spend CSV files

Sample CSV File

🚧 Case Sensitivity

Overwrite Previously Ingested Metric Data

[Example A]

[Example B]

[Example C]

Archive Data

Note

Request

Headers

Response

200SUCCESS

Get Metric Data Upload Progress

Request status

Request

Headers

Path Params

Response

200SUCCESS

200SUCCESS

Self-Serve Data Upload