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

# Create Link

> Create a new dynamic link with simplified parameters for easy integration

## Request

<ParamField header="X-API-KEY" type="string" required>
  Your API key: `b2co_your_api_key`
</ParamField>

<ParamField body="code" type="string">
  Custom short code for the link. If not provided, a random code will be
  generated. Must be unique within your project and contain only alphanumeric
  characters, hyphens, and underscores (3-50 characters).
</ParamField>

<Info>
  **Link Codes are Unique**: Each link code must be unique within your project.
  Use the [Check Code Availability](/api-reference/links/check-code) endpoint to
  verify if a code is available before creating a link.
</Info>

<ParamField body="name" type="string">
  Optional display name for the link to help with organization and
  identification.
</ParamField>

<ParamField body="payload" type="object" required>
  Link configuration object containing destination URL and platform-specific
  settings.
</ParamField>

<ParamField body="payload.link" type="string" required>
  The destination URL where users will be redirected when they click the dynamic
  link.
</ParamField>

<ParamField body="payload.iosAppId" type="string">
  ID of a saved iOS mobile app to use for this link. When provided, the link will use the saved app's configuration instead of manual iOS settings.
</ParamField>

<ParamField body="payload.androidAppId" type="string">
  ID of a saved Android mobile app to use for this link. When provided, the link will use the saved app's configuration instead of manual Android settings.
</ParamField>

<ParamField body="payload.android" type="object">
  Android-specific configuration for deep linking and app store fallbacks.
</ParamField>

<ParamField body="payload.android.package" type="string">
  Android app package name (e.g., com.yourapp.android).
</ParamField>

<ParamField body="payload.android.store_fallback" type="string">
  Play Store URL to redirect Android users without the app.
</ParamField>

<ParamField body="payload.android.min_version" type="string">
  Minimum app version required to handle the deep link.
</ParamField>

<ParamField body="payload.android.saveApp" type="boolean">
  Whether to save this Android configuration as a reusable mobile app.
</ParamField>

<ParamField body="payload.android.appName" type="string">
  Name for the saved mobile app (required if saveApp is true).
</ParamField>

<ParamField body="payload.ios" type="object">
  iOS-specific configuration for deep linking and App Store fallbacks.
</ParamField>

<ParamField body="payload.ios.bundleId" type="string">
  iOS app bundle identifier (e.g., com.yourapp.ios).
</ParamField>

<ParamField body="payload.ios.app_store_fallback" type="string">
  App Store URL to redirect iOS users without the app.
</ParamField>

<ParamField body="payload.ios.app_store_id" type="string">
  App Store ID for the iOS app.
</ParamField>

<ParamField body="payload.ios.min_version" type="string">
  Minimum app version required to handle the deep link.
</ParamField>

<ParamField body="payload.ios.saveApp" type="boolean">
  Whether to save this iOS configuration as a reusable mobile app.
</ParamField>

<ParamField body="payload.ios.appName" type="string">
  Name for the saved mobile app (required if saveApp is true).
</ParamField>

<ParamField body="payload.social" type="object">
  Social media preview configuration for rich link sharing.
</ParamField>

<ParamField body="payload.social.title" type="string">
  Title displayed in social media previews.
</ParamField>

<ParamField body="payload.social.description" type="string">
  Description displayed in social media previews.
</ParamField>

<ParamField body="payload.social.image" type="string">
  Image URL displayed in social media previews.
</ParamField>

<ParamField body="payload.campaign" type="object">
  UTM campaign parameters for analytics tracking.
</ParamField>

<ParamField body="payload.campaign.utm_source" type="string">
  Campaign source parameter.
</ParamField>

<ParamField body="payload.campaign.utm_medium" type="string">
  Campaign medium parameter.
</ParamField>

<ParamField body="payload.campaign.utm_campaign" type="string">
  Campaign name parameter.
</ParamField>

<ParamField body="payload.campaign.utm_term" type="string">
  Campaign term parameter (for paid search keywords).
</ParamField>

<ParamField body="payload.campaign.utm_content" type="string">
  Campaign content parameter (for A/B testing and content-targeted ads).
</ParamField>

<ParamField body="payload.desktop_fallback" type="string">
  Fallback URL for desktop users.
</ParamField>

<ParamField body="expiresAt" type="string">
  Optional expiration date in ISO 8601 format. Link will become inactive after
  this date.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  The created link object
</ResponseField>

<ResponseField name="data.id" type="string">
  Unique identifier for the link
</ResponseField>

<ResponseField name="data.code" type="string">
  The unique short code for the link
</ResponseField>

<ResponseField name="data.shortUrl" type="string">
  The complete short URL that can be shared
</ResponseField>

<ResponseField name="data.originalUrl" type="string">
  The original destination URL
</ResponseField>

<ResponseField name="data.name" type="string">
  Display name of the link
</ResponseField>

<ResponseField name="data.status" type="string">
  Current status of the link (ACTIVE, PAUSED, etc.)
