# Create Domain
Source: https://docs.taap.it/api-reference/domains/create

POST https://api.taap.it/v1/domains
Create a new custom domain for your workspace

Add a custom domain for branded deeplinks.

**Request:**

```bash cURL theme={null}
curl -X POST 'https://api.taap.it/v1/domains' \
  -H 'Authorization: Bearer taapit_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "links.yourcompany.com",
    "description": "Custom domain for marketing links"
  }'
```

**Response:**

```json theme={null}
{
  "id": "domain_987654321",
  "created_at": "2024-01-15T10:30:00Z",
  "domain": "links.yourcompany.com"
}
```

## Authorization

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

## Request Parameters

<ParamField type="string">
  The custom domain name (e.g., "links.yourcompany.com")
</ParamField>

<ParamField type="string">
  Optional description for the domain
</ParamField>

## Response Fields

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

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

<ResponseField name="domain" type="string">
  The custom domain name
</ResponseField>


# Delete Domain
Source: https://docs.taap.it/api-reference/domains/delete

DELETE https://api.taap.it/v1/domains/{domain_id}
Remove a domain from your account

**Request:**

```bash cURL theme={null}
curl -X DELETE 'https://api.taap.it/v1/domains/domain_987654321' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "message": "Domain deleted successfully"
}
```

## Authorization

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

## Path Parameters

<ParamField type="string">
  Unique identifier for the domain to delete
</ParamField>


# Retrieve Domain
Source: https://docs.taap.it/api-reference/domains/get

GET https://api.taap.it/v1/domains/{domain_id}
Retrieve details for a specific domain

**Request:**

```bash cURL theme={null}
curl -X GET 'https://api.taap.it/v1/domains/domain_987654321' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "id": "domain_987654321",
  "domain": "links.yourcompany.com",
  "description": "Custom domain for marketing links",
  "is_verified": true,
  "created_at": "2024-01-15T10:30:00Z"
}
```

## Authorization

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

## Path Parameters

<ParamField type="string">
  Unique identifier for the domain
</ParamField>

## Response Fields

<ResponseField name="id" type="string">
  Unique identifier for the domain
</ResponseField>

<ResponseField name="domain" type="string">
  The custom domain name
</ResponseField>

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

<ResponseField name="is_verified" type="boolean">
  Whether the domain is verified
</ResponseField>

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


# List Domains
Source: https://docs.taap.it/api-reference/domains/list

GET https://api.taap.it/v1/domains
Retrieve a paginated list of domains

**Request:**

```bash cURL theme={null}
curl -X GET 'https://api.taap.it/v1/domains?sort_by=created_at&sort_order=desc&page=1&page_size=20&cursor=eyJpZCI6ImRvbWFpbl85ODc2NTQzMjEifQ==' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "items": [
    {
      "id": "domain_987654321",
      "domain": "links.yourcompany.com",
      "is_verified": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "page": 1,
  "page_size": 10,
  "has_next": false
}
```

## Authorization

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

## Query Parameters

### Pagination Parameters

<ParamField type="string">
  Cursor for pagination (use for efficient pagination)
</ParamField>

<ParamField type="integer">
  Page number (starts from 1)
</ParamField>

<ParamField type="integer">
  Number of items per page (maximum 100)
</ParamField>

### Sorting Parameters

<ParamField type="string">
  Field to sort by (e.g., "created\_at", "updated\_at", "domain")
</ParamField>

<ParamField type="string">
  Sort order: "asc" for ascending or "desc" for descending
</ParamField>


# Track Lead
Source: https://docs.taap.it/api-reference/events/lead

POST /api/events/lead
Create a lead conversion event

## Endpoint

```
POST https://track.taap.it/api/events/lead
```

## Authentication

<Tabs>
  <Tab title="Server-side (Recommended)">
    Use your secret API key:

    ```bash theme={null}
    Authorization: Bearer taapit_sk_xxxxxxxxxxxx
    ```
  </Tab>

  <Tab title="Client-side">
    Use your publishable key:

    ```bash theme={null}
    X-Publishable-Key: taapit_pk_xxxxxxxxxxxx
    ```
  </Tab>
</Tabs>

## Request Body

| Field                  | Type   | Required | Description                                   |
| ---------------------- | ------ | -------- | --------------------------------------------- |
| `trackingId`           | string | ✓        | The `ta_tid` from the cookie or URL parameter |
| `customer`             | object | ✓        | Customer information                          |
| `customer.externalId`  | string | ✓        | Your internal user/customer ID                |
| `customer.email`       | string |          | Customer's email address                      |
| `customer.firstname`   | string |          | Customer's first name                         |
| `customer.lastname`    | string |          | Customer's last name                          |
| `customer.phoneNumber` | string |          | Customer's phone number                       |
| `customer.avatarUrl`   | string |          | URL to customer's avatar image                |
| `metadata`             | object |          | Additional custom data (key-value pairs)      |

