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

# Create Link

> Create a new deeplink with optional advanced features

Create a new deeplink with custom codes, domains, password protection, expiration dates, and tracking features.

**Request:**

```bash cURL theme={null}
curl -X POST 'https://api.taap.it/v1/links' \
  -H 'Authorization: Bearer taapit_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "original_url": "https://example.com/very-long-url-that-needs-shortening"
  }'
```

**Response:**

```json theme={null}
{
  "id": "link_987654321",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "project_id": "project_123456789",
  "domain_id": "domain_987654321",
  "pixel_id": "pixel_456789123",
  "original_url": "https://example.com/very-long-url-that-needs-shortening",
  "name": "My Marketing Link",
  "description": "Link for summer campaign",
  "code": "summer2024",
  "app": "MyApp",
  "app_logo": "https://example.com/logo.png",
  "android_link": "myapp://open?url=https://example.com",
  "ios_link": "myapp://open?url=https://example.com",
  "windows_link": "ms-windows-store://pdp/?productid=9NBLGGH123456",
  "macos_link": "macappstore://itunes.apple.com/app/myapp/id123456789",
  "whatsapp_message": "Check out this amazing link!",
  "metadata": {
    "title": "Amazing Product",
    "description": "Check out our new product",
    "favicon": "https://example.com/favicon.ico",
    "social_image": "https://example.com/social-image.jpg"
  },
  "qr_code_options": {
    "size": 200,
    "color": "#000000",
    "background_color": "#ffffff",
    "logo": "https://example.com/logo.png",
    "logo_size": 50,
    "error_correction_level": "M"
  },
  "utm_name": "summer_campaign",
  "utm_source": "email",
  "utm_medium": "newsletter",
  "utm_campaign": "summer2024",
  "utm_term": "marketing",
  "utm_content": "cta_button",
  "utm_template_id": "template_123",
  "referrer": "https://example.com",
  "password": "secure123",
  "password_description": "Enter password to access link",
  "excluded_countries": [
    {
      "code": "US",
      "label": "United States",
      "phone": "+1",
      "suggested": true,
      "lang": "en",
      "continent": "North America"
    }
  ],
  "has_public_stat": true,
  "enable_conversion_tracking": true,
  "is_archived": false,
  "expiration_date": "2024-12-31T23:59:59Z",
  "expiration_click_count": 1000,
  "clicks": 0
}
```

## Authorization

