Track Lead

Report a lead conversion event — typically a user sign-up — and attribute it to a referral click.

POST /api/track/lead

Reports a lead event for a customer who arrived via a Refport referral link. Use this to attribute sign-ups and account creations to the partner who referred them.

Request

Headers

Header	Value
`Authorization`	`Bearer YOUR_API_KEY`
`Content-Type`	`application/json`

Body

{
  "clickId": "abc123",
  "eventName": "Sign Up",
  "customerExternalId": "user_001",
  "customerEmail": "alice@example.com",
  "customerName": "Alice",
  "customerAvatar": "https://example.com/avatar.png",
  "metadata": {
    "plan": "free"
  }
}

Field	Type	Required	Description
`clickId`	`string`	Yes	The `refp_id` click ID from the user's cookie
`eventName`	`string`	Yes	Descriptive name for the event (e.g. `"Sign Up"`)
`customerExternalId`	`string`	Yes	Your internal user ID — used to link future sales to this lead
`customerEmail`	`string`	No	User's email address
`customerName`	`string`	No	User's display name
`customerAvatar`	`string`	No	URL to the user's avatar
`metadata`	`object`	No	Arbitrary key-value data attached to the event

Response

200 OK

{
  "eventName": "Sign Up",
  "click": {
    "id": "clk_xyz"
  },
  "link": {
    "id": "lnk_abc",
    "domain": "go.yoursite.com",
    "key": "alice",
    "url": "https://yoursite.com",
    "programId": "prog_001"
  },
  "customer": {
    "externalId": "user_001",
    "email": "alice@example.com",
    "name": "Alice"
  }
}

Error responses

Status	Code	Description
`400`	`INVALID_CLICK_ID`	The `clickId` does not match any recorded click
`400`	`VALIDATION_ERROR`	Missing or malformed required field
`401`	`UNAUTHORIZED`	Invalid or missing API key
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests — retry after backing off

SDK equivalent

await refport.track.lead({
  clickId: 'abc123',
  eventName: 'Sign Up',
  customerExternalId: 'user_001',
  customerEmail: 'alice@example.com',
});

See the Node.js SDK reference for full parameter details.