## Examples

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://track.taap.it/api/events/lead \
      -H "Authorization: Bearer taapit_sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "trackingId": "rLnWe1uz9t282v7g",
        "customer": {
          "externalId": "user_123",
          "email": "john@example.com",
          "firstname": "John",
          "lastname": "Doe"
        },
        "metadata": {
          "source": "signup-form"
        }
      }'
    ```
  </Tab>

  <Tab title="Node.js SDK">
    ```typescript theme={null}
    import { Taapit } from 'taapit-sdk';

    const taapit = new Taapit({
      apiKey: process.env.TAAPIT_API_KEY,
    });

    await taapit.track.lead({
      trackingId: 'rLnWe1uz9t282v7g',
      customer: {
        externalId: 'user_123',
        email: 'john@example.com',
        firstname: 'John',
        lastname: 'Doe',
      },
      metadata: {
        source: 'signup-form',
      },
    });
    ```
  </Tab>

  <Tab title="React Hook">
    ```tsx theme={null}
    import { useTaapitAnalytics } from 'taapit-sdk/react';

    function SignUpForm() {
      const { trackLead } = useTaapitAnalytics();

      const handleSignUp = async (user) => {
        trackLead({
          customer: {
            externalId: user.id,
            email: user.email,
            firstname: user.firstName,
            lastname: user.lastName,
          },
          metadata: {
            source: 'signup-form',
          },
        });
      };
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```html theme={null}
    <script src="https://taap.it/api/sdk" data-publishable-key="taapit_pk_xxx"></script>

    <script>
      taapit.trackLead({
        customer: {
          externalId: 'user_123',
          email: 'john@example.com',
          firstname: 'John',
          lastname: 'Doe',
        },
        metadata: {
          source: 'signup-form',
        },
      });
    </script>
    ```
  </Tab>
</Tabs>

## Response

<Tabs>
  <Tab title="200 OK">
    ```json theme={null}
    {
      "ok": true
    }
    ```
  </Tab>

  <Tab title="400 Bad Request">
    ```json theme={null}
    {
      "error": "Missing customer.externalId"
    }
    ```
  </Tab>

  <Tab title="401 Unauthorized">
    ```json theme={null}
    {
      "error": "Invalid API key"
    }
    ```
  </Tab>

  <Tab title="404 Not Found">
    ```json theme={null}
    {
      "error": "Click not found for this trackingId"
    }
    ```
  </Tab>
</Tabs>

## Error Codes

| HTTP Code | Error                                          | Description                             |
| --------- | ---------------------------------------------- | --------------------------------------- |
| 400       | `Invalid payload`                              | Request body validation failed          |
| 400       | `Missing customer.externalId`                  | Required field not provided             |
| 401       | `Invalid API key`                              | API key is invalid or revoked           |
| 401       | `Hostname not in allowed list`                 | Origin not whitelisted (client-side)    |
| 403       | `This click does not belong to your workspace` | trackingId is for a different workspace |
| 404       | `Click not found for this trackingId`          | trackingId doesn't exist or has expired |


# Track Sale
Source: https://docs.taap.it/api-reference/events/sale

POST /api/events/sale
Create a sale conversion event

## Endpoint

```
POST https://track.taap.it/api/events/sale
```

## Authentication

<Tabs>
  <Tab title="Server-side (Recommended)">
    Use your secret API key:

    ```bash theme={null}
    Authorization: Bearer taapit_sk_xxxxxxxxxxxx
    ```
  </Tab>

  <Tab title="Client-side">
    Use your publishable key:

    ```bash theme={null}
    X-Publishable-Key: taapit_pk_xxxxxxxxxxxx
    ```
  </Tab>
</Tabs>

## Request Body

| Field                  | Type   | Required | Description                                      |
| ---------------------- | ------ | -------- | ------------------------------------------------ |
| `trackingId`           | string | ✓        | The `ta_tid` from the cookie or URL parameter    |
| `customer`             | object | ✓        | Customer information                             |
| `customer.externalId`  | string | ✓        | Your internal user/customer ID                   |
| `customer.email`       | string |          | Customer's email address                         |
| `customer.firstname`   | string |          | Customer's first name                            |
| `customer.lastname`    | string |          | Customer's last name                             |
| `customer.phoneNumber` | string |          | Customer's phone number                          |
| `customer.avatarUrl`   | string |          | URL to customer's avatar image                   |
| `amount`               | number | ✓        | Transaction amount in currency units (not cents) |
| `currency`             | string | ✓        | ISO 4217 currency code (e.g., `eur`, `usd`)      |
| `metadata`             | object |          | Additional custom data (key-value pairs)         |

<Warning>
  **Amount format**: Use currency units, not cents.

  * ✅ `29.99` for €29.99
  * ❌ `2999` would be interpreted as €2999
</Warning>

## Examples

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://track.taap.it/api/events/sale \
      -H "Authorization: Bearer taapit_sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "trackingId": "rLnWe1uz9t282v7g",
        "customer": {
          "externalId": "user_123",
          "email": "john@example.com"
        },
        "amount": 99.99,
        "currency": "eur",
        "metadata": {
          "orderId": "order_456",
          "plan": "pro"
        }
      }'
    ```
  </Tab>

  <Tab title="Node.js SDK">
    ```typescript theme={null}
    import { Taapit } from 'taapit-sdk';

    const taapit = new Taapit({
      apiKey: process.env.TAAPIT_API_KEY,
    });

    await taapit.track.sale({
      trackingId: 'rLnWe1uz9t282v7g',
      customer: {
        externalId: 'user_123',
        email: 'john@example.com',
      },
      amount: 99.99,
      currency: 'eur',
      metadata: {
        orderId: 'order_456',
        plan: 'pro',
      },
    });
    ```
  </Tab>

  <Tab title="React Hook">
    ```tsx theme={null}
    import { useTaapitAnalytics } from 'taapit-sdk/react';

    function CheckoutButton({ order }) {
      const { trackSale } = useTaapitAnalytics();

      const handlePurchase = async () => {
        trackSale({
          customer: {
            externalId: order.userId,
            email: order.email,
          },
          amount: order.total,
          currency: 'eur',
          metadata: {
            orderId: order.id,
            plan: order.plan,
          },
        });
      };
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```html theme={null}
    <script src="https://taap.it/api/sdk" data-publishable-key="taapit_pk_xxx"></script>

    <script>
      taapit.trackSale({
        customer: {
          externalId: 'user_123',
          email: 'john@example.com',
        },
        amount: 99.99,
        currency: 'eur',
        metadata: {
          orderId: 'order_456',
        },
      });
    </script>
    ```
  </Tab>
</Tabs>

## Response

<Tabs>
  <Tab title="200 OK">
    ```json theme={null}
    {
      "ok": true
    }
    ```
  </Tab>

  <Tab title="400 Bad Request">
    ```json theme={null}
    {
      "error": "Invalid payload",
      "details": [
        {
          "path": ["amount"],
          "message": "Required"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="401 Unauthorized">
    ```json theme={null}
    {
      "error": "Invalid API key"
    }
    ```
  </Tab>

  <Tab title="404 Not Found">
    ```json theme={null}
    {
      "error": "Click not found for this trackingId"
    }
    ```
  </Tab>
</Tabs>

## Currency Codes

Use standard [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency codes:

| Currency          | Code  |
| ----------------- | ----- |
| Euro              | `eur` |
| US Dollar         | `usd` |
| British Pound     | `gbp` |
| Japanese Yen      | `jpy` |
| Swiss Franc       | `chf` |
| Canadian Dollar   | `cad` |
| Australian Dollar | `aud` |

## Error Codes

| HTTP Code | Error                                          | Description                             |
| --------- | ---------------------------------------------- | --------------------------------------- |
| 400       | `Invalid payload`                              | Request body validation failed          |
| 400       | `Missing customer.externalId`                  | Required field not provided             |
| 401       | `Invalid API key`                              | API key is invalid or revoked           |
| 401       | `Hostname not in allowed list`                 | Origin not whitelisted (client-side)    |
| 403       | `This click does not belong to your workspace` | trackingId is for a different workspace |
| 404       | `Click not found for this trackingId`          | trackingId doesn't exist or has expired |


# Create Link
Source: https://docs.taap.it/api-reference/links/create

POST https://api.taap.it/v1/links
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 type="string">
  Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`
</ParamField>

## Request Parameters

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

<ParamField 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">
  Unique identifier for the created link
</ResponseField>

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

<ResponseField name="updated_at" type="string">
  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">
  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">
  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>


# Delete Link
Source: https://docs.taap.it/api-reference/links/delete

DELETE https://api.taap.it/v1/links/{link_id}
Remove a link from your account

Permanently delete a link from your account.

**Request:**

```bash cURL theme={null}
curl -X DELETE 'https://api.taap.it/v1/links/link_987654321' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "message": "Link deleted successfully"
}
```

## Authorization

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

## Path Parameters

<ParamField type="string">
  Unique identifier for the link to delete
</ParamField>

## Query Parameters

<Warning>
  Deleting a link is permanent and cannot be undone. All analytics data associated with the link will also be removed.
</Warning>


# Retrieve Link
Source: https://docs.taap.it/api-reference/links/get

GET https://api.taap.it/v1/links/{link_id}
Retrieve details for a specific link

Get detailed information about a specific link by its ID.

**Request:**

```bash cURL theme={null}
curl -X GET 'https://api.taap.it/v1/links/link_987654321' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**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": "my-custom-link",
  "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,
  "is_archived": false,
  "expiration_date": "2024-12-31T23:59:59Z",
  "expiration_click_count": 1000,
  "clicks": 42
}
```

## Authorization

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

## Path Parameters

<ParamField type="string">
  Unique identifier for the link
</ParamField>


# List Links
Source: https://docs.taap.it/api-reference/links/list

GET https://api.taap.it/v1/links
Retrieve a paginated list of links with optional filtering

Retrieve all links with pagination and filtering options.

**Request:**

```bash cURL theme={null}
curl -X GET 'https://api.taap.it/v1/links?archived=false&sort_by=created_at&sort_order=desc&page=1&page_size=20&cursor=eyJpZCI6ImxpbmtfOTg3NjU0MzIxIn0=' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "items": [
    {
      "id": "link_987654321",
      "original_url": "https://example.com/very-long-url-that-needs-shortening",
      "short_url": "https://taap.it/my-custom-link",
      "code": "my-custom-link",
      "created_at": "2024-01-15T10:30:00Z",
      "click_count": 42,
      "is_active": true,
      "is_archived": false
    }
  ],
  "page": 1,
  "page_size": 10,
  "has_next": true,
  "has_prev": false,
  "next_cursor": "eyJpZCI6ImxpbmtfOTg3NjU0MzIxIn0=",
  "prev_cursor": null
}
```

## Authorization

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

## Query Parameters

### Pagination Parameters

<ParamField type="string">
  Cursor for pagination (use for efficient pagination)
</ParamField>

<ParamField type="integer">
  Page number (starts from 1)
</ParamField>

<ParamField type="integer">
  Number of items per page (maximum 100)
</ParamField>

### Sorting Parameters

<ParamField type="string">
  Field to sort by (e.g., "created\_at", "updated\_at", "clicks", "code")
</ParamField>

<ParamField type="string">
  Sort order: "asc" for ascending or "desc" for descending
</ParamField>

### Filtering Parameters

<ParamField type="boolean">
  Filter by archived status (true for archived links, false for active links)
</ParamField>


# Update Link
Source: https://docs.taap.it/api-reference/links/update

PUT https://api.taap.it/v1/links/{link_id}
Update an existing link's properties

Update properties of an existing link including URL, password, and expiration settings.

**Request:**

```bash cURL theme={null}
curl -X PUT 'https://api.taap.it/v1/links/link_987654321' \
  -H 'Authorization: Bearer taapit_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Marketing Link",
    "description": "Updated description for campaign",
    "original_url": "https://example.com/updated-url",
    "code": "updated-code",
    "app": "UpdatedApp",
    "app_logo": "https://example.com/new-logo.png",
    "android_link": "updatedapp://open?url=https://example.com",
    "ios_link": "updatedapp://open?url=https://example.com",
    "windows_link": "ms-windows-store://pdp/?productid=9NBLGGH987654",
    "macos_link": "macappstore://itunes.apple.com/app/updatedapp/id987654321",
    "whatsapp_message": "Check out this updated link!",
    "metadata": {
      "title": "Updated Product",
      "description": "Check out our updated product",
      "favicon": "https://example.com/new-favicon.ico",
      "social_image": "https://example.com/new-social-image.jpg"
    },
    "qr_code_options": {
      "size": 250,
      "color": "#FF0000",
      "background_color": "#FFFFFF",
      "logo": "https://example.com/new-logo.png",
      "logo_size": 60,
      "error_correction_level": "H"
    },
    "utm_name": "updated_campaign",
    "utm_source": "social",
    "utm_medium": "facebook",
    "utm_campaign": "updated2024",
    "utm_term": "updated_marketing",
    "utm_content": "updated_cta_button",
    "utm_template_id": "template_456",
    "referrer": "https://facebook.com",
    "password": "newpassword123",
    "password_description": "Enter new password to access link",
    "excluded_countries": [
      {
        "code": "CA",
        "label": "Canada",
        "phone": "+1",
        "suggested": false,
        "lang": "en",
        "continent": "North America"
      }
    ],
    "has_public_stat": false,
    "enable_conversion_tracking": true,
    "is_archived": false,
    "expiration_date": "2024-06-30T23:59:59Z",
    "expiration_click_count": 500,
    "pixel_id": "pixel_789123456"
  }'
```

**Response:**

```json theme={null}
{
  "id": "link_987654321",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:00:00Z",
  "project_id": "project_123456789",
  "domain_id": "domain_987654321",
  "pixel_id": "pixel_789123456",
  "original_url": "https://example.com/updated-url",
  "name": "Updated Marketing Link",
  "description": "Updated description for campaign",
  "code": "updated-code",
  "app": "UpdatedApp",
  "app_logo": "https://example.com/new-logo.png",
  "android_link": "updatedapp://open?url=https://example.com",
  "ios_link": "updatedapp://open?url=https://example.com",
  "windows_link": "ms-windows-store://pdp/?productid=9NBLGGH987654",
  "macos_link": "macappstore://itunes.apple.com/app/updatedapp/id987654321",
  "whatsapp_message": "Check out this updated link!",
  "metadata": {
    "title": "Updated Product",
    "description": "Check out our updated product",
    "favicon": "https://example.com/new-favicon.ico",
    "social_image": "https://example.com/new-social-image.jpg"
  },
  "qr_code_options": {
    "size": 250,
    "color": "#FF0000",
    "background_color": "#FFFFFF",
    "logo": "https://example.com/new-logo.png",
    "logo_size": 60,
    "error_correction_level": "H"
  },
  "utm_name": "updated_campaign",
  "utm_source": "social",
  "utm_medium": "facebook",
  "utm_campaign": "updated2024",
  "utm_term": "updated_marketing",
  "utm_content": "updated_cta_button",
  "utm_template_id": "template_456",
  "referrer": "https://facebook.com",
  "password": "newpassword123",
  "password_description": "Enter new password to access link",
  "excluded_countries": [
    {
      "code": "CA",
      "label": "Canada",
      "phone": "+1",
      "suggested": false,
      "lang": "en",
      "continent": "North America"
    }
  ],
  "has_public_stat": false,
  "enable_conversion_tracking": true,
  "is_archived": false,
  "expiration_date": "2024-06-30T23:59:59Z",
  "expiration_click_count": 500,
  "clicks": 42
}
```

## Authorization

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

## Path Parameters

<ParamField type="string">
  Unique identifier for the link
</ParamField>

## Request Body

All parameters are optional for updates. Only include the fields you want to update.

### Core Parameters

<ParamField type="string">
  Updated name for the link
</ParamField>

<ParamField type="string">
  Updated description for the link
</ParamField>

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

<ParamField type="string">
  Updated short code for the link
</ParamField>

<ParamField type="string">
  Updated tracking pixel ID to associate with this link
</ParamField>

<ParamField type="string">
  Updated project ID to associate with this link
</ParamField>

### Deep Linking Parameters

<ParamField type="string">
  Updated name of the mobile app for deep linking
</ParamField>

<ParamField type="string">
  Updated URL to the app logo image
</ParamField>

<ParamField type="string">
  Updated Android deep link URL (e.g., myapp\://open?url=...)
</ParamField>

<ParamField type="string">
  Updated iOS deep link URL (e.g., myapp\://open?url=...)
</ParamField>

<ParamField type="string">
  Updated Windows deep link URL (e.g., ms-windows-store://...)
</ParamField>

<ParamField type="string">
  Updated macOS deep link URL (e.g., macappstore://...)
</ParamField>

<ParamField type="string">
  Updated pre-filled message for WhatsApp sharing
</ParamField>

### Metadata Parameters

<ParamField type="object">
  Updated link metadata for website previews

  <Expandable title="Metadata properties">
    <ParamField type="string">
      Updated page title for link previews
    </ParamField>

    <ParamField type="string">
      Updated page description for link previews
    </ParamField>

    <ParamField type="string">
      Updated URL to favicon image
    </ParamField>

    <ParamField type="string">
      Updated URL to social media preview image
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Updated QR code generation options

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

    <ParamField type="string">
      Updated QR code color (hex format, e.g., #000000)
    </ParamField>

    <ParamField type="string">
      Updated QR code background color (hex format, e.g., #ffffff)
    </ParamField>

    <ParamField type="string">
      Updated URL to logo image to embed in QR code
    </ParamField>

    <ParamField type="integer">
      Updated logo size in pixels
    </ParamField>

    <ParamField type="string">
      Updated error correction level (L, M, Q, H)
    </ParamField>
  </Expandable>
</ParamField>

### UTM Parameters

<ParamField type="string">
  Updated UTM campaign name
</ParamField>

<ParamField type="string">
  Updated UTM source (e.g., email, social, google)
</ParamField>

<ParamField type="string">
  Updated UTM medium (e.g., newsletter, post, cpc)
</ParamField>

<ParamField type="string">
  Updated UTM campaign identifier
</ParamField>

<ParamField type="string">
  Updated UTM term (keywords)
</ParamField>

<ParamField type="string">
  Updated UTM content (e.g., cta\_button, banner)
</ParamField>

<ParamField type="string">
  Updated UTM template identifier
</ParamField>

<ParamField type="string">
  Updated referrer URL
</ParamField>

### Security & Access Parameters

<ParamField type="string">
  Updated password to protect the link (requires plan feature)
</ParamField>

<ParamField type="string">
  Updated description shown when password is required
</ParamField>

<ParamField type="array">
  Updated array of countries to exclude from accessing the link

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

    <ParamField type="string">
      Country name
    </ParamField>

    <ParamField type="string">
      Country phone code
    </ParamField>

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

    <ParamField type="string">
      Primary language code
    </ParamField>

    <ParamField type="string">
      Continent name
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="boolean">
  Updated setting for whether link statistics are publicly accessible
</ParamField>

### Conversion Tracking Parameters

<ParamField type="boolean">
  Updated setting for whether conversion tracking is enabled on this link
</ParamField>

### Status Parameters

<ParamField type="boolean">
  Updated archive status of the link
</ParamField>

### Expiration Parameters

<ParamField type="string">
  Updated ISO 8601 datetime when link expires (requires plan feature)
</ParamField>

<ParamField type="integer">
  Updated maximum number of clicks before link expires (requires plan feature)
</ParamField>


# Create Project
Source: https://docs.taap.it/api-reference/projects/create

POST https://api.taap.it/v1/projects
Create a new project to organize your links

**Request:**

```bash cURL theme={null}
curl -X POST 'https://api.taap.it/v1/projects' \
  -H 'Authorization: Bearer taapit_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Summer Marketing Campaign",
    "description": "Links for our summer marketing campaign",
    "color": "#FF6B6B"
  }'
```

**Response:**

```json theme={null}
{
  "id": "project_987654321",
  "created_at": "2024-01-15T10:30:00Z",
  "name": "Summer Marketing Campaign",
  "description": "Links for our summer marketing campaign",
  "color": "#FF6B6B"
}
```

## Authorization

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

## Request Parameters

<ParamField type="string">
  Name of the project
</ParamField>

<ParamField type="string">
  Optional description for the project
</ParamField>

<ParamField type="string">
  Color for the project in hex format (e.g., #FF6B6B, #FFF). Defaults to #000000 (black) if not provided. Must include the # symbol and be a valid 3 or 6 character hex color.
</ParamField>

## Response Fields

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

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

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

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

<ResponseField name="color" type="string">
  Color of the project in hex format (uppercase). Always present with default value #000000 if not specified during creation.
</ResponseField>


# Delete Project
Source: https://docs.taap.it/api-reference/projects/delete

DELETE https://api.taap.it/v1/projects/{project_id}
Remove a project from your account

**Request:**

```bash cURL theme={null}
curl -X DELETE 'https://api.taap.it/v1/projects/project_987654321' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "message": "Project deleted successfully"
}
```

## Authorization

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

## Path Parameters

<ParamField type="string">
  Unique identifier for the project to delete
</ParamField>

<Warning>
  Deleting a project will not delete the links associated with it. Links will remain but will no longer be associated with the deleted project.
</Warning>


# Retrieve Project
Source: https://docs.taap.it/api-reference/projects/get

GET https://api.taap.it/v1/projects/{project_id}
Retrieve details for a specific project

**Request:**

```bash cURL theme={null}
curl -X GET 'https://api.taap.it/v1/projects/project_987654321' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "id": "project_987654321",
  "name": "Summer Marketing Campaign",
  "description": "Links for our summer marketing campaign",
  "created_at": "2024-01-15T10:30:00Z"
}
```

## Authorization

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

## Path Parameters

<ParamField type="string">
  Unique identifier for the project
</ParamField>

## Response Fields

<ResponseField name="id" type="string">
  Unique identifier for the project
</ResponseField>

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

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

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


# List Projects
Source: https://docs.taap.it/api-reference/projects/list

GET https://api.taap.it/v1/projects
Retrieve a paginated list of projects

**Request:**

```bash cURL theme={null}
curl -X GET 'https://api.taap.it/v1/projects?sort_by=created_at&sort_order=desc&page=1&page_size=20&cursor=eyJpZCI6InByb2plY3RfOTg3NjU0MzIxIn0=' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "items": [
    {
      "id": "project_987654321",
      "name": "Summer Marketing Campaign",
      "description": "Links for our summer marketing campaign",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "page": 1,
  "page_size": 10,
  "has_next": false
}
```

## Authorization

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

## Query Parameters

### Pagination Parameters

<ParamField type="string">
  Cursor for pagination (use for efficient pagination)
</ParamField>

<ParamField type="integer">
  Page number (starts from 1)
</ParamField>

<ParamField type="integer">
  Number of items per page (maximum 100)
</ParamField>

### Sorting Parameters

<ParamField type="string">
  Field to sort by (e.g., "created\_at", "updated\_at", "name")
</ParamField>

<ParamField type="string">
  Sort order: "asc" for ascending or "desc" for descending
</ParamField>


# Update Project
Source: https://docs.taap.it/api-reference/projects/update

PUT https://api.taap.it/v1/projects/{project_id}
Update an existing project's details

**Request:**

```bash cURL theme={null}
curl -X PUT 'https://api.taap.it/v1/projects/project_987654321' \
  -H 'Authorization: Bearer taapit_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Summer Marketing Campaign 2024",
    "description": "Updated description for campaign"
  }'
```

**Response:**

```json theme={null}
{
  "id": "project_987654321",
  "name": "Summer Marketing Campaign 2024",
  "description": "Updated description for campaign",
  "updated_at": "2024-01-15T11:00:00Z"
}
```

## Authorization

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

## Path Parameters

<ParamField type="string">
  Unique identifier for the project to update
</ParamField>

## Request Parameters

<ParamField type="string">
  Name of the project
</ParamField>

<ParamField type="string">
  Optional description for the project
</ParamField>

<ParamField type="string">
  Color for the project in hex format (e.g., #FF6B6B, #FFF). Must include the # symbol and be a valid 3 or 6 character hex color. Color will be normalized to uppercase.
</ParamField>

## Response Fields

<ResponseField name="id" type="string">
  Unique identifier for the updated project
</ResponseField>

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

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

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


# Breakdowns
Source: https://docs.taap.it/api-reference/radar/breakdowns

GET https://taap.it/api/v1/radar/breakdowns
Retrieve top pages, sources, locations and devices

Returns the top breakdowns (pages, sources, locations and devices) for the project bound to your
API key over the requested date range.

**Request:**

```bash cURL theme={null}
curl -X GET 'https://taap.it/api/v1/radar/breakdowns?start=2026-01-01T00:00:00Z&end=2026-01-31T23:59:59Z&limit=20' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "data": {
    "pages": {
      "top": [
        { "pathname": "/", "people": 320 },
        { "pathname": "/pricing", "people": 110 }
      ]
    },
    "sources": {
      "referrer": [
        { "name": "Direct", "people": 210 },
        { "name": "Google", "people": 180 }
      ]
    },
    "locations": {
      "countries": [
        { "name": "France", "people": 240, "countryCode": "FR", "revenue": 980.0 },
        { "name": "Belgium", "people": 90, "countryCode": "BE", "revenue": 120.0 }
      ]
    },
    "devices": {
      "browsers": [
        { "name": "Chrome", "people": 410 },
        { "name": "Safari", "people": 220 }
      ],
      "os": [
        { "name": "Windows", "people": 300 },
        { "name": "iOS", "people": 180 }
      ]
    },
    "events": [
      { "event_name": "signup_click", "people": 40, "events": 52, "completion_rate": 0 }
    ],
    "hostnames": ["www.example.com"]
  }
}
```

## Authorization

<ParamField type="string">
  Bearer token with your Radar API key. Format: `Bearer taapit_...`
</ParamField>

## Query Parameters

<ParamField type="string">
  Start of the range, ISO 8601 (UTC). Example: `2026-01-01T00:00:00Z`.
</ParamField>

<ParamField type="string">
  End of the range, ISO 8601 (UTC). Example: `2026-01-31T23:59:59Z`.
</ParamField>

<ParamField type="integer">
  Maximum number of rows per breakdown. Must be a positive number. Defaults to `50`.
</ParamField>

## Response Fields

<ResponseField name="data" type="object">
  Each section is optional and omitted when there is no data.

  <Expandable title="Breakdowns">
    <ResponseField name="pages.top" type="array">
      Top pages, each with `pathname` and `people`.
    </ResponseField>

    <ResponseField name="sources.referrer" type="array">
      Top referrers, each with `name` and `people`.
    </ResponseField>

    <ResponseField name="locations.countries" type="array">
      Top countries, each with `name`, `people`, `countryCode` and `revenue`.
    </ResponseField>

    <ResponseField name="devices.browsers" type="array">
      Top browsers, each with `name` and `people`.
    </ResponseField>

    <ResponseField name="devices.os" type="array">
      Top operating systems, each with `name` and `people`.
    </ResponseField>

    <ResponseField name="events" type="array">
      Top custom events, each with `event_name`, `people` and `events`.
    </ResponseField>

    <ResponseField name="hostnames" type="array">
      Hostnames seen for the project in the range.
    </ResponseField>
  </Expandable>
</ResponseField>


# Custom events
Source: https://docs.taap.it/api-reference/radar/custom-events

GET https://taap.it/api/v1/radar/custom-events
Most frequent custom events tracked for the project

Returns the most frequent custom events tracked for the project bound to your API key, ranked by
volume.

**Request:**

```bash cURL theme={null}
curl -X GET 'https://taap.it/api/v1/radar/custom-events?start=2026-01-01T00:00:00Z&end=2026-01-31T23:59:59Z&limit=20' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "data": [
    { "event_name": "signup_click", "people": 240, "events": 312, "completion_rate": 0 },
    { "event_name": "add_to_cart", "people": 180, "events": 410, "completion_rate": 0 }
  ],
  "limit": 20
}
```

## Authorization

<ParamField type="string">
  Bearer token with your Radar API key. Format: `Bearer taapit_...`
</ParamField>

## Query Parameters

<ParamField type="string">
  Start of the range, ISO 8601 (UTC). Optional — omit for all time.
</ParamField>

<ParamField type="string">
  End of the range, ISO 8601 (UTC). Optional — omit for all time.
</ParamField>

<ParamField type="integer">
  Maximum number of events to return. Capped at `500`.
</ParamField>

## Response Fields

<ResponseField name="data" type="array">
  Custom events ranked by volume.

  <Expandable title="Event">
    <ResponseField name="event_name" type="string">Name of the custom event.</ResponseField>
    <ResponseField name="people" type="number">Number of unique people who triggered it.</ResponseField>
    <ResponseField name="events" type="number">Total number of times the event fired.</ResponseField>
    <ResponseField name="completion_rate" type="number">Reserved for funnel use; currently `0`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="limit" type="integer">
  The effective limit applied to this response.
</ResponseField>


# Radar API
Source: https://docs.taap.it/api-reference/radar/introduction

Read your Radar (Visitors) analytics programmatically with a project-scoped API key

The **Radar API** lets external applications read the analytics collected by Taapit Radar
(the Visitors product): aggregate metrics, time series, realtime visitors and top
breakdowns (pages, sources, locations, devices).

## Base URL

```
https://taap.it/api/v1/radar
```

## Authentication

Radar endpoints are authenticated with a **project-scoped API key**. Every key belongs to a
single Radar project (one website), so you never pass a `projectId` — the project is resolved
from the key itself.

Send the key as a Bearer token:

```http theme={null}
Authorization: Bearer taapit_your_api_key_here
```

You can also use the `x-api-key` header instead:

```http theme={null}
x-api-key: taapit_your_api_key_here
```

<Info>
  API keys are created from the Radar dashboard under **Project settings → API**. The full key
  is shown only once at creation — store it securely and never expose it client-side.
</Info>

### Permissions

Each key carries a permission level (**All**, **Read only** or **Restricted**). All current
Radar endpoints are read-only, so any permission level can call them. Write scopes are reserved
for future write endpoints.

## Endpoints

<CardGroup>
  <Card title="Metrics" icon="chart-simple" href="/api-reference/radar/metrics">
    Aggregate metrics over a date range (people, visits, pageviews, revenue…).
  </Card>

  <Card title="Time series" icon="chart-line" href="/api-reference/radar/timeseries">
    Time-bucketed series of the core metrics.
  </Card>

  <Card title="Realtime" icon="signal-stream" href="/api-reference/radar/realtime">
    Active visitors in a rolling window.
  </Card>

  <Card title="Breakdowns" icon="layer-group" href="/api-reference/radar/breakdowns">
    Top pages, sources, locations and devices.
  </Card>

  <Card title="People" icon="users" href="/api-reference/radar/people">
    List people (visitors) with their key attributes and filters.
  </Card>

  <Card title="Person details" icon="user" href="/api-reference/radar/people-details">
    A single person with their sessions and activity heatmap.
  </Card>

  <Card title="Last visitors" icon="bolt" href="/api-reference/radar/last-visitors">
    Visitors active in the last few minutes (live feed).
  </Card>

  <Card title="Custom events" icon="bullseye" href="/api-reference/radar/custom-events">
    Most frequent custom events tracked for the project.
  </Card>
</CardGroup>

## Date parameters

Endpoints that accept a date range use the `start` and `end` query parameters in ISO 8601
format (UTC), for example `2026-01-01T00:00:00Z`.

## Rate limits & quotas

Radar endpoints are backed by an analytics engine that bills per query, so each API key has
**per-key rate limits** to keep usage (and your costs) under control:

| Window | Default limit           |
| ------ | ----------------------- |
| Second | 3 requests / second     |
| Minute | 60 requests / minute    |
| Day    | 5,000 requests / day    |
| Month  | 50,000 requests / month |

The per-second cap is a **burst guard**: a single key can never spike above a few requests per
second, keeping usage comfortably under the analytics engine's per-second billing threshold.

Every response includes rate-limit headers so you can track your remaining budget:

```http theme={null}
X-RateLimit-Limit: 5000        # daily limit
X-RateLimit-Remaining: 4987    # requests left today
X-RateLimit-Reset: 1769990400  # UTC epoch seconds when the daily window resets
```

When a limit is exceeded the API returns **`429 Too Many Requests`** with a `Retry-After`
header (seconds to wait) and a `scope` field indicating which window was hit
(`second`, `minute`, `day` or `month`).

<Warning>
  Usage is logged **per key and per endpoint**. Polling endpoints like `realtime` and
  `last-visitors` consume quota on every call — cache responses and avoid sub-minute polling
  unless you really need it. Each call to `breakdowns` runs several aggregations, so it counts
  as one request but is heavier than a single metric read.
</Warning>

## Errors

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "Both 'start' and 'end' query parameters are required"
  }
  ```

  ```json 429 Too Many Requests theme={null}
  {
    "error": "Rate limit exceeded",
    "scope": "minute",
    "retryAfterSeconds": 42
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "error": "Internal server error"
  }
  ```
</ResponseExample>


# Last visitors
Source: https://docs.taap.it/api-reference/radar/last-visitors

GET https://taap.it/api/v1/radar/last-visitors
Visitors active within the last few minutes (live feed)

Returns the visitors that were active within the last `minutes`. This is a live feed; responses
are never cached.

<Warning>
  This endpoint is meant for live dashboards. It consumes quota on every call — avoid polling more
  than once per minute. See [Rate limits](/api-reference/radar/introduction#rate-limits-quotas).
</Warning>

**Request:**

```bash cURL theme={null}
curl -X GET 'https://taap.it/api/v1/radar/last-visitors?minutes=5' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "visitorId": "v_8a1c2d",
      "countryCode": "FR",
      "city": "Paris",
      "page": "/pricing",
      "referrer": "google",
      "device": "mobile",
      "lastSeen": "2026-01-28T17:42:10.000Z"
    }
  ],
  "windowMinutes": 5
}
```

## Authorization

<ParamField type="string">
  Bearer token with your Radar API key. Format: `Bearer taapit_...`
</ParamField>

## Query Parameters

<ParamField type="integer">
  Rolling window in minutes. Minimum `1`, maximum `60`.
</ParamField>

## Response Fields

<ResponseField name="data" type="array">
  Visitors active in the window, ordered by most recent activity. Each entry includes the
  visitor's location, current page, referrer and device.
</ResponseField>

<ResponseField name="windowMinutes" type="integer">
  The window size applied to this response.
</ResponseField>


# Metrics
Source: https://docs.taap.it/api-reference/radar/metrics

GET https://taap.it/api/v1/radar/overview
Retrieve aggregate Radar metrics for a date range

Returns aggregate metrics for the project bound to your API key over the requested date range.

**Request:**

```bash cURL theme={null}
curl -X GET 'https://taap.it/api/v1/radar/overview?start=2026-01-01T00:00:00Z&end=2026-01-31T23:59:59Z' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "data": {
    "people": 1280,
    "visits": 1890,
    "pageviews": 5230,
    "events": 412,
    "revenue": 1990.5,
    "revenue_currency": "EUR",
    "sales": 23,
    "conversion_rate": 1.79,
    "revenue_per_visitor": 1.05,
    "bounce_rate": 38.2,
    "avg_duration_s": 142,
    "avg_duration_mmss": "02:22"
  }
}
```

## Authorization

<ParamField type="string">
  Bearer token with your Radar API key. Format: `Bearer taapit_...`
</ParamField>

## Query Parameters

<ParamField type="string">
  Start of the range, ISO 8601 (UTC). Example: `2026-01-01T00:00:00Z`.
</ParamField>

<ParamField type="string">
  End of the range, ISO 8601 (UTC). Example: `2026-01-31T23:59:59Z`.
</ParamField>

## Response Fields

<ResponseField name="data" type="object">
  <Expandable title="Metrics">
    <ResponseField name="people" type="integer">Unique visitors.</ResponseField>
    <ResponseField name="visits" type="integer">Number of sessions.</ResponseField>
    <ResponseField name="pageviews" type="integer">Total pageviews.</ResponseField>
    <ResponseField name="events" type="integer">Custom events tracked.</ResponseField>
    <ResponseField name="revenue" type="number">Attributed revenue.</ResponseField>
    <ResponseField name="revenue_currency" type="string">ISO 4217 currency of `revenue`.</ResponseField>
    <ResponseField name="sales" type="integer">Number of sales / conversions.</ResponseField>
    <ResponseField name="conversion_rate" type="number">Conversion rate (percentage).</ResponseField>
    <ResponseField name="revenue_per_visitor" type="number">Revenue divided by unique visitors.</ResponseField>
    <ResponseField name="bounce_rate" type="number">Bounce rate (percentage).</ResponseField>
    <ResponseField name="avg_duration_s" type="integer">Average session duration in seconds.</ResponseField>
    <ResponseField name="avg_duration_mmss" type="string">Average session duration as `mm:ss`.</ResponseField>
  </Expandable>
</ResponseField>


# People
Source: https://docs.taap.it/api-reference/radar/people

GET https://taap.it/api/v1/radar/people
List people (visitors) for the project bound to your API key

Returns a paginated list of people (visitors) over the requested date range, with their key
attributes (identity, location, source, device, revenue, sessions). Supports optional filters.

**Request:**

```bash cURL theme={null}
curl -X GET 'https://taap.it/api/v1/radar/people?start=2026-01-01T00:00:00Z&end=2026-01-31T23:59:59Z&limit=50&sort=recent' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "visitorId": "v_8a1c2d",
      "name": "Quiet Fox",
      "email": "jane@example.com",
      "status": "identified",
      "countryCode": "FR",
      "countryName": "France",
      "source": "google",
      "browser": "Chrome",
      "device": "desktop",
      "revenue": 120.0,
      "sessions": 4,
      "events": 37,
      "firstSeen": "2026-01-03T09:12:00.000Z",
      "lastSeen": "2026-01-28T17:42:00.000Z"
    }
  ],
  "total": 1842,
  "limit": 50
}
```

## Authorization

<ParamField type="string">
  Bearer token with your Radar API key. Format: `Bearer taapit_...`
</ParamField>

## Query Parameters

<ParamField type="string">
  Start of the range, ISO 8601 (UTC). Example: `2026-01-01T00:00:00Z`.
</ParamField>

<ParamField type="string">
  End of the range, ISO 8601 (UTC). Example: `2026-01-31T23:59:59Z`.
</ParamField>

<ParamField type="string">
  Sort order. `recent` (last activity), `revenue`, `sessions` or `events`.
</ParamField>

<ParamField type="integer">
  Maximum number of people to return. Capped at `1000`.
</ParamField>

<ParamField type="string">
  Filter by ISO-2 country code (e.g. `FR`).
</ParamField>

<ParamField type="string">
  Filter by browser name (e.g. `Chrome`).
</ParamField>

<ParamField type="string">
  Filter by device type (`desktop`, `mobile`, `tablet`).
</ParamField>

<ParamField type="string">
  Filter by traffic source / referrer.
</ParamField>

<ParamField type="string">
  Filter by identity status (`identified` or `anonymous`).
</ParamField>

<ParamField type="string">
  Filter by activity level.
</ParamField>

## Response Fields

<ResponseField name="data" type="array">
  Array of people.

  <Expandable title="Person">
    <ResponseField name="visitorId" type="string">Stable visitor identifier.</ResponseField>
    <ResponseField name="name" type="string">Real name if known, otherwise a generated alias.</ResponseField>
    <ResponseField name="email" type="string | null">Email when the visitor is identified.</ResponseField>
    <ResponseField name="status" type="string">`identified` or `anonymous`.</ResponseField>
    <ResponseField name="countryCode" type="string">ISO-2 country code, or `XX` if unknown.</ResponseField>
    <ResponseField name="countryName" type="string">Human-readable country name.</ResponseField>
    <ResponseField name="source" type="string">Traffic source / referrer.</ResponseField>
    <ResponseField name="browser" type="string">Browser name.</ResponseField>
    <ResponseField name="device" type="string">Device type.</ResponseField>
    <ResponseField name="revenue" type="number">Total attributed revenue.</ResponseField>
    <ResponseField name="sessions" type="number">Number of sessions.</ResponseField>
    <ResponseField name="events" type="number">Number of events.</ResponseField>
    <ResponseField name="firstSeen" type="string">First activity, ISO 8601.</ResponseField>
    <ResponseField name="lastSeen" type="string">Last activity, ISO 8601.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of people in the range (unfiltered). Equals `data.length` when filters are applied.
</ResponseField>

<ResponseField name="limit" type="integer">
  The effective limit applied to this response.
</ResponseField>


# Person details
Source: https://docs.taap.it/api-reference/radar/people-details

GET https://taap.it/api/v1/radar/people/details
Retrieve a single person with their sessions and activity heatmap

Returns one person (visitor) with their profile, the list of sessions in the range, and a daily
activity heatmap. Responses are always freshly computed (not cached).

**Request:**

```bash cURL theme={null}
curl -X GET 'https://taap.it/api/v1/radar/people/details?visitorId=v_8a1c2d&start=2026-01-01T00:00:00Z&end=2026-01-31T23:59:59Z' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "data": {
    "visitor": {
      "visitorId": "v_8a1c2d",
      "name": "Quiet Fox",
      "email": "jane@example.com",
      "status": "identified",
      "countryCode": "FR",
      "countryName": "France",
      "source": "google",
      "browser": "Chrome",
      "device": "desktop",
      "revenue": 120.0,
      "sessions": 4,
      "firstSeen": "2026-01-03T09:12:00.000Z",
      "lastSeen": "2026-01-28T17:42:00.000Z"
    },
    "sessions": [
      {
        "sessionId": "s_5f2a",
        "startTime": "2026-01-28T17:10:00.000Z",
        "endTime": "2026-01-28T17:42:00.000Z",
        "durationSeconds": 1920,
        "referrer": "google",
        "device": "desktop",
        "browser": "Chrome",
        "os": "macOS"
      }
    ],
    "heatmap": [
      { "date": "2026-01-28", "events": 12 }
    ]
  }
}
```

## Authorization

<ParamField type="string">
  Bearer token with your Radar API key. Format: `Bearer taapit_...`
</ParamField>

## Query Parameters

<ParamField type="string">
  The visitor identifier returned by the [People](/api-reference/radar/people) endpoint.
</ParamField>

<ParamField type="string">
  Start of the range, ISO 8601 (UTC).
</ParamField>

<ParamField type="string">
  End of the range, ISO 8601 (UTC).
</ParamField>

## Response Fields

<ResponseField name="data.visitor" type="object">
  The person's profile (same shape as a row in the People endpoint).
</ResponseField>

<ResponseField name="data.sessions" type="array">
  Sessions within the range.

  <Expandable title="Session">
    <ResponseField name="sessionId" type="string">Session identifier.</ResponseField>
    <ResponseField name="startTime" type="string">Session start, ISO 8601.</ResponseField>
    <ResponseField name="endTime" type="string">Session end, ISO 8601.</ResponseField>
    <ResponseField name="durationSeconds" type="number">Session duration in seconds.</ResponseField>
    <ResponseField name="referrer" type="string">Session source / referrer.</ResponseField>
    <ResponseField name="device" type="string">Device type.</ResponseField>
    <ResponseField name="browser" type="string">Browser name.</ResponseField>
    <ResponseField name="os" type="string">Operating system.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.heatmap" type="array">
  Daily activity, each entry with `date` (YYYY-MM-DD) and `events` count.
</ResponseField>

<ResponseExample>
  ```json 404 Not Found theme={null}
  {
    "error": "Visitor not found"
  }
  ```
</ResponseExample>


# Realtime
Source: https://docs.taap.it/api-reference/radar/realtime

GET https://taap.it/api/v1/radar/realtime
Retrieve the number of active visitors in a rolling window

Returns the number of active visitors in a rolling window for the project bound to your API key.

**Request:**

```bash cURL theme={null}
curl -X GET 'https://taap.it/api/v1/radar/realtime?windowMinutes=30' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "data": {
    "active_visitors": 17
  }
}
```

## Authorization

<ParamField type="string">
  Bearer token with your Radar API key. Format: `Bearer taapit_...`
</ParamField>

## Query Parameters

<ParamField type="integer">
  Rolling window size in minutes. Must be a positive number. Defaults to `30`.
</ParamField>

## Response Fields

<ResponseField name="data" type="object">
  <Expandable title="Realtime">
    <ResponseField name="active_visitors" type="integer">
      Number of visitors active within the window.
    </ResponseField>
  </Expandable>
</ResponseField>


# Time series
Source: https://docs.taap.it/api-reference/radar/timeseries

GET https://taap.it/api/v1/radar/timeseries
Retrieve a time-bucketed series of the core Radar metrics

Returns the core metrics bucketed over time for the project bound to your API key. The bucket
granularity is derived automatically from the requested range.

**Request:**

```bash cURL theme={null}
curl -X GET 'https://taap.it/api/v1/radar/timeseries?start=2026-01-01T00:00:00Z&end=2026-01-07T23:59:59Z' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "t": "2026-01-01 00:00:00",
      "people": 120,
      "visits": 180,
      "pageviews": 540,
      "events": 32,
      "revenue": 210.0
    },
    {
      "t": "2026-01-02 00:00:00",
      "people": 96,
      "visits": 140,
      "pageviews": 410,
      "events": 21,
      "revenue": 0
    }
  ]
}
```

## Authorization

<ParamField type="string">
  Bearer token with your Radar API key. Format: `Bearer taapit_...`
</ParamField>

## Query Parameters

<ParamField type="string">
  Start of the range, ISO 8601 (UTC). Example: `2026-01-01T00:00:00Z`.
</ParamField>

<ParamField type="string">
  End of the range, ISO 8601 (UTC). Example: `2026-01-07T23:59:59Z`.
</ParamField>

## Response Fields

<ResponseField name="data" type="array">
  An ordered array of data points.

  <Expandable title="Data point">
    <ResponseField name="t" type="string">Bucket timestamp (`YYYY-MM-DD HH:MM:SS`, UTC).</ResponseField>
    <ResponseField name="people" type="integer">Unique visitors in the bucket.</ResponseField>
    <ResponseField name="visits" type="integer">Sessions in the bucket.</ResponseField>
    <ResponseField name="pageviews" type="integer">Pageviews in the bucket.</ResponseField>
    <ResponseField name="events" type="integer">Custom events in the bucket.</ResponseField>
    <ResponseField name="revenue" type="number">Attributed revenue in the bucket.</ResponseField>
  </Expandable>
</ResponseField>


# Link Statistics
Source: https://docs.taap.it/api-reference/stats/link-stats

GET https://api.taap.it/v1/stats/links/{link_id}
Retrieve detailed statistics for a specific link

**Request:**

```bash cURL theme={null}
curl -X GET 'https://api.taap.it/v1/stats/links/link_987654321?start_date=2024-01-01T00:00:00Z&end_date=2024-01-31T23:59:59Z&max_days=30' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
[
  {
    "id": "stat_123456789",
    "link_id": "link_987654321",
    "last_updated": "2024-01-15T10:30:00Z",
    "click_date": "2024-01-15",
    "total_clicks": 45,
    "unique_visitors": 38,
    "scans_only": 5,
    "clicks_only": 40,
    "chrome_clicks": 25,
    "ios_clicks": 15,
    "android_clicks": 5,
    "os_stats": {
      "iOS": 15,
      "Android": 5,
      "Windows": 20,
      "macOS": 5
    },
    "city_stats": {
      "New York": 10,
      "Los Angeles": 8,
      "Toronto": 5
    },
    "os_version_stats": {
      "iOS 17.0": 10,
      "iOS 16.5": 5,
      "Android 13": 3,
      "Android 12": 2
    },
    "lang_stats": {
      "en": 30,
      "fr": 8,
      "es": 7
    },
    "device_stats": {
      "mobile": 28,
      "desktop": 15,
      "tablet": 2
    },
    "browser_stats": {
      "Chrome": 32,
      "Safari": 8,
      "Firefox": 3,
      "Edge": 2
    },
    "country_stats": {
      "US": 25,
      "CA": 12,
      "UK": 8
    },
    "device_and_os_stats": {
      "iPhone iOS": 15,
      "Android Phone": 5,
      "Windows Desktop": 20,
      "Mac Desktop": 5
    },
    "app_stats": {
      "Safari": 8,
      "Chrome Mobile": 15,
      "Chrome Desktop": 17
    },
    "device_type_stats": {
      "smartphone": 20,
      "desktop": 20,
      "tablet": 5
    },
    "from_app_stats": {
      "true": 8,
      "false": 37
    },
    "continent_stats": {
      "North America": 37,
      "Europe": 8
    }
  }
]
```

## Authorization

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

## Path Parameters

<ParamField type="string">
  Unique identifier for the link
</ParamField>

## Query Parameters

<ParamField type="string">
  Start date for statistics (ISO 8601 format, e.g., 2024-01-01T00:00:00Z)
</ParamField>

<ParamField type="string">
  End date for statistics (ISO 8601 format, e.g., 2024-01-31T23:59:59Z)
</ParamField>

<ParamField type="integer">
  Maximum number of days to retrieve statistics for (minimum: 1, maximum: 30)
</ParamField>

## Response Fields

<ResponseField name="id" type="string">
  Unique identifier for the statistics record
</ResponseField>

<ResponseField name="link_id" type="string">
  Unique identifier for the link
</ResponseField>

<ResponseField name="last_updated" type="string">
  ISO 8601 timestamp when the statistics were last updated
</ResponseField>

<ResponseField name="click_date" type="string">
  Date for the statistics (YYYY-MM-DD format)
</ResponseField>

<ResponseField name="total_clicks" type="integer">
  Total number of clicks on this date
</ResponseField>

<ResponseField name="unique_visitors" type="integer">
  Number of unique visitors on this date
</ResponseField>

<ResponseField name="scans_only" type="integer">
  Number of QR code scans without clicks on this date
</ResponseField>

<ResponseField name="clicks_only" type="integer">
  Number of direct clicks without scans on this date
</ResponseField>

<ResponseField name="chrome_clicks" type="integer">
  Number of clicks from Chrome browser on this date
</ResponseField>

<ResponseField name="ios_clicks" type="integer">
  Number of clicks from iOS devices on this date
</ResponseField>

<ResponseField name="android_clicks" type="integer">
  Number of clicks from Android devices on this date
</ResponseField>

<ResponseField name="os_stats" type="object">
  Statistics broken down by operating system

  <Expandable title="Operating system statistics">
    <ResponseField name="{os_name}" type="integer">
      Number of clicks from this operating system (OS name as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="city_stats" type="object">
  Statistics broken down by city

  <Expandable title="City statistics">
    <ResponseField name="{city_name}" type="integer">
      Number of clicks from this city (city name as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="os_version_stats" type="object">
  Statistics broken down by operating system version

  <Expandable title="OS version statistics">
    <ResponseField name="{version}" type="integer">
      Number of clicks from this OS version (version as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="lang_stats" type="object">
  Statistics broken down by language

  <Expandable title="Language statistics">
    <ResponseField name="{language_code}" type="integer">
      Number of clicks from this language (language code as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="device_stats" type="object">
  Statistics broken down by device type

  <Expandable title="Device statistics">
    <ResponseField name="mobile" type="integer">
      Number of clicks from mobile devices
    </ResponseField>

    <ResponseField name="desktop" type="integer">
      Number of clicks from desktop devices
    </ResponseField>

    <ResponseField name="tablet" type="integer">
      Number of clicks from tablet devices
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="browser_stats" type="object">
  Statistics broken down by browser

  <Expandable title="Browser statistics">
    <ResponseField name="{browser_name}" type="integer">
      Number of clicks from this browser (browser name as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="country_stats" type="object">
  Statistics broken down by country

  <Expandable title="Country statistics">
    <ResponseField name="{country_code}" type="integer">
      Number of clicks from this country (country code as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="device_and_os_stats" type="object">
  Statistics broken down by device and operating system combination

  <Expandable title="Device and OS statistics">
    <ResponseField name="{device_os}" type="integer">
      Number of clicks from this device-OS combination (device-OS as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="app_stats" type="object">
  Statistics broken down by application

  <Expandable title="Application statistics">
    <ResponseField name="{app_name}" type="integer">
      Number of clicks from this application (app name as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="device_type_stats" type="object">
  Statistics broken down by device type (detailed)

  <Expandable title="Device type statistics">
    <ResponseField name="{device_type}" type="integer">
      Number of clicks from this device type (device type as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="from_app_stats" type="object">
  Statistics showing clicks from apps vs web browsers

  <Expandable title="App vs web statistics">
    <ResponseField name="true" type="integer">
      Number of clicks from mobile applications
    </ResponseField>

    <ResponseField name="false" type="integer">
      Number of clicks from web browsers
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="continent_stats" type="object">
  Statistics broken down by continent

  <Expandable title="Continent statistics">
    <ResponseField name="{continent_name}" type="integer">
      Number of clicks from this continent (continent name as key)
    </ResponseField>
  </Expandable>
</ResponseField>


# Link Stats Summary
Source: https://docs.taap.it/api-reference/stats/link-summary

GET https://api.taap.it/v1/stats/links/{link_id}/summary
Get aggregated statistics for a link

**Request:**

```bash cURL theme={null}
curl -X GET 'https://api.taap.it/v1/stats/links/link_987654321/summary?start_date=2024-01-01&end_date=2024-01-31' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "link_id": "link_987654321",
  "total_clicks": 1250,
  "top_countries": [
    {"name": "US", "count": 650},
    {"name": "CA", "count": 280},
    {"name": "UK", "count": 180}
  ],
  "top_devices": [
    {"name": "mobile", "count": 750},
    {"name": "desktop", "count": 400},
    {"name": "tablet", "count": 100}
  ],
  "top_browsers": [
    {"name": "Chrome", "count": 800},
    {"name": "Safari", "count": 300},
    {"name": "Firefox", "count": 100}
  ],
  "qr_code_usage": 45,
  "date_range": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  }
}
```

## Authorization

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

## Path Parameters

<ParamField type="string">
  Unique identifier for the link
</ParamField>

## Query Parameters

<ParamField type="string">
  Start date for statistics (YYYY-MM-DD format)
</ParamField>

<ParamField type="string">
  End date for statistics (YYYY-MM-DD format)
</ParamField>

## Response Fields

<ResponseField name="link_id" type="string">
  Unique identifier for the link
</ResponseField>

<ResponseField name="total_clicks" type="integer">
  Total number of clicks on the link
</ResponseField>

<ResponseField name="top_countries" type="array">
  Array of top countries by click count

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

    <ResponseField name="count" type="integer">
      Number of clicks from this country
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="top_devices" type="array">
  Array of top devices by click count

  <Expandable title="Device object properties">
    <ResponseField name="name" type="string">
      Device type (mobile, desktop, tablet)
    </ResponseField>

    <ResponseField name="count" type="integer">
      Number of clicks from this device type
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="top_browsers" type="array">
  Array of top browsers by click count

  <Expandable title="Browser object properties">
    <ResponseField name="name" type="string">
      Browser name (Chrome, Safari, Firefox, etc.)
    </ResponseField>

    <ResponseField name="count" type="integer">
      Number of clicks from this browser
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="qr_code_usage" type="integer">
  Number of times the QR code was scanned
</ResponseField>

<ResponseField name="date_range" type="object">
  Date range for the statistics

  <Expandable title="Date range properties">
    <ResponseField name="start" type="string">
      Start date of the statistics period
    </ResponseField>

    <ResponseField name="end" type="string">
      End date of the statistics period
    </ResponseField>
  </Expandable>
</ResponseField>


# Workspace Statistics
Source: https://docs.taap.it/api-reference/stats/workspace-stats

GET https://api.taap.it/v1/stats/workspaces
Retrieve detailed statistics for your workspace

**Request:**

```bash cURL theme={null}
curl -X GET 'https://api.taap.it/v1/stats/workspaces?start_date=2024-01-01T00:00:00Z&end_date=2024-01-31T23:59:59Z&max_days=30' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
[
  {
    "id": "ws_stat_123456789",
    "last_updated": "2024-01-15T10:30:00Z",
    "click_date": "2024-01-15",
    "total_clicks": 1250,
    "unique_visitors": 980,
    "scans_only": 50,
    "clicks_only": 1200,
    "chrome_clicks": 800,
    "ios_clicks": 400,
    "android_clicks": 200,
    "os_stats": {
      "iOS": 400,
      "Android": 200,
      "Windows": 500,
      "macOS": 150
    },
    "city_stats": {
      "New York": 200,
      "Los Angeles": 150,
      "Toronto": 100,
      "London": 80
    },
    "os_version_stats": {
      "iOS 17.0": 300,
      "iOS 16.5": 100,
      "Android 13": 120,
      "Android 12": 80
    },
    "lang_stats": {
      "en": 900,
      "fr": 150,
      "es": 100,
      "de": 50
    },
    "device_stats": {
      "mobile": 750,
      "desktop": 400,
      "tablet": 100
    },
    "browser_stats": {
      "Chrome": 800,
      "Safari": 300,
      "Firefox": 100,
      "Edge": 50
    },
    "country_stats": {
      "US": 650,
      "CA": 280,
      "UK": 180,
      "DE": 80
    },
    "device_and_os_stats": {
      "iPhone iOS": 400,
      "Android Phone": 200,
      "Windows Desktop": 500,
      "Mac Desktop": 150
    },
    "app_stats": {
      "Safari": 300,
      "Chrome Mobile": 400,
      "Chrome Desktop": 400
    },
    "device_type_stats": {
      "smartphone": 600,
      "desktop": 500,
      "tablet": 150
    },
    "from_app_stats": {
      "true": 300,
      "false": 950
    },
    "continent_stats": {
      "North America": 930,
      "Europe": 200,
      "Asia": 100,
      "Oceania": 20
    }
  }
]
```

## Authorization

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

## Query Parameters

<ParamField type="string">
  Start date for statistics (ISO 8601 format, e.g., 2024-01-01T00:00:00Z)
</ParamField>

<ParamField type="string">
  End date for statistics (ISO 8601 format, e.g., 2024-01-31T23:59:59Z)
</ParamField>

<ParamField type="integer">
  Maximum number of days to retrieve statistics for (minimum: 1, maximum: 30)
</ParamField>

## Response Fields

<ResponseField name="id" type="string">
  Unique identifier for the statistics record
</ResponseField>

<ResponseField name="last_updated" type="string">
  ISO 8601 timestamp when the statistics were last updated
</ResponseField>

<ResponseField name="click_date" type="string">
  Date for the statistics (YYYY-MM-DD format)
</ResponseField>

<ResponseField name="total_clicks" type="integer">
  Total number of clicks across all workspace links on this date
</ResponseField>

<ResponseField name="unique_visitors" type="integer">
  Number of unique visitors across all workspace links on this date
</ResponseField>

<ResponseField name="scans_only" type="integer">
  Number of QR code scans without clicks across all workspace links on this date
</ResponseField>

<ResponseField name="clicks_only" type="integer">
  Number of direct clicks without scans across all workspace links on this date
</ResponseField>

<ResponseField name="chrome_clicks" type="integer">
  Number of clicks from Chrome browser across all workspace links on this date
</ResponseField>

<ResponseField name="ios_clicks" type="integer">
  Number of clicks from iOS devices across all workspace links on this date
</ResponseField>

<ResponseField name="android_clicks" type="integer">
  Number of clicks from Android devices across all workspace links on this date
</ResponseField>

<ResponseField name="os_stats" type="object">
  Statistics broken down by operating system across all workspace links

  <Expandable title="Operating system statistics">
    <ResponseField name="{os_name}" type="integer">
      Number of clicks from this operating system (OS name as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="city_stats" type="object">
  Statistics broken down by city across all workspace links

  <Expandable title="City statistics">
    <ResponseField name="{city_name}" type="integer">
      Number of clicks from this city (city name as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="os_version_stats" type="object">
  Statistics broken down by operating system version across all workspace links

  <Expandable title="OS version statistics">
    <ResponseField name="{version}" type="integer">
      Number of clicks from this OS version (version as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="lang_stats" type="object">
  Statistics broken down by language across all workspace links

  <Expandable title="Language statistics">
    <ResponseField name="lang_stats.{language_code}" type="integer">
      Number of clicks from this language (language code as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="device_stats" type="object">
  Statistics broken down by device type across all workspace links

  <Expandable title="Device statistics">
    <ResponseField name="mobile" type="integer">
      Number of clicks from mobile devices
    </ResponseField>

    <ResponseField name="desktop" type="integer">
      Number of clicks from desktop devices
    </ResponseField>

    <ResponseField name="tablet" type="integer">
      Number of clicks from tablet devices
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="browser_stats" type="object">
  Statistics broken down by browser across all workspace links

  <Expandable title="Browser statistics">
    <ResponseField name="{browser_name}" type="integer">
      Number of clicks from this browser (browser name as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="country_stats" type="object">
  Statistics broken down by country across all workspace links

  <Expandable title="Country statistics">
    <ResponseField name="{country_code}" type="integer">
      Number of clicks from this country (country code as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="device_and_os_stats" type="object">
  Statistics broken down by device and operating system combination across all workspace links

  <Expandable title="Device and OS statistics">
    <ResponseField name="{device_os}" type="integer">
      Number of clicks from this device-OS combination (device-OS as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="app_stats" type="object">
  Statistics broken down by application across all workspace links

  <Expandable title="Application statistics">
    <ResponseField name="{app_name}" type="integer">
      Number of clicks from this application (app name as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="device_type_stats" type="object">
  Statistics broken down by device type (detailed) across all workspace links

  <Expandable title="Device type statistics">
    <ResponseField name="{device_type}" type="integer">
      Number of clicks from this device type (device type as key)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="from_app_stats" type="object">
  Statistics showing clicks from apps vs web browsers across all workspace links

  <Expandable title="App vs web statistics">
    <ResponseField name="true" type="integer">
      Number of clicks from mobile applications
    </ResponseField>

    <ResponseField name="false" type="integer">
      Number of clicks from web browsers
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="continent_stats" type="object">
  Statistics broken down by continent across all workspace links

  <Expandable title="Continent statistics">
    <ResponseField name="{continent_name}" type="integer">
      Number of clicks from this continent (continent name as key)
    </ResponseField>
  </Expandable>
</ResponseField>


# Workspace Stats Summary
Source: https://docs.taap.it/api-reference/stats/workspace-summary

GET https://api.taap.it/v1/stats/workspaces/summary
Get aggregated statistics for your workspace

**Request:**

```bash cURL theme={null}
curl -X GET 'https://api.taap.it/v1/stats/workspaces/summary?start_date=2024-01-01&end_date=2024-01-31' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

