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

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