> ## Documentation Index
> Fetch the complete documentation index at: https://help.airbridge.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Ad Spend Data

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

<h4 id="ad-spend-data">
  Ad Spend Data
</h4>

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

<h4 id="metric-data">
  Metric Data
</h4>

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

Request to upload ad spend data in CSV format.

<h4 id="header">
  Header
</h4>

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

```header-multipart theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
Content-Type: multipart/form-data; charset=utf-8
```

<h4 id="csv-file-format-and-schema">
  CSV file format and schema
</h4>

##### Content rules and schema of ad spend CSV files

<div style={{ overflowX: 'auto' }}>
  <table style={{ display: 'table' }}>
    <thead>
      <tr>
        <th>
          Category
        </th>

        <th>
          Column Name
        </th>

        <th>
          Type
        </th>

        <th>
          Description
        </th>

        <th>
          Required
        </th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>
          Group by
        </td>

        <td>
          date
        </td>

        <td>
          string
        </td>

        <td>
          The date the spend was incurred.<br />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.
        </td>

        <td>
          **Required**
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          channel
        </td>

        <td>
          string
        </td>

        <td>
          The channel name.<br />[Integration channel ](https://docs.google.com/spreadsheets/d/13ThNnryqRmZQwJVecM8lZ2OB7LzA8s3cwLlQBGpbXLg/edit#gid=1415221276\&range=B:B)matches the one used in the Airbridge dashboard with a unique lowercase latter.<br />Note that channels already provided by Airbridge cannot be uploaded.
        </td>

        <td>
          **Required**
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          currency
        </td>

        <td>
          string
        </td>

        <td>
          The currency.<br />Must use capitalized, three-letter currency codes that comply with ISO 4217.<br />e.g. KRW, USD
        </td>

        <td>
          **Required**
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          campaign
        </td>

        <td>
          string
        </td>

        <td>
          The campaign name
        </td>

        <td>
          **Required**
        </td>
      </tr>

      <tr>
        <td>
          Metric
        </td>

        <td>
          impressions
        </td>

        <td>
          int
        </td>

        <td>
          The impression count.<br />Note that comma (,) cannot be used as a delimiter for numeric data.
        </td>

        <td>
          **Required**
        </td>
      </tr>

      <tr>
        <td>
          Metric
        </td>

        <td>
          clicks
        </td>

        <td>
          int
        </td>

        <td>
          The click count.<br />Note that comma (,) cannot be used as a delimiter for numeric data.
        </td>

        <td>
          **Required**
        </td>
      </tr>

      <tr>
        <td>
          Metric
        </td>

        <td>
          cost
        </td>

        <td>
          float
        </td>

        <td>
          The ad spend.<br />Note that comma (,) cannot be used as a delimiter for numeric data.
        </td>

        <td>
          **Required**
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          campaign\_id
        </td>

        <td>
          string
        </td>

        <td>
          The ID of campaign.
        </td>

        <td>
          Optional
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          ad\_group
        </td>

        <td>
          string
        </td>

        <td>
          The ad group.
        </td>

        <td>
          Optional
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          ad\_group\_id
        </td>

        <td>
          string
        </td>

        <td>
          The ID of ad group.
        </td>

        <td>
          Optional
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          ad\_creative
        </td>

        <td>
          string
        </td>

        <td>
          The ad creative.
        </td>

        <td>
          Optional
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          ad\_creative\_id
        </td>

        <td>
          string
        </td>

        <td>
          The ID of ad creative.
        </td>

        <td>
          Optional
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          term
        </td>

        <td>
          string
        </td>

        <td>
          The term.
        </td>

        <td>
          Optional
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          term\_id
        </td>

        <td>
          string
        </td>

        <td>
          The ID of term.
        </td>

        <td>
          Optional
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          ad\_account
        </td>

        <td>
          string
        </td>

        <td>
          The ad account.
        </td>

        <td>
          Optional
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          ad\_account\_id
        </td>

        <td>
          string
        </td>

        <td>
          The ID of ad account.
        </td>

        <td>
          Optional
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          sub\_publisher
        </td>

        <td>
          string
        </td>

        <td>
          The sub publisher
        </td>

        <td>
          Optional
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          sub\_sub\_publisher\_1
        </td>

        <td>
          string
        </td>

        <td>
          The sub-sub publisher 1
        </td>

        <td>
          Optional
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          sub\_sub\_publisher\_2
        </td>

        <td>
          string
        </td>

        <td>
          The sub-sub publisher 2
        </td>

        <td>
          Optional
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          sub\_sub\_publisher\_3
        </td>

        <td>
          string
        </td>

        <td>
          The sub-sub publisher 3
        </td>

        <td>
          Optional
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          country
        </td>

        <td>
          string
        </td>

        <td>
          2-digit lowercase country value.<br />e.g. kr, us, gb, fr
        </td>

        <td>
          Optional
        </td>
      </tr>

      <tr>
        <td>
          Group by
        </td>

        <td>
          os\_name
        </td>

        <td>
          string
        </td>

        <td>
          The OS Name<br />Be aware that data in columns with a type defined as 'string' is case-sensitive.<br />e.g. Android, iOS
        </td>

        <td>
          Optional
        </td>
      </tr>
    </tbody>
  </table>
</div>

<h4 id="sample-csv-file">
  Sample CSV File
</h4>

* [Example CSV File](https://udl-static.s3.ap-northeast-1.amazonaws.com/docs/airbridge_cost_upload_sample.csv)

<h4 id="a-case-sensitivity">
  🚧 Case Sensitivity
</h4>

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.

<h3 id="overwrite-correct-previously-ingested-ad-spend">
  Overwrite (correct) Previously Ingested Ad Spend
</h3>

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 |

<h3 id="delete-previously-ingested-ad-spend">
  Delete Previously Ingested Ad Spend
</h3>

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.

<h3 id="note">
  Note
</h3>

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

<Card title="Try API Request" icon="rectangle-api" horizontal href="https://www.postman.com/airbridge-engineering/workspace/airbridge-api/request/22395869-e91f64df-f07c-45df-af43-999698f4c4dc" />

```text POST theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
https://api.airbridge.io/self-serve-data/v1/ad-spend/requests
```

<h2 id="upload-ad-spend-data-request">
  Request
</h2>

***

<h3 id="upload-ad-spend-data-headers">
  Headers
</h3>

<ParamField header="Accept-Language" type="string">
  You can specify the language to use for API requests and responses. It follows the ISO-639-1 format.
</ParamField>

<ParamField header="Content-Type" type="string">
  Represents the media type of the resource. Defaults to `application/json`.
</ParamField>

<ParamField header="Authorization" type="string">
  The key value to use for API requests. Instructions for getting API keys are in "[how to generate API Keys](/en/references/introduction#authorization)".
</ParamField>

<RequestExample>
  ```shellscript Request theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  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}'
  ```
</RequestExample>

<h2 id="upload-ad-spend-data-response">
  Response
</h2>

***

### 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                  |

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {
    "reason": null,
    "status": "uploaded",
    "createdAt": "2023-01-01T09:00:00",
    "requestId": "08844672-62d8-4da8-9d48-e14961651e0c",
    "updatedAt": "2023-01-01T09:00:00",
    "prevStatus": null
  }
  ```
</ResponseExample>