**Response:**

```json theme={null}
{
  "total_clicks": 15750,
  "top_countries": [
    {"name": "US", "count": 8250},
    {"name": "CA", "count": 3150},
    {"name": "UK", "count": 2250}
  ],
  "top_devices": [
    {"name": "mobile", "count": 9450},
    {"name": "desktop", "count": 5250},
    {"name": "tablet", "count": 1050}
  ],
  "top_browsers": [
    {"name": "Chrome", "count": 10000},
    {"name": "Safari", "count": 3750},
    {"name": "Firefox", "count": 1500}
  ],
  "qr_code_usage": 525,
  "date_range": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  }
}
```

## Authorization

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

## Query Parameters

<ParamField type="string">
  Start date for statistics (YYYY-MM-DD format)
</ParamField>

<ParamField type="string">
  End date for statistics (YYYY-MM-DD format)
</ParamField>

## Response Fields

<ResponseField name="total_clicks" type="integer">
  Total number of clicks across all links in the workspace
</ResponseField>

<ResponseField name="top_countries" type="array">
  Array of top countries by click count across all workspace links

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

    <ResponseField name="count" type="integer">
      Number of clicks from this country
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="top_devices" type="array">
  Array of top devices by click count across all workspace links

  <Expandable title="Device object properties">
    <ResponseField name="name" type="string">
      Device type (mobile, desktop, tablet)
    </ResponseField>

    <ResponseField name="count" type="integer">
      Number of clicks from this device type
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="top_browsers" type="array">
  Array of top browsers by click count across all workspace links

  <Expandable title="Browser object properties">
    <ResponseField name="name" type="string">
      Browser name (Chrome, Safari, Firefox, etc.)
    </ResponseField>

    <ResponseField name="count" type="integer">
      Number of clicks from this browser
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="qr_code_usage" type="integer">
  Total number of QR code scans across all workspace links
