Self-Serve Data Upload

    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

    Request to upload ad spend data in CSV format.

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

    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. The system only accepts dates within the 92 days preceding the current date. 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

    🚧 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.

    Response

    200 SUCCESS

    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


    Get Ad Spend Data Upload Progress

    GET

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

    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

    Path Params

    request_id
    Requiredstring

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

    Response

    200 (Upload Succeeded)SUCCESS

    200 (Upload Failed)SUCCESS


    Upload Metric Data

    POST

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

    Request to upload metric data in CSV format.

    Header

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

    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. The system only accepts dates within the 92 days preceding the current date. 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

    🚧 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 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. 최종 반영: 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

    Response

    200 SUCCESS

    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


    Get Metric Data Upload Progress

    GET

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

    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

    Path Params

    request_id
    string

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

    Response

    200 (Upload Succeeded)SUCCESS

    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

    200 (Upload Failed)SUCCESS

    Was this page helpful?

    Have any questions or suggestions?