Upload Ad Spend Data

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. Request to upload ad spend data in CSV format. The Content-Type in the Request Header uses multipart/form-data.

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.

POST

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

Request

Headers

string

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

string

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

string

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

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

200

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

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

API Reference

Tracking Link

Server-to-Server Event

Actuals Report

Revenue Report

Active Users Report

Retention Report

Raw Data

Attribution Result

Self-Serve Data Upload

SKAdNetwork Configuration API

Ad Spend Data

Metric 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

200

​Ad Spend Data

​Metric 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

​200

Ad Spend Data

Metric Data

Header

CSV file format and schema

Sample CSV File

🚧 Case Sensitivity

Overwrite (correct) Previously Ingested Ad Spend

Delete Previously Ingested Ad Spend

Note

Request

Headers

Response

200