</ResponseField>

<ResponseField name="date_range" type="object">
  Date range for the statistics

  <Expandable title="Date range properties">
    <ResponseField name="start" type="string">
      Start date of the statistics period
    </ResponseField>

    <ResponseField name="end" type="string">
      End date of the statistics period
    </ResponseField>
  </Expandable>
</ResponseField>


# Authentication
Source: https://docs.taap.it/authentication

Learn how to authenticate with the taap.it API using API keys

The taap.it API uses API key-based authentication to secure access to your account and resources. All API requests must include a valid API key in the Authorization header.

## API Key Overview

API keys provide secure access to your taap.it account and are created through the web application dashboard. Each API key is:

* **User-specific**: Tied to your user account
* **Scoped**: Can have full access, read-only access, or limited permissions
* **Secure**: Prefixed with `taapit_` and cryptographically generated

## Creating API Keys

<Steps>
  <Step title="Access API Settings">
    Log into your taap.it dashboard and navigate to your user settings.
  </Step>

  <Step title="Generate New Key">
    In the "API Keys" section, click "Create API Key" and provide a descriptive name.
  </Step>

  <Step title="Set Permissions">
    Choose the appropriate permission level for your use case:

    * **Full Access**: Complete read/write access to all resources
    * **Read Only**: View-only access to all resources
    * **Limited Access**: Custom permissions for specific resources
  </Step>

  <Step title="Store Securely">
    Copy the generated API key immediately and store it securely.

    <Warning>
      API keys are only displayed once during creation. If lost, you'll need to generate a new key.
    </Warning>
  </Step>
