---
id: "api-reference/track-lead"
type: "doc"
url: "https://affitor.com/docs/api-reference/track-lead"
kind: "reference"
updated: "2026-11-16"
---
# Track Lead

> Record a signup or lead event that links a customer to an affiliate click.

`POST /api/v1/track/lead`

Records a lead event for a customer who signed up through an affiliate referral. Call this after a successful registration so Affitor can advance the attribution chain from click → lead.

---

## Authentication

| Mode | When to use | How |
|------|-------------|-----|
| **Server mode** (recommended) | Your backend calls the API after a signup | `Authorization: Bearer <program_api_token>` |
| **Browser mode** | The tracker's `signup()` call from the page | No `Authorization` header — the call carries only the `click_id` |

The mode is decided by the header: a request with a valid Bearer key is server mode, and a request without one is browser mode. In server mode, Affitor validates the key and checks that the customer belongs to that program.

### Lead auth policy

Each program has a lead auth policy. **Every program requires server-verified leads** (`server_required`) unless it is explicitly set to allow browser leads (`browser_allowed`). Under `server_required`, a browser-mode lead is recorded as **provisional**:

- the API still returns `200`, with `provisional: true` in the body
- the lead does not settle attribution, does not save your `customer_key` on the customer, and does not count in partner metrics or pay a per-lead commission
- it settles only when your backend sends the same lead with a Bearer key, or when a Stripe Checkout payment for that customer arrives through your connected Stripe account. A sale sent to `/api/v1/track/sale` does not settle it, and a Bearer lead sent after that sale returns `400`

A browser lead settles directly only on a program set to `browser_allowed`. A browser lead that did not settle answers `200` with `"provisional": true`. Send leads from your server with a Bearer key so the lead settles under either policy.

---

## Request

### Headers

<ParamList>
  <ParamField name="Authorization" type="header" requirement="conditional">
    `Bearer <program_api_token>` — send it for server mode. Without it, the call is treated as browser mode.
  </ParamField>
  <ParamField name="Content-Type" type="header" required>
    Must be `application/json`.
  </ParamField>
</ParamList>

### Body fields

<ParamList>
  <ParamField name="click_id" type="string" requirement="conditional">
    The `affitor_click_id` value from the affiliate click cookie. Send it on every lead outside test mode: Affitor finds the customer through the click.
  </ParamField>
  <ParamField name="customer_key" type="string" requirement="conditional">
    Your internal customer or user ID. Send it with the `click_id`: when the lead settles, Affitor saves it on that customer, so later sales can find the customer by your own id. On its own it finds no customer on a first lead, because the key is saved only when a lead settles.
  </ParamField>
  <ParamField name="email" type="string">
    The buyer's email address. Send it on every lead. When the lead settles, Affitor saves a one-way hash of it and a masked form (`j***@example.com`) on the customer, only if the customer has none yet; the lead never stores the address itself. It is the fallback that keeps a sale with the right partner: a Stripe Checkout payment that carries no click id (the buyer paid on another device or cleared their cookies) is matched to this customer by its checkout email, so it can still go to the partner who referred them. A provisional browser lead does not save it.
  </ParamField>
  <ParamField name="additional_data" type="object">
    Optional metadata. Supports `test_mode` (boolean), `program_id` (number), and `event_name` (string).
  </ParamField>
  <ParamField name="program_id" type="string | integer">
    The program of the page (the tracker sends it). Read only in browser mode; with a Bearer key, the key's program decides. When sent, the customer found by `click_id` or `customer_key` must belong to this program; otherwise the lead answers `400` `Customer not found. Provide a valid click_id or customer_key.`
  </ParamField>
</ParamList>

Outside test mode, send the `click_id` with your `customer_key`. A request with neither answers `400` `click_id or customer_key is required`. A first lead with only `customer_key` answers `400` `Customer not found. Provide a valid click_id or customer_key.`, because Affitor saves your key on the customer only when a lead settles. Without a Bearer key, `click_id` is always required.

### Request body example

<CodeGroup items={[
  {
    label: "cURL",
    lang: "bash",
    code: `curl -X POST https://api.affitor.com/api/v1/track/lead \\
  -H "Authorization: Bearer YOUR_PROGRAM_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "click_id": "cust_42_1234567890",
    "customer_key": "usr_abc123",
    "email": "user@example.com"
  }'`
  },
  {
    label: "JSON body",
    lang: "json",
    code: `{
  "click_id": "cust_42_1234567890",
  "customer_key": "usr_abc123",
  "email": "user@example.com"
}`
  },
]} />

---

## Response

### Success — 200

```json
{
  "success": true,
  "message": "Lead tracked successfully"
}
```

### Success — provisional browser lead (200)

Returned for a browser-mode lead (no Bearer key) when the program requires server-verified leads. The lead is stored but not settled; see [Lead auth policy](#lead-auth-policy).

```json
{
  "success": true,
  "provisional": true,
  "message": "Lead recorded as provisional. This program requires server-side (Bearer) lead tracking to settle attribution."
}
```

### Success — test mode (200)

When `additional_data.test_mode` is `true`, the response includes the created event details:

```json
{
  "success": true,
  "message": "Test lead event tracked successfully",
  "data": {
    "eventId": 456,
    "programId": 1,
    "test_mode": true
  }
}
```

---

## Errors

| Status | Condition |
|--------|-----------|
| `400 Bad Request` | `click_id` and `customer_key` are both missing (outside test mode): `click_id or customer_key is required` |
| `400 Bad Request` | Browser mode: `customer_key` was sent without `click_id` (`click_id is required when no API key is sent`) |
| `400 Bad Request` | No customer record found for the provided `click_id` or `customer_key` (for example a first lead sent with only `customer_key`), or (browser mode) the customer does not belong to the `program_id` sent |
| `400 Bad Request` | Customer does not belong to the authenticated program (server mode cross-program mismatch) |
| `400 Bad Request` | Customer status cannot transition to lead (e.g. already converted) |
| `401 Unauthorized` | `Authorization` header is present but the token is invalid or not found |
| `403 Forbidden` | Test mode only: the Bearer key and `additional_data.program_id` name different programs (`program_id does not match the API key`) |
| `500 Internal Server Error` | Unexpected error during lead event creation |

---

## Test Mode

Send `additional_data.test_mode: true` to create a test lead event without affecting production attribution. In test mode:

- a Bearer key is not required to store the test event, but only a test event sent with your program API key counts toward integration verification
- pass `additional_data.program_id` to associate the test event with a specific program
- the event is created with `is_test: true`

```json
{
  "click_id": "test_lead_001",
  "customer_key": "test_customer",
  "additional_data": {
    "test_mode": true,
    "program_id": 1
  }
}
```

---

## Related

- [Click Tracking](/docs/brand/tracking/click-tracking/) — must run before lead tracking
- [Lead Tracking Guide](/docs/brand/tracking/lead-tracking-signup/) — implementation examples (Node.js, Python, browser)
- [Track Sale](/docs/api-reference/track-sale/) — next step after a successful lead