<ParamField header="Authorization" type="string" required>
  Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`
</ParamField>

## Request Parameters

<ParamField body="original_url" type="string" required>
  The URL to be shortened. Supports http, https, mailto, tel, sms, whatsapp, tg, skype schemes.
</ParamField>

<ParamField body="enable_conversion_tracking" type="boolean">
  Whether to enable conversion tracking on this link. When omitted, the default depends on your plan's conversion tracking feature.
</ParamField>

## Response Fields

### Core Fields

<ResponseField name="id" type="string" required>
  Unique identifier for the created link
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp when the link was created
</ResponseField>

<ResponseField name="updated_at" type="string" required>
  ISO 8601 timestamp when the link was last updated
</ResponseField>

<ResponseField name="project_id" type="string">
  ID of the associated project
</ResponseField>

<ResponseField name="domain_id" type="string">
  ID of the custom domain used
</ResponseField>

<ResponseField name="pixel_id" type="string">
  ID of the associated tracking pixel
</ResponseField>

### Link Content

<ResponseField name="original_url" type="string" required>
  The original URL that was shortened
</ResponseField>

<ResponseField name="name" type="string">
  Name of the link
</ResponseField>

<ResponseField name="description" type="string">
  Description of the link
</ResponseField>

<ResponseField name="code" type="string" required>
  The short code used in the URL
</ResponseField>

### Deep Linking

<ResponseField name="app" type="string">
  Name of the mobile app for deep linking
</ResponseField>

<ResponseField name="app_logo" type="string">
  URL to the app logo image
</ResponseField>

<ResponseField name="android_link" type="string">
  Android deep link URL
</ResponseField>

<ResponseField name="ios_link" type="string">
  iOS deep link URL
</ResponseField>

<ResponseField name="windows_link" type="string">
  Windows deep link URL
</ResponseField>

<ResponseField name="macos_link" type="string">
  macOS deep link URL
</ResponseField>

<ResponseField name="whatsapp_message" type="string">
  Pre-filled message for WhatsApp sharing
</ResponseField>

### Metadata & QR Code

<ResponseField name="metadata" type="object">
  Link metadata for website previews

  <Expandable title="Metadata properties">
    <ResponseField name="title" type="string">
      Page title for link previews
    </ResponseField>

    <ResponseField name="description" type="string">
      Page description for link previews
    </ResponseField>

    <ResponseField name="favicon" type="string">
      URL to favicon image
    </ResponseField>

    <ResponseField name="social_image" type="string">
      URL to social media preview image
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="qr_code_options" type="object">
  QR code generation options

  <Expandable title="QR Code options">
    <ResponseField name="size" type="integer">
      QR code size in pixels
    </ResponseField>

    <ResponseField name="color" type="string">
      QR code color (hex format)
    </ResponseField>

    <ResponseField name="background_color" type="string">
      QR code background color (hex format)
    </ResponseField>

    <ResponseField name="logo" type="string">
      URL to logo image embedded in QR code
    </ResponseField>

    <ResponseField name="logo_size" type="integer">
      Logo size in pixels
    </ResponseField>

    <ResponseField name="error_correction_level" type="string">
      Error correction level (L, M, Q, H)
    </ResponseField>
  </Expandable>
</ResponseField>

### UTM Parameters

<ResponseField name="utm_name" type="string">
  UTM campaign name
</ResponseField>

<ResponseField name="utm_source" type="string">
  UTM source
</ResponseField>

<ResponseField name="utm_medium" type="string">
  UTM medium
</ResponseField>

<ResponseField name="utm_campaign" type="string">
  UTM campaign identifier
</ResponseField>

<ResponseField name="utm_term" type="string">
  UTM term (keywords)
</ResponseField>

<ResponseField name="utm_content" type="string">
  UTM content
</ResponseField>

<ResponseField name="utm_template_id" type="string">
  UTM template identifier
</ResponseField>

<ResponseField name="referrer" type="string">
  Referrer URL
</ResponseField>

### Security & Access

<ResponseField name="password" type="string">
  Password to protect the link
</ResponseField>

<ResponseField name="password_description" type="string">
  Description shown when password is required
</ResponseField>

<ResponseField name="excluded_countries" type="array">
  Array of countries excluded from accessing the link

  <Expandable title="Excluded country properties">
    <ResponseField name="code" type="string">
      Country code (ISO 3166-1 alpha-2)
    </ResponseField>

    <ResponseField name="label" type="string">
      Country name
    </ResponseField>

    <ResponseField name="phone" type="string">
      Country phone code
    </ResponseField>

    <ResponseField name="suggested" type="boolean">
      Whether this country is suggested for exclusion
    </ResponseField>

    <ResponseField name="lang" type="string">
      Primary language code
    </ResponseField>

    <ResponseField name="continent" type="string">
      Continent name
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_public_stat" type="boolean">
  Whether link statistics are publicly accessible
</ResponseField>

### Conversion Tracking

<ResponseField name="enable_conversion_tracking" type="boolean">
  Whether conversion tracking is enabled on this link
</ResponseField>

### Status Flags

<ResponseField name="is_archived" type="boolean">
  Whether the link is archived
</ResponseField>

### Expiration

<ResponseField name="expiration_date" type="string">
  ISO 8601 datetime when link expires
</ResponseField>

<ResponseField name="expiration_click_count" type="integer">
  Maximum number of clicks before link expires
</ResponseField>

### Analytics

<ResponseField name="clicks" type="integer">
  Total number of clicks
</ResponseField>

## Error Responses

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "detail": "Invalid URL format"
  }
  ```

  ```json 409 Conflict theme={null}
  {
    "detail": "Custom code already exists"
  }
  ```
</ResponseExample>