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

# Track Click

> Record a click event for affiliate tracking. This endpoint uses burst rate limiting for high-frequency tracking.

Use this endpoint to track when a visitor clicks an affiliate link. This is useful for server-side tracking implementations. You can later use the returned ID as `referral_id` in Affonso server-side tracking endpoints.

## Body Parameters

<ParamField body="programId" type="string" required>
  The unique identifier of the affiliate program. The program must belong to your team.
</ParamField>

<ParamField body="trackingId" type="string" required>
  The affiliate's tracking ID. The affiliate must have an approved partnership with the specified program.
</ParamField>

<ParamField body="sub1" type="string">
  Sub-parameter 1 for custom tracking. Maximum 255 characters.
</ParamField>

<ParamField body="sub2" type="string">
  Sub-parameter 2 for custom tracking. Maximum 255 characters.
</ParamField>

<ParamField body="sub3" type="string">
  Sub-parameter 3 for custom tracking. Maximum 255 characters.
</ParamField>

<ParamField body="sub4" type="string">
  Sub-parameter 4 for custom tracking. Maximum 255 characters.
</ParamField>

<ParamField body="sub5" type="string">
  Sub-parameter 5 for custom tracking. Maximum 255 characters.
</ParamField>

<ParamField body="referrer" type="string">
  The referring URL where the click originated. Maximum 2000 characters.
</ParamField>

<ParamField body="ip" type="string">
  Visitor's IP address. Maximum 45 characters (supports IPv6).
</ParamField>

<ParamField body="userAgent" type="string">
  Visitor's user agent string. Maximum 1000 characters.
</ParamField>

<ParamField body="utmSource" type="string">
  UTM source parameter. Maximum 255 characters.
</ParamField>

<ParamField body="utmMedium" type="string">
  UTM medium parameter. Maximum 255 characters.
</ParamField>

<ParamField body="utmCampaign" type="string">
  UTM campaign parameter. Maximum 255 characters.
</ParamField>

<ParamField body="utmTerm" type="string">
  UTM term parameter. Maximum 255 characters.
</ParamField>

<ParamField body="utmContent" type="string">
  UTM content parameter. Maximum 255 characters.
</ParamField>

<ParamField body="gclid" type="string">
  Google Click ID for Google Ads tracking. Maximum 255 characters.
</ParamField>

<ParamField body="fbclid" type="string">
  Facebook Click ID for Facebook Ads tracking. Maximum 255 characters.
</ParamField>

<ParamField body="msclkid" type="string">
  Microsoft Click ID for Microsoft Ads tracking. Maximum 255 characters.
</ParamField>

<ParamField body="ttclid" type="string">
  TikTok Click ID for TikTok Ads tracking. Maximum 255 characters.
</ParamField>

## Response

The response includes the created click object.

<ResponseField name="success" type="boolean">
  Always `true` for successful responses
</ResponseField>

<ResponseField name="data" type="object">
  The created click object.

  <Expandable title="Data Object Properties">
    <ResponseField name="id" type="string">
      Unique identifier for the click. You can use this value as `referral_id` in later requests such as `POST /v1/events`, `POST /v1/conversions`, or the Segment adapter (`properties.referral_id`).
    </ResponseField>

    <ResponseField name="trackingId" type="string">
      The affiliate's tracking ID
    </ResponseField>

    <ResponseField name="programId" type="string">
      The affiliate program ID
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of when the click was recorded
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.affonso.io/v1/clicks" \
    -H "Authorization: Bearer sk_live_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "programId": "prg_456def",
      "trackingId": "PARTNER123",
      "referrer": "https://partner-blog.com/review",
      "utmSource": "partner-blog",
      "utmMedium": "referral",
      "utmCampaign": "summer-2024"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "clk_xyz789",
      "trackingId": "PARTNER123",
      "programId": "prg_456def",
      "createdAt": "2024-01-25T12:00:00Z"
    }
  }
  ```
</ResponseExample>

**Note:** If this click is the first stable identifier you have, keep the returned `id` and send it as `referral_id` in your first backend conversion or event request. Once the referral is linked to your own `customer_id` or `external_user_id`, later events can use those identifiers instead.