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

# Create Tracking Link

An Airbridge tracking link is an all-in-one link that serves as both a linking tool to redirect users and a tracking tool for attribution.

When they are clicked on, tracking links enable users to reach their desired destination in the app regardless of the platform, channel, or device operating system. It also helps to analyze and attribute the source of user conversions such as link click, post-click install, and post-install purchase.

<Info>
  **Tracking link API token**

  It is advised to use the "Tracking link API token" when creating tracking links from the client server.
</Info>

Request to create Tracking Link.

rate limit : 50 tracking link per second

```text POST theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
https://api.airbridge.io/v1/tracking-links
```

## Request

***

### Headers

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

### Body Params

<ParamField body="channel" type="string" required>
  Channel name of the touchpoint and conversion.

  Upon creation, tracking links are separated into "integrated" channels and "custom" channels.

  "Integrated" channels are medias with postback integration, and have [predefined channel names](https://abit.ly/integrated-channels). All other channel names are considered "Custom" channels.
</ParamField>

<ParamField body="campaignParams" type="object">
  Configure campaign parameter for tracking link.

  <Expandable title="child attributes">
    <ParamField body="campaignParams.campaign" type="string">
      The campaign credited with the winning touchpoint or conversion.
    </ParamField>

    <ParamField body="campaignParams.ad_group" type="string">
      The ad group credited with the winning touchpoint or conversion.
    </ParamField>

    <ParamField body="campaignParams.ad_creative" type="string">
      The ad creative credited with the winning touchpoint or conversion.
    </ParamField>

    <ParamField body="campaignParams.content" type="string">
      The content credited with the winning touchpoint or conversion.
    </ParamField>

    <ParamField body="campaignParams.term" type="string">
      The search term credited with the winning touchpoint or conversion.
    </ParamField>

    <ParamField body="campaignParams.sub_id" type="string">
      The sub publisher that generated the touchpoint.

      Sub media values are usually provided by predefined "integrated" channels.
    </ParamField>

    <ParamField body="campaignParams.sub_id_1" type="string">
      The 1st level sub-sub publisher that generated the touchpoint.

      Sub media values are usually provided by predefined "integrated" channels.
    </ParamField>

    <ParamField body="campaignParams.sub_id_2" type="string">
      The 2nd level sub-sub publisher that generated the touchpoint.

      Sub media values are usually provided by predefined "integrated" channels.
    </ParamField>

    <ParamField body="campaignParams.sub_id_3" type="string">
      The 3rd level sub-sub publisher that generated the touchpoint.

      Sub media values are usually provided by predefined "integrated" channels.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="isReengagement" type="enum">
  Configure the Re-engagement parameter. The Re-engagement parameter has three options: OFF, ON-TRUE, and ON-FALSE.

  | Value | Description |
  | - | - |
  | `OFF` | OFF is the default setting. The touchpoint can be attributed to both install events and post-install events (in-app events). |
  | `ON-TRUE` | ON-TRUE is used for re-engagement campaigns for installed users. The touchpoint generated by the tracking link is attributed only to the deeplink open and the following in-app events, not to the install event. |
  | `ON-FALSE` | ON-FALSE is used for user acquisition campaigns targeting uninstalled users. The touchpoint generated by the tracking link is attributed only to the install event and the following in-app events, not to the 'deeplink open' event. |
</ParamField>

<ParamField body="deeplinkUrl" type="string">
  Configure the Deeplink URL for redirect.

  If `deeplinkUrl` is missing or null, the deeplink setting is not configured.

  Example format: **`URLScheme://path?key=value`**

  If an invalid deeplinkUrl is used, the deep link may not work properly and **could result in unexpected behavior or issues.**
</ParamField>

<ParamField body="deeplinkOption" type="object">
  <Expandable title="child attributes">
    <ParamField body="deeplinkOption.showAlertForInitialDeeplinkingIssue" type="boolean">
      Stopover Page

      true: activate

      false: deactivate
    </ParamField>

    <ParamField body="deeplinkOption.useCustomAirpage" type="boolean">
      Whether to use the custom Airpage.

      true: Use the custom Airpage for the user's browser language, or the default custom Airpage if there is no page for that language.

      false: Do not use the custom Airpage.

      If not passed, the app's default custom Airpage setting is applied.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="fallbackPaths" type="object">
  Configure the redirect path by platform when deep linking doesn't redirect as intended.

  Only https URLs are supported when you enter a URL directly.

  <Expandable title="child attributes">
    <ParamField body="fallbackPaths.android" type="enum">
      Redirect android user to `google-play` or an https URL

      | Value | Description |
      | - | - |
      | `google-play` | Landing in the Google Play Store. |
      | `{https_url}` | Landing in the `https` URL. |
    </ParamField>

    <ParamField body="fallbackPaths.ios" type="enum">
      Redirect iOS user to `itunes-appstore` or an https URL

      | Value | Description |
      | - | - |
      | `itunes-appstore` | Landing in the App Store. |
      | `{https_url}` | Landing in the `https` URL. |
    </ParamField>

    <ParamField body="fallbackPaths.desktop" type="enum">
      Redirect desktop user to `google-play`, `itunes-appstore` or an https URL

      | Value | Description |
      | - | - |
      | `google-play` | Landing in the Google Play Store. |
      | `itunes-appstore` | Landing in the App Store. |
      | `{https_url}` | Landing in the `https` URL. |
    </ParamField>

    <ParamField body="fallbackPaths.option" type="object">
      <Expandable title="child attributes">
        <ParamField body="fallbackPaths.option.iosCustomProductPageId" type="string">
          The ppid for the Custom Product Page in the Apple App Store.

          Enable the custom product page to be shown when landing in the App Store.
        </ParamField>

        <ParamField body="fallbackPaths.option.googlePlayCustomStoreListing" type="string">
          The Custom Store Listing listing value for the Google Play Store.

          Enables the display of your custom store listing when landing on the Google Play Store.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="ogTag" type="object">
  Configure the Open Graph for the tracking link that will be shown when the link is shared or posted.

  <Expandable title="child attributes">
    <ParamField body="ogTag.title" type="string">
      The Open Graph of url specified in fallbackPath.
    </ParamField>

    <ParamField body="ogTag.description" type="string">
      `og:title` for tracking link
    </ParamField>

    <ParamField body="ogTag.imageUrl" type="string">
      `og:description` for tracking link
    </ParamField>

    <ParamField body="ogTag.websiteCrawl" type="enum">
      `og:image` for tracking link

      | Value | Description |
      | - | - |
      | `desktop` | When the tracking link is shared, the social media platform directly crawls the Open Graph of the desktop URL specified in fallbackPaths and uses it for the social share preview. Dynamic URLs are also supported, and any change to the Open Graph is reflected automatically from the next time the link is shared. The values set for title, description, and imageUrl will be ignored. |
    </ParamField>

    <ParamField body="ogTag.useDefault" type="boolean">
      Enable the Social Share preview default values set in the Airbridge dashboard.

      Note. Other parameter values in the og tag will be ignored.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="customShortId" type="string">
  Configure the Short Link ID of tracking links depending on your campaign or contents. If not passed, a random Short Link ID will be generate, and can not be changed once generated.

  The Short Link ID of a tracking link cannot be reused even if the tracking link has been deprecated.

  The Short Link ID is only available for tracking links created with a custom domain.

  * If a [primary domain](/en/guides/custom-domain#set-the-primary-domain) is set: The tracking link is created with the primary domain even if `domain` is not passed.
  * If no primary domain is set: Pass the custom domain to use in `domain` as well, or a `400` error is returned.

  **Allowed Characters & Restrictions**

  * Lowercase English letters: `a–z`
  * Korean characters (Hangul): `가–힣`
  * Numbers: `0–9`
  * Special characters: hyphen (`-`), underscore (`_`)
  * Maximum length: 45 characters
</ParamField>

<ParamField body="domain" type="string">
  The custom domain to create the custom channel tracking link with.

  Enter a custom domain that has been added to the app and verified, without the scheme and path, such as `link.example.com`.

  If not passed, the [primary domain](/en/guides/custom-domain#set-the-primary-domain) is used, and if no primary domain is set, `abr.ge` is used.

  A `400` error is returned if the domain has not been added to the app or has not been verified.
</ParamField>

<ParamField body="useReservedDomain" type="boolean">
  If set to `true`, the tracking link is created with `abr.ge` even if a primary domain is set.

  The default value is `false`.

  Cannot be used with `customShortId`.
</ParamField>

<RequestExample>
  ```shellscript Request theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  curl -X POST 'https://api.airbridge.io/v1/tracking-links' \
    -H 'Accept-Language: ko' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}' \
    -d '{
    "channel": "my-channel",
    "campaignParams": {
      "campaign": "2022_FW_Sale_Festival",
      "ad_group": "UA",
      "ad_creative": "Coat_840x600"
    },
    "isReengagement": "ON-TRUE",
    "deeplinkOption": {
      "showAlertForInitialDeeplinkingIssue": true
    },
    "fallbackPaths": {
      "option": {
        "iosCustomProductPageId": "5ae82ffe-1f08-428d-b352-ac1c3a22aa1e",
        "googlePlayCustomStoreListing": "custom-store-listing"
      }
    },
    "ogTag": {
      "title": "30% Off Winter Apparel for 3 Days Only",
      "description": "Get great deals on apparel to keep you warm this winter",
      "imageUrl": "https://static.airbridge.io/images/2021_airbridge_og_tag.png"
    }
  }'
  ```
</RequestExample>

## Response

***

### 200

Tracking Link was successfully created.

| Parameter | Description |
| - | - |
| trackingLink.id | The ID of Tracking Link. |
| trackingLink.channelType | The channel type of Tracking Link. |
| trackingLink.link.impression | The Tracking Link generate impression event |
| trackingLink.link.click | The Tracking Link generate click event. |
| trackingLink.link.serverToServerClick | The Tracking Link generate S2S event. |
| trackingLink.shortId | The short ID of Tracking Link. |
| trackingLink.shortUrl | The short link of Tracking Link. |
| trackingLink.trackingTemplateId | The template ID of Tracking Link. |

### 400

The tracking link cannot be created with the requested values.

Check the cause in `detail` of the response.

| detail | Cause |
| - | - |
| `Custom Short ID is only available with a custom domain` | `customShortId` was passed, but the tracking link is created with `abr.ge`. If no primary domain is set, pass `domain` as well. |
| `Domain must not include scheme`<br />`Domain must not include path` | The value passed in `domain` includes a scheme such as `https://` or a path. |
| `Custom domain not found for app: {domain}` | The domain passed in `domain` has not been added to the app. |
| `Custom domain is not certificated: {domain}` | The domain passed in `domain` has not been verified. |

### 404

There is no such app. Please check the request token again.

### 422

There are some invalid values in request.

### 429

rate limit exceeded

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {
    "data": {
      "trackingLink": {
        "id": 10000,
        "link": {
          "click": "https://abr.ge/@airbridge/my-channel?...",
          "impression": "https://abr.ge/@airbridge/my-channel?...",
          "serverToServerClick": null
        },
        "shortId": "6nwx4w",
        "shortUrl": "https://abr.ge/6nwx4w",
        "channelType": "custom",
        "trackingTemplateId": "706f9839a7b50d87ab917dbb1b9fa7f3"
      }
    }
  }
  ```

  ```json 400 theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {
    "type": "about:blank",
    "title": "Bad Request",
    "detail": "Custom Short ID is only available with a custom domain",
    "status": 400,
    "traceId": "1-000000-000000000000000"
  }
  ```

  ```json 404 theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {
    "type": "about:blank",
    "title": "Not Found",
    "detail": "There is no such app.",
    "status": 404,
    "traceId": "1-000000-000000000000000"
  }
  ```

  ```json 422 theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {
    "detail": [
      {
        "loc": [
          "string"
        ],
        "msg": "string",
        "type": "string"
      }
    ]
  }
  ```

  ```json 429 theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {
    "type": "Rate limit exceeded",
    "title": null,
    "status": 429,
    "traceId": "1-6768fb4d-0833f0c4639017b1613ac244"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.