</Steps>

## Using API Keys

Include your API key in the Authorization header using the Bearer token format:

```http theme={null}
Authorization: Bearer taapit_your_api_key_here
```

### Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://api.taap.it/v1/workspaces' \
    -H 'Authorization: Bearer taapit_abc123def456ghi789' \
    -H 'Content-Type: application/json'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.taap.it/v1/workspaces', {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  });
  ```

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

  headers = {
      'Authorization': f'Bearer {api_key}',
      'Content-Type': 'application/json'
  }

  response = requests.get('https://api.taap.it/v1/workspaces', headers=headers)
  ```

  ```php PHP theme={null}
  <?php
  $headers = [
      'Authorization: Bearer ' . $api_key,
      'Content-Type: application/json'
  ];

  $response = file_get_contents('https://api.taap.it/v1/workspaces', false, 
      stream_context_create(['http' => ['header' => implode("\r\n", $headers)]])
  );
  ?>
  ```
</CodeGroup>

## Permission Levels

API keys can have different permission levels that control access to resources:

### Full Access

<Check>
  Grants complete read and write access to all resources and endpoints.
</Check>

* **Use case**: Server-to-server integrations, administrative tools
* **Permissions**: All read and write operations
* **Security**: High - monitor usage carefully

### Read Only

<Info>
  Provides view-only access to all resources without modification capabilities.
</Info>

* **Use case**: Analytics dashboards, reporting tools
* **Permissions**: GET operations only
* **Security**: Medium - data exposure limited to viewing

### Limited Access

<Tip>
  Custom permissions allow granular control over specific resources and operations.
</Tip>

* **Use case**: Third-party integrations with specific needs
* **Permissions**: Configurable per resource (domains, links, projects, workspaces, analytics)
* **Security**: High - minimal necessary permissions

## Security Best Practices

<AccordionGroup>
  <Accordion title="Key Storage">
    * Store API keys in environment variables, not in code
    * Use secure key management services for production
    * Never commit API keys to version control
    * Rotate keys regularly for enhanced security
  </Accordion>

  <Accordion title="Access Control">
    * Use the principle of least privilege
    * Create separate keys for different environments
    * Monitor API key usage and set up alerts
    * Deactivate unused or compromised keys immediately
  </Accordion>

  <Accordion title="Network Security">
    * Always use HTTPS for API requests
    * Implement proper error handling
    * Use IP whitelisting when possible
    * Monitor for suspicious activity
  </Accordion>
</AccordionGroup>

## Error Handling

### Authentication Errors

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "detail": "Invalid API key"
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "detail": "Insufficient permissions for this operation"
  }
  ```
</ResponseExample>

### Common Authentication Issues

<AccordionGroup>
  <Accordion title="Invalid API Key">
    * Verify the key is copied correctly
    * Check that the key hasn't been deactivated
    * Ensure you're using the full key including the `taapit_` prefix
  </Accordion>

  <Accordion title="Permission Denied">
    * Check if your API key has the required permissions
    * Verify you're trying to access resources you own
    * Consider upgrading to a key with full access
  </Accordion>

  <Accordion title="Rate Limiting">
    * Monitor your request frequency
    * Implement exponential backoff
    * Check the rate limit headers in responses
  </Accordion>
</AccordionGroup>

## Migration Guide

If you're migrating from another authentication method or upgrading your integration:

<Steps>
  <Step title="Create New API Key">
    Generate a new API key with appropriate permissions for your use case.
  </Step>

  <Step title="Test Integration">
    Update your application to use the new API key and test thoroughly.
  </Step>

  <Step title="Deactivate Old Key">
    Once confirmed working, deactivate any old authentication credentials.
  </Step>
</Steps>

<Card title="Ready to authenticate?" icon="key" href="/quickstart">
  Follow our quickstart guide to make your first authenticated API call.
</Card>


# Shopify
Source: https://docs.taap.it/conversions/automatic/shopify

Automatic conversion tracking for Shopify stores — add a script tag and configure webhooks

The Taapit Shopify integration provides **fully automatic** conversion tracking with no app to install. Add one script tag to your theme, configure three webhooks, and every checkout and order is automatically attributed to your Taapit links.

## How it works

<Frame>
  <img alt="Taapit Shopify integration" />
</Frame>

## Features

* ✅ **No app required** – Just a script tag and webhooks
* ✅ **Automatic tracking** – Every checkout and order is tracked
* ✅ **Full attribution** – Works across sessions (90-day cookie)
* ✅ **Real-time sync** – Events appear instantly
* ✅ **Multi-currency** – Supports all Shopify currencies

## Prerequisites

<Warning>
  **Important**: For conversion tracking to work, users must arrive on your
  store via a **Taapit deeplink**. This is how the tracking ID (`ta_tid`) is
  generated and passed to your store.
</Warning>

<Warning>
  **Hide the "Buy Now" button**: The Buy Now (accelerated checkout) button
  bypasses the cart and goes directly to payment — this flow **cannot be
  tracked**. You must disable it in your theme so all customers go through the
  standard Add to Cart → Checkout flow.

  To hide it: open your theme editor → select a product page section → find
  **Dynamic checkout buttons** and uncheck it, then save.
</Warning>

Before you start:

1. **Create a Taapit deeplink** pointing to your Shopify store or a product page
2. **Enable conversion tracking** on your link in the Taapit dashboard

## Installation

<Steps>
  <Step title="Add the script tag to theme.liquid">
    Copy this script tag:

    ```html theme={null}
    <script
      defer
      src="https://taap.it/api/shopify/script"
    ></script>
    ```

    Then add it to your theme:

    1. In Shopify Admin, go to **Online Store** → **Themes**
    2. Click **Customize** → **Edit code** on your active theme
    3. Open the **theme.liquid** file
    4. Paste the script just before the `</head>` closing tag, then save

    The script captures the `ta_tid` tracking ID from Taapit links and stores it in a cookie and localStorage for 90 days. It also attaches the tracking ID to cart attributes so it survives through to the order.
  </Step>

  <Step title="Configure Webhooks">
    You need to create **3 webhooks** in Shopify pointing to your Taapit webhook URL.

    Your webhook URL (found in your Taapit dashboard under Settings → Analytics → Shopify):

    ```
    https://track.taap.it/api/shopify/webhook?workspaceId=YOUR_WORKSPACE_ID
    ```

    **Steps to configure in Shopify:**

    1. In Shopify Admin, go to **Settings** → **Notifications**
    2. Scroll down to the **Webhooks** section and click **Create webhook**
    3. Choose an event: **Order payment** → paste the webhook URL → save
    4. Repeat for **Checkout creation**
    5. Repeat for **Checkout update**

    <Warning>
      You must create **3 separate webhooks** with the same URL:

      * `orders/paid` → tracks a **Sale** event
      * `checkouts/create` → tracks a **Lead** event
      * `checkouts/update` → updates the Lead if the cart changes

      Your workspace ID is already included in the URL shown in your dashboard.
    </Warning>
  </Step>

  <Step title="Verify the setup">
    1. Visit your store from a Taapit link (you should see `?ta_tid=xxx` in the URL)
    2. Check browser DevTools → Application → Cookies for `ta_tid`
    3. Add a product to the cart and proceed to checkout
    4. Check the **Analytics** tab in Taapit — a Lead event should appear
    5. Complete a test order — a Sale event should appear
  </Step>
</Steps>

## How Tracking Works

1. **Visitor arrives** via Taapit link with `?ta_tid=xxx`
2. **Script captures** the `ta_tid` and stores it in a cookie and localStorage
3. **Script adds** the tracking ID to cart attributes (persists through checkout)
4. **Customer clicks Checkout** — the tracking ID is forwarded via cart attributes
5. **Order webhook** sends order details + tracking ID to Taapit
6. **Conversion recorded** and attributed to the original link

<Warning>
  This flow only works if the customer goes through the **standard cart checkout**.
  The Buy Now (accelerated checkout) button bypasses the cart, so the tracking
  ID is never attached. Make sure to disable it in your theme.
</Warning>

## Tracked Events

| Shopify Event      | Taapit Event | When                     |
| ------------------ | ------------ | ------------------------ |
| `checkouts/create` | Lead         | Customer starts checkout |
| `checkouts/update` | Lead update  | Cart is modified         |
| `orders/paid`      | Sale         | Order is paid            |

## Troubleshooting

<AccordionGroup>
  <Accordion title="The ta_tid cookie is not set">
    Make sure you are visiting the store from a Taapit link that contains `?ta_tid=xxx` in the URL. The script only sets the cookie when this parameter is present.
  </Accordion>

  <Accordion title="Conversions not appearing">
    1. Check that the script tag is present in your theme.liquid (before `</head>`)
    2. Check that all 3 webhooks are correctly configured with your workspace ID
    3. Check that the Buy Now button is hidden — orders placed through it cannot be tracked
    4. Verify the `ta_tid` cookie is set in your browser DevTools
  </Accordion>

  <Accordion title="Theme compatibility">
    Works with all Shopify themes that allow editing theme.liquid. For headless setups (Hydrogen, custom storefronts), use the [Manual Client-side Integration](/conversions/manual/client-side) instead.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Stripe Integration" icon="stripe" href="/conversions/automatic/stripe">
    Also using Stripe? Add the Stripe integration.
  </Card>

  <Card title="Create Your First Link" icon="link" href="/links/create">
    Create a Taapit link to start tracking.
  </Card>
</CardGroup>


# Stripe
Source: https://docs.taap.it/conversions/automatic/stripe

Automatic conversion tracking for Stripe payments

The Taapit Stripe integration automatically tracks all your Stripe payments as sales conversions. Just install the SDK, connect the app, and pass the tracking ID to Stripe.

## How it works

<Frame>
  <img alt="Taapit Visual Stripe integration" />
</Frame>

## Prerequisites

<Warning>
  **Important**: For conversion tracking to work, users must arrive on your
  website via a **Taapit deeplink**. This is how the tracking ID (`ta_tid`) is
  generated and passed to your site.
</Warning>

Before you start:

1. **Create a Taapit deeplink** pointing to your website or landing page
2. **Enable conversion tracking** on your link:
   * Go to your link settings in the Taapit dashboard
   * Enable **Conversion Tracking**
3. **Configure Stripe integration** in [Settings → Conversion](https://taap.it/dashboard/settings/conversion) and select **Stripe Integration**

```mermaid theme={null}
flowchart LR
    A[User clicks Taapit link] --> B[Lands on your site with ta_tid]
    B --> C[SDK stores ta_tid in cookie]
    C --> D[User makes purchase]
    D --> E[ta_tid sent to Stripe]
    E --> F[Taapit tracks conversion]