</ResponseField>

<ResponseField name="data.qrCode" type="string">
  QR code URL for the link
</ResponseField>

<ResponseField name="data.createdAt" type="string">
  ISO 8601 timestamp when the link was created
</ResponseField>

<ResponseField name="data.expiresAt" type="string">
  ISO 8601 timestamp when the link expires (if set)
</ResponseField>

<ResponseField name="data.clickCount" type="number">
  Number of times the link has been clicked
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.bit2connect.com/1.0/links" \
    -H "X-API-KEY: b2co_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "code": "summer-sale",
      "name": "Summer Sale Campaign",
      "payload": {
        "link": "https://yourapp.com/products/summer-sale",
        "android": {
          "package": "com.yourapp.android",
          "store_fallback": "https://play.google.com/store/apps/details?id=com.yourapp.android"
        },
        "ios": {
          "bundleId": "com.yourapp.ios",
          "app_store_fallback": "https://apps.apple.com/app/yourapp/id123456789"
        },
        "social": {
          "title": "Summer Sale - Up to 50% Off!",
          "description": "Don'\''t miss our biggest sale of the year. Shop now!",
          "image": "https://yourapp.com/images/summer-sale.jpg"
        },
        "campaign": {
          "utm_source": "api",
          "utm_medium": "dynamic_link",
          "utm_campaign": "summer_sale_2024"
        }
      },
      "expiresAt": "2024-12-31T23:59:59Z"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.bit2connect.com/1.0/links", {
    method: "POST",
    headers: {
      "X-API-KEY": "b2co_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      code: "summer-sale",
      name: "Summer Sale Campaign",
      payload: {
        link: "https://yourapp.com/products/summer-sale",
        android: {
          package: "com.yourapp.android",
          store_fallback:
            "https://play.google.com/store/apps/details?id=com.yourapp.android",
        },
        ios: {
          bundleId: "com.yourapp.ios",
          app_store_fallback: "https://apps.apple.com/app/yourapp/id123456789",
        },
        social: {
          title: "Summer Sale - Up to 50% Off!",
          description: "Don't miss our biggest sale of the year. Shop now!",
          image: "https://yourapp.com/images/summer-sale.jpg",
        },
        campaign: {
          utm_source: "api",
          utm_medium: "dynamic_link",
          utm_campaign: "summer_sale_2024",
        },
      },
      expiresAt: "2024-12-31T23:59:59Z",
    }),
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.bit2connect.com/1.0/links"
  headers = {
      "X-API-KEY": "b2co_your_api_key",
      "Content-Type": "application/json"
  }

  payload = {
      "code": "summer-sale",
      "name": "Summer Sale Campaign",
      "payload": {
          "link": "https://yourapp.com/products/summer-sale",
          "android": {
              "package": "com.yourapp.android",
              "store_fallback": "https://play.google.com/store/apps/details?id=com.yourapp.android"
          },
          "ios": {
              "bundleId": "com.yourapp.ios",
              "app_store_fallback": "https://apps.apple.com/app/yourapp/id123456789"
          },
          "social": {
              "title": "Summer Sale - Up to 50% Off!",
              "description": "Don't miss our biggest sale of the year. Shop now!",
              "image": "https://yourapp.com/images/summer-sale.jpg"
          },
          "campaign": {
              "utm_source": "api",
              "utm_medium": "dynamic_link",
              "utm_campaign": "summer_sale_2024"
          }
      },
      "expiresAt": "2024-12-31T23:59:59Z"
  }

  response = requests.post(url, json=payload, headers=headers)
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "success": true,
    "data": {
      "id": "clp123abc456",
      "code": "summer-sale",
      "shortUrl": "https://b2co.link/summer-sale",
      "originalUrl": "https://yourapp.com/products/summer-sale",
      "name": "Summer Sale Campaign",
      "status": "ACTIVE",
      "qrCode": "https://b2co.link/summer-sale/qr",
      "createdAt": "2024-01-15T10:30:00Z",
      "expiresAt": "2024-12-31T23:59:59Z",
      "clickCount": 0
    }
  }
  ```

  ```json Error Response theme={null}
  {
    "success": false,
    "error": {
      "code": "CODE_ALREADY_EXISTS",
      "message": "The specified code is already in use"
    }
  }
  ```
</ResponseExample>

## Error Codes

<ResponseField name="VALIDATION_ERROR" type="string">
  Invalid request payload or parameters
</ResponseField>

<ResponseField name="CODE_ALREADY_EXISTS" type="string">
  The specified code is already in use
</ResponseField>

<ResponseField name="INVALID_API_KEY" type="string">
  API key is missing or invalid
</ResponseField>

<ResponseField name="RATE_LIMIT_EXCEEDED" type="string">
  Too many requests, please try again later
</ResponseField>

<ResponseField name="SUBSCRIPTION_REQUIRED" type="string">
  Active subscription required to create links
</ResponseField>