> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.partnerpage.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.partnerpage.io/_mcp/server.

# Track a lead

POST https://v1.api.partnerpage.io/api/deal-registration/private/v1alpha/tracking/lead/
Content-Type: application/json

Called by your server when a customer signs up. The Tracking ID names the directory, so one API key reports for each of your directories. A new customer needs the click ID your site kept in its `pp_click` cookie and becomes a Partner lead for the partner whose link was clicked, awaiting your approval. One customer ID gives one lead per directory: reporting it again, with or without the click, returns it. A lead the pasted script reported, still awaiting approval, moves to this report's click. Every call is real: try it on a test directory.

```bash
curl -X POST https://v1.api.partnerpage.io/api/deal-registration/private/v1alpha/tracking/lead/ \
  -H "Authorization: Token $PARTNERPAGE_API_KEY" -H "Content-Type: application/json" \
  -d '{"trackingId":"pp_trk_…","clickId":"<pp_click cookie>","customerId":"user_123","email":"jane@example.com","name":"Jane Doe","company":"Acme","eventName":"Sign up"}'
```

Reference: https://docs.partnerpage.io/api-reference/partner-tracking/track-a-lead

## Authentication

- `Authorization` header (required) (prefixed with ` Token   `) — Your API key, sent as `Authorization: Token <your API key>`

## Request

### Body (application/json)

This endpoint expects a TrackingLeadRequest.

- `customerId` (string, required) — Your own ID for the customer; one lead per customer ID.
- `email` (string, required)
- `trackingId` (string, required) — The directory's Tracking ID, from Settings › Partner links (pp_trk_...).
- `clickId` (string, optional, nullable) — The click ID the script kept in its pp_click cookie. Required for a customer PartnerPage does not know yet.
- `name` (string, optional, nullable)
- `company` (string, optional, nullable)
- `eventName` (string, optional, default: ) — Your own name for the event, for example Sign up.

## Response

### 200

A Partner lead already carries this customer ID

- `id` (string, required)
- `customerId` (string, required)
- `state` (enum, required) — * `submitted` - Submitted * `approved` - Approved * `declined` - Declined * `won` - Won * `lost` - Lost
  - Allowed values: `submitted`, `approved`, `declined`, `won`, `lost`
- `partnerEntryId` (string, required)

### 201

Partner lead created

- `id` (string, required)
- `customerId` (string, required)
- `state` (enum, required) — * `submitted` - Submitted * `approved` - Approved * `declined` - Declined * `won` - Won * `lost` - Lost
  - Allowed values: `submitted`, `approved`, `declined`, `won`, `lost`
- `partnerEntryId` (string, required)

## Errors

### 400 Bad Request Error

A field is missing or malformed, the body is not a JSON object, a new customer has no `clickId`, the click is unknown, from another directory or expired, or partner links are off

- `any`

### 401 Unauthorized Error

The API key is missing or invalid; a dashboard login is refused

- `any`

### 403 Forbidden Error

The Tracking ID is another organisation's, the key lacks the decide permission on Partner leads, or Partner leads are off

- `any`

### 404 Not Found Error

No directory has this Tracking ID: `{"code": "unknown_tracking_id"}`

- `any`

### 429 Too Many Requests Error

Rate limit exceeded: up to 1,000 requests an hour per API key to each of the lead, sale and refund calls

- `any`

## Examples

**Request**

```json
{
  "customerId": "user_123",
  "email": "jane@example.com",
  "trackingId": "pp_trk_4fQ9xZ2mK7pL1sV8nB3cR6tY",
  "clickId": "4c1e0a4e-2f8c-4a1b-9d9e-3b2a1c0d8e7f",
  "name": "Jane Doe",
  "company": "Acme",
  "eventName": "Sign up"
}
```

**SDK Code**

```python Example request (application/json)
import requests

url = "https://v1.api.partnerpage.io/api/deal-registration/private/v1alpha/tracking/lead/"

payload = {
    "customerId": "user_123",
    "email": "jane@example.com",
    "trackingId": "pp_trk_4fQ9xZ2mK7pL1sV8nB3cR6tY",
    "clickId": "4c1e0a4e-2f8c-4a1b-9d9e-3b2a1c0d8e7f",
    "name": "Jane Doe",
    "company": "Acme",
    "eventName": "Sign up"
}
headers = {
    "Authorization": "Token  <apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Example request (application/json)
const url = 'https://v1.api.partnerpage.io/api/deal-registration/private/v1alpha/tracking/lead/';
const options = {
  method: 'POST',
  headers: {Authorization: 'Token  <apiKey>', 'Content-Type': 'application/json'},
  body: '{"customerId":"user_123","email":"jane@example.com","trackingId":"pp_trk_4fQ9xZ2mK7pL1sV8nB3cR6tY","clickId":"4c1e0a4e-2f8c-4a1b-9d9e-3b2a1c0d8e7f","name":"Jane Doe","company":"Acme","eventName":"Sign up"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```