```

## Installation

<Steps>
  <Step title="Install the Taapit SDK on your website">
    First, add the Taapit SDK to your website to capture the `ta_tid` tracking ID:

    <Tabs>
      <Tab title="NPM Package (React/Next.js)">
        ```bash theme={null}
        npm install taapit-sdk
        ```

        Then add the Analytics component to your root layout:

        ```tsx app/layout.tsx theme={null}
        import { Analytics } from 'taapit-sdk/react';

        export default function RootLayout({ children }) {
          return (
            <html>
              <body>
                {children}
                <Analytics />
              </body>
            </html>
          );
        }
        ```
      </Tab>

      <Tab title="Script Tag (No Build Step)">
        Add this script to your HTML `<head>` or before `</body>`:

        ```html theme={null}
        <script src="https://taap.it/api/sdk"></script>
        ```
      </Tab>
    </Tabs>

    <Warning>
      This step is **required**. Without the SDK, the `ta_tid` won't be captured and conversions can't be tracked.
    </Warning>
  </Step>

  <Step title="Install the Stripe App">
    1. Go to the [Stripe App Marketplace](https://marketplace.stripe.com/)
    2. Search for "Taapit Conversion"
    3. Click **Install**

    Or install directly from your Taapit dashboard:

    1. Go to **Settings** → **Integrations** → **Stripe**
    2. Click **Install Stripe Integration**
  </Step>

  <Step title="Connect your Taapit workspace">
    After installing the app in Stripe:

    **1. Open the Taapit app in your Stripe dashboard and click "Connect workspace"**

    <Frame>
      <img alt="Taapit Stripe App - Connect workspace button" />
    </Frame>

    **2. Authorize the connection to your Taapit workspace**

    You will be redirected to the Taapit consent page. Select the workspace you want to connect and click **Authorize**.

    <Frame>
      <img alt="Taapit consent page" />
    </Frame>

    **3. Verify the workspace is connected**

    Once authorized, you will see your workspace connected in the Stripe app.

    <Frame>
      <img alt="Taapit Stripe App - Workspace connected" />
    </Frame>
  </Step>

  <Step title="Pass the tracking ID to Stripe">
    Pass the `ta_tid` to Stripe when creating customers, checkout sessions, or payment intents.

    ### 1. Frontend: Get the tracking ID

    First, retrieve the tracking ID from your frontend to pass it to your API:

    <Tabs>
      <Tab title="With Taapit SDK">
        ```typescript theme={null}
        // Using the taapit global object (script tag)
        const trackingId = taapit.getTrackingId();
        ```
      </Tab>

      <Tab title="With React Hook">
        ```tsx theme={null}
        import { useTaapitAnalytics } from 'taapit-sdk/react';

        function CheckoutButton() {
          const { trackingId } = useTaapitAnalytics();

          const handleCheckout = async () => {
            const response = await fetch('/api/create-checkout', {
              method: 'POST',
              headers: { 'Content-Type': 'application/json' },
              body: JSON.stringify({
                priceId: 'price_xxx',
                trackingId,
              }),
            });
            const { url } = await response.json();
            window.location.href = url;
          };

          return <button onClick={handleCheckout}>Subscribe</button>;
        }
        ```
      </Tab>

      <Tab title="From Cookie directly">
        ```typescript theme={null}
        // Read directly from cookie
        const trackingId = document.cookie
          .split('; ')
          .find(row => row.startsWith('ta_tid='))
          ?.split('=')[1];
        ```
      </Tab>
    </Tabs>

    <Info>
      The tracking ID can be retrieved from:

      1. **Taapit SDK** - `taapit.getTrackingId()` or `useTaapitAnalytics()` hook
      2. **Cookie** (`ta_tid`) - automatically set by the SDK

      The backend should check both the request body and cookies for maximum compatibility.
    </Info>

    ***

    ### 2. Track Sales: Create a Checkout Session

    When a user makes a purchase, pass the tracking ID in the checkout session metadata.

    <Info>
      **When is `taapitTrackingId` required for Checkout Sessions?**

      * If the customer was **already tracked via a lead event** (using `taapitCustomerExternalId`), the `taapitTrackingId` is **optional** - you only need to pass `taapitCustomerExternalId` to link the sale.
      * If this is a **new customer** (no prior lead), `taapitTrackingId` is **required** to attribute the sale.
    </Info>

    ```typescript app/api/create-checkout/route.ts theme={null}
    import { NextRequest } from 'next/server';
    import Stripe from 'stripe';

    const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

    export async function POST(request: NextRequest) {
      const body = await request.json();
      const { priceId, customerExternalId } = body;

      // Get tracking ID from cookie OR from request body
      // Optional if customer already tracked via lead
      const trackingId =
        request.cookies.get('ta_tid')?.value ||
        body.trackingId ||
        '';

      const session = await stripe.checkout.sessions.create({
        mode: 'subscription',
        line_items: [{ price: priceId, quantity: 1 }],
        success_url: 'https://yoursite.com/success',
        cancel_url: 'https://yoursite.com/cancel',
        // Pass tracking ID and customer ID in metadata
        metadata: {
          taapitTrackingId: trackingId, // Optional if customer exists
          taapitCustomerExternalId: customerExternalId, // Required
        },
        // Also in subscription_data for subscriptions
        subscription_data: {
          metadata: {
            taapitTrackingId: trackingId,
            taapitCustomerExternalId: customerExternalId,
          },
        },
      });

      return Response.json({ url: session.url });
    }
    ```

    ***

    ### 3. (Optional) Track Leads: Create a Stripe Customer

    If you want to track leads separately from sales, create a Stripe customer with the tracking ID when a user signs up. Taapit listens to the `customer.created` webhook.

    ```typescript app/api/stripe/create-customer/route.ts theme={null}
    import { NextRequest } from 'next/server';
    import Stripe from 'stripe';

    const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

    export async function POST(request: NextRequest) {
      const body = await request.json();
      const { email, name, externalId } = body;

      // Get tracking ID from cookie OR from request body
      const trackingId =
        request.cookies.get('ta_tid')?.value ||
        body.trackingId ||
        '';

      // Create Stripe customer with Taapit metadata
      const customer = await stripe.customers.create({
        email,
        name,
        metadata: {
          taapitTrackingId: trackingId,
          taapitCustomerExternalId: externalId, // Your internal user ID
        },
      });

      return Response.json({ customerId: customer.id });
    }
    ```

    <Info>
      This step is **optional**. Use it if you want to track user signups as leads before they make a purchase.
    </Info>

    ***

    ### 4. (Alternative) Using Stripe Payment Links

    If you're using [Stripe Payment Links](https://stripe.com/docs/payment-links), you can track sales automatically without writing any backend code.

    <Warning>
      With Payment Links, only **sale events** are tracked. Lead webhooks are not created.
    </Warning>

    **How to set it up:**

    1. Get your Stripe Payment Link URL (e.g., `https://buy.stripe.com/xxx`)
    2. Add `?taapit_client_reference_id=1` to the URL:
       ```
       https://buy.stripe.com/xxx?taapit_client_reference_id=1
       ```
    3. Shorten this URL with Taapit

    **How it works:**

    When a user clicks on your Taapit deeplink, Taapit automatically:

    1. Replaces `taapit_client_reference_id=1` with `client_reference_id=taapit_tid_{trackingId}`
    2. Stripe receives the tracking ID as `client_reference_id`
    3. When checkout completes, Taapit attributes the sale to the original click
  </Step>

  <Step title="Verify the connection">
    1. Go to **Settings** → **Integrations** → **Stripe** in Taapit
    2. You should see **Connected** status
    3. Make a test payment
    4. Check the **Analytics** tab for the conversion
  </Step>
</Steps>

## Tracked Events

The Stripe integration automatically tracks these events:

| Stripe Event                 | Taapit Event | Description                             |
| ---------------------------- | ------------ | --------------------------------------- |
| `customer.created`           | Lead         | Customer created with tracking metadata |
| `checkout.session.completed` | Sale         | Checkout session completed              |
| `invoice.paid`               | Sale         | Subscription invoice paid               |

## Metadata Fields

The integration looks for these metadata fields on Stripe objects:

| Field                      | Required  | Description                                |
| -------------------------- | --------- | ------------------------------------------ |
| `taapitTrackingId`         | See below | The tracking ID (`ta_tid` from the cookie) |
| `taapitCustomerExternalId` | Yes       | Your internal user ID                      |

<Info>
  Use `taapitTrackingId` (not `ta_tid`) in Stripe metadata. The `ta_tid` is the
  cookie name, while `taapitTrackingId` is the metadata field name.
</Info>

<Info>
  **When is `taapitTrackingId` required?** - **Lead events**
  (`customer.created`): `taapitTrackingId` is **always required** - **Sale
  events** (`checkout.session.completed`, `invoice.paid`): - If the customer was
  **already tracked via a lead event** (using `taapitCustomerExternalId`), the
  `taapitTrackingId` is **optional** - you only need the
  `taapitCustomerExternalId` - If this is a **new customer** (no prior lead),
  `taapitTrackingId` is **required** to attribute the sale
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Conversions not appearing">
    1. **Check metadata**: Ensure `taapitTrackingId` is in your Stripe metadata
    2. **Verify webhook delivery**: In Stripe → Developers → Webhooks 3. **Check
       connection**: Settings → Integrations → Stripe should show "Connected"
  </Accordion>

  <Accordion title="Tracking ID missing">
    If the tracking ID is empty, the user either: - Didn't come from a Taapit
    link - Has cookies blocked - Cookie wasn't passed to checkout This is normal
    for organic/direct traffic.
  </Accordion>
</AccordionGroup>

## Security

| Permission              | Purpose                        |
| ----------------------- | ------------------------------ |
| `customer_read`         | Read customer information      |
| `subscription_read`     | Read subscription data         |
| `invoice_read`          | Read invoice amounts           |
| `checkout_session_read` | Read checkout session metadata |
| `webhook_read`          | Receive payment events         |

## FAQ

<AccordionGroup>
  <Accordion title="Do I need to install the SDK?">
    Yes, you need the Taapit SDK on your website to capture the `ta_tid` cookie.
    The Stripe app only handles payment tracking.
  </Accordion>

  <Accordion title="How are subscription renewals handled?">
    Each `invoice.paid` event triggers a sale. The tracking ID from the original
    checkout is used for attribution.
  </Accordion>

  <Accordion title="What about refunds?">
    Currently, refunds are not automatically tracked. We're working on this
    feature.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Shopify Integration" icon="shopify" href="/conversions/automatic/shopify">
    Set up automatic tracking for Shopify stores.
  </Card>

  <Card title="Manual Integration" icon="code" href="/conversions/manual/server-side">
    For custom payment flows.
  </Card>
</CardGroup>


# How Conversions Work
Source: https://docs.taap.it/conversions/how-conversions-work

Understand the conversion tracking flow from click to conversion

Taapit Conversion Tracking enables you to attribute leads and sales to the deeplinks that drove them. This allows you to measure the true ROI of your marketing campaigns.

## The Conversion Flow

<Frame>
  <img alt="Taapit Visual manual integration" />
</Frame>

## Key Concepts

### 1. Tracking ID (`ta_tid`)

When a user clicks on a Taapit deeplink, we generate a unique tracking ID and append it to your destination URL:

```
https://yoursite.com/landing?ta_tid=rLnWe1uz9t282v7g
```

This ID links the click to any future conversions. It's:

* **Unique per click** – Each click gets its own ID
* **Persistent** – Stored in a cookie
* **Privacy-friendly** – Contains no personal information

<Info>Learn more about [the tracking ID](/conversions/tracking-id).</Info>

### 2. Lead Events

A **lead** is a potential customer who has shown interest. Examples:

* User signs up for an account
* User submits a contact form
* User starts a free trial
* User subscribes to a newsletter

Lead tracking requires:

* `trackingId` – The `ta_tid` from the cookie
* `customer.externalId` – Your internal user ID

### 3. Sale Events

A **sale** is a completed transaction. Examples:

* One-time purchase
* Subscription payment
* Upgrade to paid plan
* In-app purchase

Sale tracking requires:

* `trackingId` – The `ta_tid` from the cookie
* `customer.externalId` – Your internal user ID
* `amount` – Transaction amount in currency units (e.g., 29.99)
* `currency` – ISO 4217 currency code (e.g., `eur`, `usd`)

### 4. Customer Object

Both lead and sale events include a customer object to identify the user:

```json theme={null}
{
  "customer": {
    "externalId": "user_123", // Required: Your internal user ID
    "email": "john@example.com", // Optional: User's email
    "firstname": "John", // Optional: First name
    "lastname": "Doe", // Optional: Last name
    "phoneNumber": "+33612345678", // Optional: Phone number
    "avatarUrl": "https://..." // Optional: Avatar URL
  }
}
```

<Warning>
  The `externalId` is required and should be your internal user ID. This is used
  to deduplicate conversions and track customer lifetime value.
</Warning>

## Attribution Model

Taapit uses **last-click attribution**:

* If a user clicks multiple Taapit links before converting, the conversion is attributed to the **most recent click**
* The cookie window ensures long sales cycles are captured
* Each new click updates the tracking ID

## Conversion Types Comparison

| Feature     | Lead             | Sale                |
| ----------- | ---------------- | ------------------- |
| Tracking ID | Required         | Required            |
| Customer ID | Required         | Required            |
| Amount      | Not applicable   | Required            |
| Currency    | Not applicable   | Required            |
| Metadata    | Optional         | Optional            |
| Use case    | Sign-ups, trials | Purchases, payments |

## Integration Methods

Choose the integration method that best fits your stack:

### Native Integrations (Zero Code)

| Integration                                  | Best for            | Setup time |
| -------------------------------------------- | ------------------- | ---------- |
| [Stripe](/conversions/integrations/stripe)   | SaaS, subscriptions | 2 minutes  |
| [Shopify](/conversions/integrations/shopify) | E-commerce stores   | 2 minutes  |

### SDK Integrations

| Method                                                  | Best for         | Reliability |
| ------------------------------------------------------- | ---------------- | ----------- |
| [Client-side SDK](/conversions/track-leads)             | Simple setups    | Good        |
| [Server-side SDK](/conversions/track-leads#server-side) | Maximum accuracy | Excellent   |

### API Integrations

| Method                                 | Best for            | Flexibility |
| -------------------------------------- | ------------------- | ----------- |
| [REST API](/conversions/api-reference) | Custom integrations | Maximum     |

## Data Flow

### Client-side Flow

```
Browser → Taapit API → Your Dashboard
```

1. Browser reads `ta_tid` from cookie
2. SDK sends event to Taapit API
3. Data appears in your dashboard

**Pros:** Simple setup, no backend changes\
**Cons:** Can be blocked by ad blockers

### Server-side Flow

```
Browser → Your Backend → Taapit API → Your Dashboard
```

1. Browser sends `ta_tid` to your backend (cookie or form field)
2. Your backend sends event to Taapit API
3. Data appears in your dashboard

**Pros:** Cannot be blocked, more reliable\
**Cons:** Requires backend integration

## Privacy & Compliance

Taapit is designed with privacy in mind:

* **No personal data in tracking ID** – `ta_tid` is a random string
* **First-party cookies** – Set on your domain, not blocked by browsers
* **GDPR compliant** – No cross-site tracking
* **Data ownership** – You own your conversion data

## Next Steps

<CardGroup>
  <Card title="Get the Tracking ID" icon="fingerprint" href="/conversions/tracking-id">
    Learn how to retrieve the ta\_tid in your application.
  </Card>

  <Card title="Track Leads" icon="user-plus" href="/conversions/track-leads">
    Start tracking lead conversions.
  </Card>
</CardGroup>


# Client-side Integration
Source: https://docs.taap.it/conversions/manual/client-side

Track conversions directly from your frontend using the NPM package or script tag

Track leads and sales directly from the browser. This method is simple to implement but can be blocked by ad blockers.

<Warning>
  Client-side tracking can be **blocked by ad blockers**. For maximum
  reliability, we strongly recommend [Server-side
  Integration](/conversions/manual/server-side) instead.
</Warning>

## Prerequisites

<Warning>
  **Important**: For conversion tracking to work, users must arrive on your
  website via a **Taapit deeplink**. This is how the tracking ID (`ta_tid`) is
  generated and passed to your site.
</Warning>

Before you start:

1. **Create a Taapit deeplink** pointing to your website or landing page
2. **Enable conversion tracking** on your link:
   * Go to your link settings in the Taapit dashboard
   * Enable **Conversion Tracking**

Then, configure your Taapit workspace:

<Steps>
  <Step title="Go to Conversion settings">
    1. In your Taapit dashboard, go to [Settings →
       Conversion](https://taap.it/dashboard/settings/conversion) 2. In the
       dropdown, select **Manual Client-side Integration**
  </Step>

  <Step title="Add your allowed hostnames">
    1. In the **Allowed Hostnames** section, add your website domains (e.g.,
       `example.com`, `www.example.com`) 2. Click **Save**

    <Warning>
      The SDK will only work on domains listed in your allowed hostnames. Don't
      forget to add both `www` and non-`www` versions if needed.
    </Warning>
  </Step>

  <Step title="Get your Publishable Key">
    1. Copy your **Publishable Key** (starts with `taapit_pk_`) 2. You'll use
       this key in the next steps

    <Info>
      If you don't have a publishable key yet, click **Generate Key** to create
      one.
    </Info>
  </Step>
</Steps>

## Installation

Choose your preferred method:

<Tabs>
  <Tab title="NPM Package (React/Next.js)">
    <Steps>
      <Step title="Install the SDK">
        ```bash theme={null}
        npm install taapit-sdk
        ```
      </Step>

      <Step title="Add the Analytics component">
        Add the `Analytics` component to your root layout to automatically capture the `ta_tid`:

        ```tsx app/layout.tsx theme={null}
        import { Analytics } from 'taapit-sdk/react';

        export default function RootLayout({ children }) {
          return (
            <html>
              <body>
                {children}
                <Analytics publishableKey="taapit_pk_xxx" />
              </body>
            </html>
          );
        }
        ```

        <Info>
          Get your publishable key from the [Taapit Dashboard](https://taap.it/dashboard/settings/analytics).
        </Info>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Script Tag (No Build Step)">
    Add this script to your HTML `<head>` or before `</body>`:

    ```html theme={null}
    <script
      src="https://taap.it/api/sdk"
      data-publishable-key="taapit_pk_xxx"
    ></script>
    ```

    The script automatically:

    * Captures the `ta_tid` from the URL when users arrive
    * Stores it in a cookie for 365 days
    * Exposes the global `taapit` object

    **Alternative methods:**

    ```html theme={null}
    <!-- Via URL parameter -->
    <script src="https://taap.it/api/sdk?key=taapit_pk_xxx"></script>

    <!-- Or configure programmatically -->
    <script src="https://taap.it/api/sdk"></script>
    <script>
      taapit.configure({ publishableKey: "taapit_pk_xxx" });
    </script>
    ```
  </Tab>
</Tabs>

## Track a Lead

A **lead** is a potential customer who shows interest (sign-up, form submission, trial start).

<Info>
  **`trackingId` for leads**: The `trackingId` is **always required** for lead
  events. It is automatically detected from the `ta_tid` cookie set when the
  user clicked a Taapit link.
</Info>

<Tabs>
  <Tab title="NPM Package">
    ```tsx components/signup-form.tsx theme={null}
    'use client';

    import { useTaapitAnalytics } from 'taapit-sdk/react';

    export function SignUpForm() {
      const { trackLead, isReady, trackingId } = useTaapitAnalytics();

    const handleSubmit = async (formData: FormData) => {
    const email = formData.get('email') as string;
    const name = formData.get('name') as string;

        // Create user in your system
        const user = await createUser({ email, name });

        // Track the lead with Taapit
        trackLead({
          customer: {
            externalId: user.id,      // Required: your user ID
            email: user.email,
            firstname: user.firstName,
            lastname: user.lastName,
          },
          metadata: {
            source: 'signup-form',
            plan: 'free-trial',
          },
        });

    };

    return (

    <form action={handleSubmit}>
      <input name="name" placeholder="Name" required />
      <input name="email" type="email" placeholder="Email" required />
      <button type="submit">Start Free Trial</button>
    </form>
    ); }

    ```

    ### Direct import (alternative)

    ```tsx theme={null}
    import { taapit } from 'taapit-sdk/react';

    export function SignUpButton() {
      const handleClick = async () => {
        const user = await signUp();
        taapit.trackLead({
          customer: { externalId: user.id, email: user.email },
        });
      };

      return <button onClick={handleClick}>Sign Up</button>;
    }
    ```
  </Tab>

  <Tab title="Script Tag">
    ```html theme={null}
    <script>
      document.getElementById('signup-form').addEventListener('submit', async (e) => {
        e.preventDefault();
        
        const formData = new FormData(e.target);
        
        // Create user via your API
        const response = await fetch('/api/signup', {
          method: 'POST',
          body: formData,
        });
        const user = await response.json();
        
        // Track the lead
        taapit.trackLead({
          customer: {
            externalId: user.id,
            email: formData.get('email'),
            firstname: formData.get('name').split(' ')[0],
            lastname: formData.get('name').split(' ').slice(1).join(' '),
          },
        });
        
        window.location.href = '/dashboard';
      });
    </script>
    ```
  </Tab>
</Tabs>

## Track a Sale

A **sale** is a completed transaction (purchase, subscription, payment).

<Info>
  **`trackingId` for sales**: If the customer was already tracked via a **lead
  event**, the `trackingId` is optional. You only need the `customerExternalId`
  to link the sale to the existing customer. If this is a **new customer** (no
  prior lead), the user must have a valid `ta_tid` cookie (set by clicking a
  Taapit link).
</Info>

<Tabs>
  <Tab title="NPM Package">
    ```tsx components/checkout.tsx theme={null}
    'use client';

    import { useTaapitAnalytics } from 'taapit-sdk/react';

    export function CheckoutButton({ cart, user }) {
      const { trackSale } = useTaapitAnalytics();

    const handlePurchase = async () => {
    // Process payment
    const order = await processPayment(cart);

        // Track the sale with Taapit
        trackSale({
          customer: {
            externalId: user.id,
            email: user.email,
          },
          amount: cart.total,  // e.g., 49.99 (NOT cents)
          currency: 'eur',     // ISO 4217 code
          metadata: {
            orderId: order.id,
            items: cart.items.length,
          },
        });

        router.push(`/order/${order.id}`);

    };

    return (

    <button onClick={handlePurchase}>Complete Purchase - €{cart.total}</button>
    ); }

    ```
  </Tab>

  <Tab title="Script Tag">
    ```html theme={null}
    <script>
      document.getElementById('checkout-btn').addEventListener('click', async () => {
        // Process payment via your API
        const response = await fetch('/api/checkout', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ cartId: 'cart_123' }),
        });
        const order = await response.json();

        // Track the sale
        taapit.trackSale({
          customer: {
            externalId: order.userId,
            email: order.customerEmail,
          },
          amount: order.total,
          currency: order.currency,
          metadata: { orderId: order.id },
        });

        window.location.href = `/order/${order.id}`;
      });
    </script>
    ```
  </Tab>
</Tabs>

<Warning>
  The `amount` must be in **currency units**, not cents. - ✅ `amount: 29.99`
  for €29.99 - ❌ `amount: 2999` (this would be €2999)
</Warning>

## Available Methods

```javascript theme={null}
// Get the current tracking ID
const trackingId = taapit.getTrackingId();

// Track a lead (trackingId is ALWAYS required - auto-detected from cookie)
taapit.trackLead({
  customer: {
    externalId: 'user_123',    // Required
    email: 'john@example.com',
    firstname: 'John',
    lastname: 'Doe',
    phoneNumber: '+33612345678',
    avatarUrl: 'https://example.com/avatar.jpg',
  },
  metadata: { ... },  // Optional custom data
});

// Track a sale
// trackingId is optional if customer was already tracked via a lead event
taapit.trackSale({
  customer: { externalId: 'user_123' },  // Required - links to existing customer
  amount: 99.99,      // Required
  currency: 'eur',    // Required (ISO 4217)
  metadata: { ... },
});
```

## Best Practices

### 1. Always track after confirmation

```typescript theme={null}
// ✅ Good - Track after action is confirmed
const user = await createUser(data);
taapit.trackLead({ customer: { externalId: user.id } });

// ❌ Bad - Track before confirmation
taapit.trackLead({ customer: { externalId: "pending" } });
const user = await createUser(data); // Might fail!
```

### 2. Handle missing tracking IDs gracefully

```typescript theme={null}
const trackingId = taapit.getTrackingId();

if (trackingId) {
  taapit.trackLead({...});
}
// Continue with your flow even without tracking
```

### 3. Use stable external IDs

```typescript theme={null}
// ✅ Good - Use your database ID
customer: {
  externalId: user.id;
}

// ❌ Bad - Don't use transient values
customer: {
  externalId: session.id;
}
```

## Limitations

* **Ad blockers** may block tracking requests
* **Browser restrictions** can prevent cookies from being set
* **Page close** before tracking completes loses the event

For critical conversions like sales, consider [Server-side Integration](/conversions/manual/server-side).

## Next Steps

<CardGroup>
  <Card title="Server-side Integration" icon="server" href="/conversions/manual/server-side">
    More reliable tracking from your backend (recommended).
  </Card>

  <Card title="API Reference" icon="code" href="/conversions/api-reference">
    Full API documentation.
  </Card>
</CardGroup>


# Server-side Integration (Recommended)
Source: https://docs.taap.it/conversions/manual/server-side

Track conversions from your backend for maximum reliability

Server-side tracking is the **recommended method** for conversion tracking because it:

* ✅ **Can't be blocked** by ad blockers
* ✅ **Guarantees delivery** of tracking events
* ✅ **Confirms actions** before tracking (e.g., payment verified)
* ✅ **Works with webhooks** from payment providers

## How It Works

<Frame>
  <img alt="Taapit Visual manual integration" />
</Frame>

## Prerequisites

<Warning>
  **Important**: For conversion tracking to work, users must arrive on your
  website via a **Taapit deeplink**. This is how the tracking ID (`ta_tid`) is
  generated and passed to your site.
</Warning>

Before you start:

1. **Create a Taapit deeplink** pointing to your website or landing page
2. **Enable conversion tracking** on your link:
   * Go to your link settings in the Taapit dashboard
   * Enable **Conversion Tracking**
3. **Get your Secret Key** from [Settings → Conversion](https://taap.it/dashboard/settings/conversion) in your Taapit dashboard

<Warning>
  Never expose your **secret key** in client-side code. Use it only on your
  server.
</Warning>

## Installation

<Warning>
  Even for server-side tracking, you **must** install the SDK on your frontend
  to capture the `ta_tid` cookie.
</Warning>

<Tabs>
  <Tab title="NPM Package (React/Next.js)">
    ### Step 1: Frontend - Install the SDK

    ```bash theme={null}
    npm install taapit-sdk
    ```

    Add the Analytics component to capture `ta_tid`:

    ```tsx app/layout.tsx theme={null}
    import { Analytics } from "taapit-sdk/react";

    export default function RootLayout({ children }) {
      return (
        <html>
          <body>
            {children}
            <Analytics />
          </body>
        </html>
      );
    }
    ```

    ### Step 2: Backend - Set up your API key

    ```bash .env theme={null}
    TAAPIT_API_KEY=taapit_sk_xxx
    ```

    <Warning>Never expose your secret API key in client-side code.</Warning>

    ### Step 3: Backend - Track conversions

    ```typescript app/api/signup/route.ts theme={null}
    import { Taapit } from "taapit-sdk";
    import { cookies } from "next/headers";

    const taapit = new Taapit({
      apiKey: process.env.TAAPIT_API_KEY,
    });

    export async function POST(request: Request) {
      const body = await request.json();

      // Get tracking ID from cookie
      const cookieStore = cookies();
      const trackingId = cookieStore.get("ta_tid")?.value;

      // Create user in your database
      const user = await db.users.create({
        email: body.email,
        name: body.name,
      });

      // Track the lead
      if (trackingId) {
        await taapit.track.lead({
          trackingId,
          customer: {
            externalId: user.id,
            email: user.email,
          },
        });
      }

      return Response.json({ user });
    }
    ```
  </Tab>

  <Tab title="Script Tag + REST API">
    ### Step 1: Frontend - Add the script

    ```html theme={null}
    <script src="https://taap.it/api/sdk"></script>
    ```

    ### Step 2: Frontend - Send tracking ID to backend

    ```html theme={null}
    <script>
      document
        .getElementById("signup-form")
        .addEventListener("submit", async (e) => {
          e.preventDefault();
          const formData = new FormData(e.target);

          // Include tracking ID in request
          await fetch("/api/signup", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({
              email: formData.get("email"),
              name: formData.get("name"),
              trackingId: taapit.getTrackingId(), // Include this!
            }),
          });
        });
    </script>
    ```

    ### Step 3: Backend - Call the REST API

    ```bash theme={null}
    curl -X POST https://track.taap.it/api/events/lead \
      -H "Authorization: Bearer taapit_sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "trackingId": "rLnWe1uz9t282v7g",
        "customer": {
          "externalId": "user_123",
          "email": "john@example.com"
        }
      }'
    ```
  </Tab>
</Tabs>

## Track a Lead

<Tabs>
  <Tab title="Node.js SDK">
    ```typescript theme={null}
    import { Taapit } from 'taapit-sdk';
    import { cookies } from 'next/headers';

    const taapit = new Taapit({ apiKey: process.env.TAAPIT_API_KEY });

    export async function POST(request: Request) {
      const body = await request.json();
      const cookieStore = cookies();
      const trackingId = cookieStore.get('ta_tid')?.value || body.trackingId;
      
      // Create user
      const user = await createUser(body);
      
      // Track lead
      if (trackingId) {
        const result = await taapit.track.lead({
          trackingId,
          customer: {
            externalId: user.id,
            email: user.email,
            firstname: body.firstName,
            lastname: body.lastName,
          },
          metadata: {
            source: 'signup-api',
            plan: body.plan,
          },
        });
        
        if (!result.success) {
          console.error('Failed to track lead:', result.error);
        }
      }
      
      return Response.json({ user });
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    def track_lead(tracking_id: str, user: dict):
    response = requests.post(
    'https://track.taap.it/api/events/lead',
    headers={
    'Authorization': f'Bearer {TAAPIT_API_KEY}',
    'Content-Type': 'application/json',
    },
    json={
    'trackingId': tracking_id,
    'customer': {
    'externalId': user['id'],
    'email': user['email'],
    'firstname': user.get('first_name'),
    'lastname': user.get('last_name'),
    },
    },
    )
    return response.json()

    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    <?php
    function trackLead($trackingId, $user) {
        $ch = curl_init('https://track.taap.it/api/events/lead');

        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST => true,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . TAAPIT_API_KEY,
                'Content-Type: application/json',
            ],
            CURLOPT_POSTFIELDS => json_encode([
                'trackingId' => $trackingId,
                'customer' => [
                    'externalId' => $user['id'],
                    'email' => $user['email'],
                ],
            ]),
        ]);

        $response = curl_exec($ch);
        return json_decode($response, true);
    }
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    require 'net/http'
    require 'json'

    def track_lead(tracking_id, user)
    uri = URI('https://track.taap.it/api/events/lead')
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true

    request = Net::HTTP::Post.new(uri.path)
    request['Authorization'] = "Bearer #{TAAPIT_API_KEY}"
    request['Content-Type'] = 'application/json'
    request.body = {
    trackingId: tracking_id,
    customer: {
    externalId: user[:id],
    email: user[:email]
    }
    }.to_json

    response = http.request(request)
    JSON.parse(response.body)
    end

    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    func trackLead(trackingID string, user User) error {
        payload := map[string]interface{}{
            "trackingId": trackingID,
            "customer": map[string]string{
                "externalId": user.ID,
                "email":      user.Email,
            },
        }

        body, _ := json.Marshal(payload)
        req, _ := http.NewRequest("POST",
            "https://track.taap.it/api/events/lead",
            bytes.NewBuffer(body))

        req.Header.Set("Authorization", "Bearer "+apiKey)
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, err := client.Do(req)
        if err != nil {
            return err
        }
        defer resp.Body.Close()

        return nil
    }
    ```
  </Tab>
</Tabs>

## Track a Sale

<Info>
  **`trackingId` for sales**: If the customer was already tracked via a **lead
  event**, the `trackingId` is optional for sale events. You only need to
  provide the `customerExternalId` to link the sale to the existing customer. If
  this is a **new customer** (no prior lead), `trackingId` is required.
</Info>

<Tabs>
  <Tab title="Node.js SDK">
    ```typescript theme={null}
    export async function POST(request: Request) {
      const body = await request.json();
      const cookieStore = cookies();
      const trackingId = cookieStore.get('ta_tid')?.value || body.trackingId;
      
      // Verify payment
      const order = await verifyPayment(body);
      
      // Track sale
      // trackingId is optional if customer was already tracked via a lead event
      await taapit.track.sale({
        trackingId, // Optional if customer already exists
        customer: {
          externalId: order.userId, // Required - links to existing customer or creates new one
          email: order.customerEmail,
        },
        amount: order.total,      // e.g., 149.99 (NOT cents)
        currency: order.currency, // e.g., 'eur'
        metadata: {
          orderId: order.id,
          productIds: order.items.map(i => i.productId),
        },
      });
      
      return Response.json({ success: true });
    }
    ```
  </Tab>

  <Tab title="REST API">
    ```bash theme={null}
    # With trackingId (new customer or first-time tracking)
    curl -X POST https://track.taap.it/api/events/sale \
      -H "Authorization: Bearer taapit_sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "trackingId": "rLnWe1uz9t282v7g",
        "customer": {
          "externalId": "user_123",
          "email": "john@example.com"
        },
        "amount": 99.99,
        "currency": "eur",
        "metadata": {
          "orderId": "order_456"
        }
      }'

    # Without trackingId (customer already tracked via lead event)

    curl -X POST https://track.taap.it/api/events/sale \
     -H "Authorization: Bearer taapit_sk_xxx" \
     -H "Content-Type: application/json" \
     -d '{
    "customer": {
    "externalId": "user_123"
    },
    "amount": 99.99,
    "currency": "eur"
    }'

    ```
  </Tab>
</Tabs>

<Warning>
  The `amount` must be in **currency units**, not cents.

  * ✅ `amount: 29.99` for €29.99
  * ❌ `amount: 2999` (this would be €2999)
</Warning>

## API Reference

### Endpoints

| Event | Endpoint                                     |
| ----- | -------------------------------------------- |
| Lead  | `POST https://track.taap.it/api/events/lead` |
| Sale  | `POST https://track.taap.it/api/events/sale` |

### Authentication

```

Authorization: Bearer taapit_sk_xxx

```

### Request Body

```json theme={null}
{
  "trackingId": "rLnWe1uz9t282v7g",
  "customer": {
    "externalId": "user_123",
    "email": "john@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "phoneNumber": "+33612345678",
    "avatarUrl": "https://example.com/avatar.jpg"
  },
  "amount": 99.99,       // Sale only
  "currency": "eur",     // Sale only
  "metadata": {}
}
```

| Field                 | Type   | Required  | Description                  |
| --------------------- | ------ | --------- | ---------------------------- |
| `trackingId`          | string | See below | The `ta_tid` from cookie/URL |
| `customer.externalId` | string | Yes       | Your internal user ID        |
| `customer.email`      | string | No        | User's email                 |
| `amount`              | number | Sale only | Amount in currency units     |
| `currency`            | string | Sale only | ISO 4217 code (eur, usd...)  |
| `metadata`            | object | No        | Custom data                  |

<Info>
  **When is `trackingId` required?** - **Lead events**: `trackingId` is **always
  required** - **Sale events**: - If the `customerExternalId` was already
  tracked (via a previous lead event), `trackingId` is **optional** - If this is
  a new customer (no prior lead event), `trackingId` is **required** to create
  the customer record
</Info>

### Response

```json theme={null}
{ "ok": true }
```

## Best Practices

### 1. Get tracking ID from multiple sources

```typescript theme={null}
const cookieStore = cookies();
const trackingId =
  cookieStore.get("ta_tid")?.value || // Cookie (preferred)
  body.trackingId || // Request body
  new URL(request.url).searchParams.get("ta_tid"); // URL param
```

### 2. Always track after confirmation

```typescript theme={null}
// ✅ Good - Track after payment is confirmed
const paymentResult = await processPayment();
if (paymentResult.success) {
  await taapit.track.sale({...});
}

// ❌ Bad - Track before confirmation
await taapit.track.sale({...});
const paymentResult = await processPayment(); // Might fail!
```

### 3. Store tracking ID for later use

```typescript theme={null}
// When creating checkout session
const session = await stripe.checkout.sessions.create({
  metadata: { ta_tid: trackingId }, // Store for webhook
});

// Later in webhook, retrieve it
const trackingId = session.metadata.ta_tid;
```

### 4. Log tracking failures

```typescript theme={null}
const result = await taapit.track.sale({...});
if (!result.success) {
  console.error('Taapit tracking failed:', result.error);
  // Don't fail the main operation - tracking is secondary
}
```

## Next Steps

<CardGroup>
  <Card title="Stripe Integration" icon="stripe" href="/conversions/automatic/stripe">
    Automatic tracking for Stripe (even simpler).
  </Card>

  <Card title="Track Lead API" icon="code" href="/api-reference/events/lead">
    Full API documentation for leads.
  </Card>

  <Card title="Track Sale API" icon="code" href="/api-reference/events/sale">
    Full API documentation for sales.
  </Card>
</CardGroup>


# Overview
Source: https://docs.taap.it/conversions/overview

Track leads and sales from your Taapit deeplinks

Taapit Conversions allows you to track leads and sales from your deeplinks, enabling you to measure the ROI of your marketing campaigns.

## How it works

<Frame>
  <img alt="Taapit Visual manual integration" />
</Frame>

1. A user clicks on your Taapit deeplink
2. Taapit redirects them to your website with a `ta_tid` parameter
3. The tracking ID is stored in a cookie
4. When the user converts (signs up, purchases, etc.), the conversion is sent to Taapit

## Choose your integration method

There are **4 ways** to integrate Taapit Conversions:

<CardGroup>
  <Card title="🔌 Stripe" icon="stripe" href="/conversions/automatic/stripe">
    **Semi-automatic** – Install the SDK, pass tracking ID in Stripe metadata.
  </Card>

  <Card title="🔌 Shopify" icon="shopify" href="/conversions/automatic/shopify">
    **Automatic** – Install the app, enable the theme extension. Zero code.
  </Card>

  <Card title="🛠️ Client-side" icon="browser" href="/conversions/manual/client-side">
    **Manual** – Track conversions from your frontend with JavaScript.
  </Card>

  <Card title="🛠️ Server-side (Recommended)" icon="server" href="/conversions/manual/server-side">
    **Manual** – Track from your backend for maximum reliability.
  </Card>
</CardGroup>

## Which method should I use?

| Method          | Best for            | Pros                            | Cons                          |
| --------------- | ------------------- | ------------------------------- | ----------------------------- |
| **Stripe**      | SaaS, subscriptions | Automatic tracking via webhooks | Requires passing metadata     |
| **Shopify**     | E-commerce stores   | Zero code, fully automatic      | Shopify only                  |
| **Client-side** | Quick setup         | Easy to implement               | Can be blocked by ad blockers |
| **Server-side** | Production apps     | Reliable, can't be blocked      | Requires backend code         |

<Info>
  For most production applications, we recommend **Server-side integration** for
  maximum reliability, or one of the **Automatic integrations** if you use
  Stripe or Shopify.
</Info>


# taap.it API Documentation
Source: https://docs.taap.it/index

Powerful link management and analytics API for developers

# Welcome to taap.it API

The **taap.it API** provides powerful programmatic access to our link management and analytics platform. Create, manage, and track deeplinks with enterprise-grade features and detailed analytics.

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Get up and running with your first API call in under 5 minutes
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Secure API key authentication with granular permissions
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/links">
    Complete documentation for all endpoints and features
  </Card>

  <Card title="Analytics" icon="chart-line" href="/api-reference/stats">
    Detailed insights and performance metrics for your links
  </Card>
</CardGroup>

## Key Features

<AccordionGroup>
  <Accordion title="Link Management" icon="link">
    * Create deeplinks with custom codes and domains
    * Password protection and expiration settings
    * UTM parameter templates and tracking pixels
    * Bulk operations and advanced filtering
  </Accordion>

  <Accordion title="Analytics & Insights" icon="chart-bar">
    * Real-time click tracking and unique visitor counts
    * Geographic and device analytics
    * Browser and referrer statistics
    * Exportable reports and data visualization
  </Accordion>

  <Accordion title="Advanced Features" icon="cog">
    * Password protection and expiration settings
    * UTM parameter tracking and templates
    * QR code generation with custom branding
    * Geographic restrictions and access control
  </Accordion>

  <Accordion title="Custom Domains" icon="globe">
    * Branded deeplinks with your domain
    * DNS verification and setup assistance
    * SSL certificate management
    * Domain performance monitoring
  </Accordion>
</AccordionGroup>

## Popular API Endpoints

<CardGroup>
  <Card title="Links API" icon="link" href="/api-reference/links">
    **POST /v1/links** - Create, update, and manage deeplinks with advanced features like password protection and expiration dates.
  </Card>

  <Card title="Analytics API" icon="chart-line" href="/api-reference/stats">
    **GET /v1/stats/links/** - Access comprehensive analytics including clicks, geographic data, and device statistics.
  </Card>

  <Card title="Domains API" icon="globe" href="/api-reference/domains">
    **POST /v1/domains** - Manage custom domains for branded deeplinks with DNS verification.
  </Card>

  <Card title="Projects API" icon="folder" href="/api-reference/projects">
    **POST /v1/projects** - Organize and group related links with project-based management.
  </Card>
</CardGroup>

## Quick Example

<CodeGroup>
  ```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/long-url",
      "custom_code": "my-link"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.taap.it/v1/links', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      original_url: 'https://example.com/long-url',
      custom_code: 'my-link'
    })
  });
  ```

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

  response = requests.post(
    'https://api.taap.it/v1/links',
    headers={
      'Authorization': f'Bearer {api_key}',
      'Content-Type': 'application/json'
    },
    json={
      'original_url': 'https://example.com/long-url',
      'custom_code': 'my-link'
    }
  )
  ```
</CodeGroup>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "id": "link_987654321",
    "original_url": "https://example.com/long-url",
    "short_url": "https://taap.it/my-link",
    "code": "my-link",
    "created_at": "2024-01-15T10:30:00Z",
    "click_count": 0,
    "is_active": true
  }
  ```
</ResponseExample>

## Base URL & Authentication

All API requests should be made to:

```
https://api.taap.it/v1
```

<Info>
  All requests require authentication using API keys. Include your API key in the Authorization header: `Bearer taapit_your_api_key_here`
</Info>

<Card title="Ready to get started?" icon="rocket" href="/quickstart">
  Follow our quickstart guide to make your first API call and start building with taap.it.
</Card>


# Introduction
Source: https://docs.taap.it/introduction

Welcome to the taap.it API documentation

## What is taap.it API?

The taap.it API provides programmatic access to taap.it's link management and analytics platform. With our API, you can create, manage, and track deeplinks, analyze performance data, and integrate taap.it's capabilities directly into your applications.

## Key Features

<CardGroup>
  <Card title="Link Management" icon="link">
    Create, update, and delete deeplinks with custom domains and advanced features
  </Card>

  <Card title="Analytics & Insights" icon="chart-line">
    Track clicks, unique visitors, geographic data, and device analytics
  </Card>

  <Card title="Custom Domains" icon="globe">
    Create branded deeplinks with your own custom domains
  </Card>

  <Card title="Project Management" icon="folder">
    Group related links and track performance across projects
  </Card>
</CardGroup>

## Getting Started

<Steps>
  <Step title="Create an API Key">
    Log into your taap.it dashboard and navigate to your user settings to create an API key.

    <Warning>
      Keep your API key secure and never share it publicly. API keys provide full access to your account.
    </Warning>
  </Step>

  <Step title="Make Your First Request">
    Use your API key to authenticate requests to the taap.it API.

    ```bash cURL theme={null}
    curl -X GET 'https://api.taap.it/v1/links' \
      -H 'Authorization: Bearer taapit_your_api_key_here'
    ```
  </Step>

  <Step title="Start Building">
    Explore our endpoints for domains, links, projects, and stats to build powerful integrations.
  </Step>
</Steps>

## Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header using the Bearer token format:

```bash theme={null}
Authorization: Bearer taapit_your_api_key_here
```

<Info>
  API keys are prefixed with `taapit_` and can be created through the web application dashboard.
</Info>

## Base URL

All API requests should be made to:

```
https://api.taap.it/v1
```

## Rate Limits

The taap.it API implements rate limiting to ensure fair usage and optimal performance:

* **Plan-based Rate Limits**: Rate limits vary based on your subscription plan
* **Per-user enforcement**: Limits are applied per user account
* **Future endpoint-specific limits**: May be implemented for specific endpoints in the future

Rate limit headers are included in all responses:

```http theme={null}
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
```

## Response Format

All API responses are returned in JSON format with the following structure:

<CodeGroup>
  ```json Success Response theme={null}
  {
    "data": { ... },
    "message": "Success"
  }
  ```

  ```json Error Response theme={null}
  {
    "detail": "Error message describing what went wrong"
  }
  ```
</CodeGroup>

## Status Codes

The API uses standard HTTP status codes:

* `200` - Success
* `201` - Created
* `400` - Bad Request
* `401` - Unauthorized
* `403` - Forbidden
* `404` - Not Found
* `409` - Conflict
* `429` - Too Many Requests
* `500` - Internal Server Error

## Support

Need help? We're here to assist:

* **Email**: [support@taap.it](mailto:support@taap.it)
* **Documentation**: This documentation site
* **Status Page**: status.taap.it

<Card title="Ready to get started?" icon="rocket" href="/quickstart">
  Jump into our quickstart guide to make your first API call in under 5 minutes.
</Card>


# Quickstart Guide
Source: https://docs.taap.it/quickstart

Get up and running with the taap.it API in minutes

This quickstart guide will walk you through making your first API call to the taap.it API.

## Prerequisites

Before you begin, you'll need:

* A taap.it account
* An API key (created through the web dashboard)
* A tool to make HTTP requests (curl, Postman, or your preferred client)

## Step 1: Create an API Key

<Steps>
  <Step title="Log into taap.it Dashboard">
    Visit [www.taap.it](https://www.taap.it) and log into your account.
  </Step>

  <Step title="Navigate to API Settings">
    Go to your user settings and find the "API Keys" section.
  </Step>

  <Step title="Generate New Key">
    Click "Create API Key" and give it a descriptive name. Copy the generated key immediately.

    <Warning>
      API keys are only shown once during creation. Make sure to copy and store them securely.
    </Warning>
  </Step>
</Steps>

Your API key will look like this: `taapit_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz`

## Step 2: Make Your First Request

Let's start by listing your existing links to verify your API key is working:

```bash cURL theme={null}
curl -X GET 'https://api.taap.it/v1/links' \
  -H 'Authorization: Bearer taapit_your_api_key_here' \
  -H 'Content-Type: application/json'
```

**Response:**

```json theme={null}
{
  "items": [],
  "page": 1,
  "page_size": 20,
  "has_next": false
}
```

## Step 3: Create Your First Link

Now let's create a deeplink:

```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",
    "custom_code": "my-custom-link"
  }'
```

**Response:**

```json theme={null}
{
  "id": "link_987654321",
  "original_url": "https://example.com/very-long-url-that-needs-shortening",
  "short_url": "https://taap.it/my-custom-link",
  "code": "my-custom-link",
  "created_at": "2024-01-15T10:35:00Z",
  "updated_at": "2024-01-15T10:35:00Z",
  "click_count": 0,
  "is_active": true
}
```

## Step 4: Get Link Analytics

Let's check the analytics for your newly created link:

```bash cURL theme={null}
curl -X GET 'https://api.taap.it/v1/stats/links/link_987654321' \
  -H 'Authorization: Bearer taapit_your_api_key_here' \
  -H 'Content-Type: application/json'
```

**Response:**

```json theme={null}
[
  {
    "link_id": "link_987654321",
    "click_date": "2024-01-15",
    "total_clicks": 0,
    "unique_visitors": 0,
    "country_stats": {},
    "device_stats": {},
    "browser_stats": {},
    "scans_only": 0
  }
]
```

## Next Steps

<CardGroup>
  <Card title="Explore Domains" icon="globe" href="/api-reference/domains">
    Learn how to manage custom domains for your deeplinks
  </Card>

  <Card title="Project Management" icon="folder" href="/api-reference/projects">
    Organize your links into projects for better management
  </Card>

  <Card title="Advanced Analytics" icon="chart-line" href="/api-reference/stats">
    Dive deeper into link performance and user analytics
  </Card>

  <Card title="Links Management" icon="link" href="/api-reference/links">
    Create, update, and manage your deeplinks
  </Card>
</CardGroup>

## Common Patterns

### Error Handling

Always check for errors in API responses:

```javascript JavaScript Example theme={null}
const response = await fetch('https://api.taap.it/v1/links', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

if (!response.ok) {
  const error = await response.json();
  console.error('API Error:', error.detail);
  return;
}

const data = await response.json();
console.log('Success:', data);
```

### Rate Limit Handling

Handle rate limits gracefully:

```javascript JavaScript Example theme={null}
async function makeRequest(url, options) {
  const response = await fetch(url, options);
  
  if (response.status === 429) {
    const retryAfter = response.headers.get('Retry-After');
    console.log(`Rate limited. Retry after ${retryAfter} seconds`);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return makeRequest(url, options); // Retry
  }
  
  return response;
}
```

## Need Help?

<AccordionGroup>
  <Accordion title="Authentication Issues">
    * Verify your API key is correct and active
    * Ensure you're using the `Bearer` prefix in the Authorization header
    * Check that your API key hasn't expired
  </Accordion>

  <Accordion title="Rate Limiting">
    * Implement exponential backoff for retries
    * Monitor the `X-RateLimit-Remaining` header
    * Consider caching responses to reduce API calls
  </Accordion>

  <Accordion title="Common Errors">
    * **401 Unauthorized**: Invalid or missing API key
    * **403 Forbidden**: Insufficient permissions for the requested resource
    * **404 Not Found**: Resource doesn't exist or you don't have access
    * **409 Conflict**: Resource already exists (e.g., duplicate custom code)
  </Accordion>
</AccordionGroup>

<Card title="Ready to build?" icon="code" href="/api-reference">
  Explore our complete API reference to unlock the full power of taap.it.
</Card>