> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstpromoter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tracking leads and sign-ups
> Capture a lead when they sign-up or fill an optin form. This endpoint is used to track leads and sign-ups. It's not for tracking the actual sales and commissions.
Sign-ups are tracked as leads in FirstPromoter so when a person referred by the promoter/affiliate signs up, a new referral should be added inside FirstPromoter **(you can see them inside the `Referrals` section as `Leads`)**.
The recommended way to do this is to grab the `_fprom_tid` **(_fprom_track for accounts created prior to April 2021)** cookie value(which keeps the tracking id and referral identification) on your server and send it along with the sign-up data through the tid parameter.
**Alternative:** In some special cases, you can refer sign ups directly to a promoter, by passing the referral id through ref_id parameter. Be careful when using this because the referral id can be modified by the promoter by default, however you can disable that from the campaign configuration page.**HTTP Request**
`POST https://firstpromoter.com/api/v1/track/signup`
## OpenAPI
````yaml openapi-tracking POST /signup
openapi: 3.0.1
info:
title: FirstPromoter Tracking API
description: >-
Our tracking API allows companies to track any type of signups, sales,
cancellations and refunds for any billing provider, you are not limited to
our built-in integrations with Stripe, Chargebee, Recurly and Braintree.
license:
name: MIT
version: 1.0.0
servers:
- url: https://firstpromoter.com/api/v1/track
security:
- apiKeyAuth: []
paths:
/signup:
post:
description: >-
Capture a lead when they sign-up or fill an optin form. This endpoint is
used to track leads and sign-ups. It's not for tracking the actual sales
and commissions.
Sign-ups are tracked as leads in
FirstPromoter so when a person referred by the promoter/affiliate signs
up, a new referral should be added inside FirstPromoter **(you can see
them inside the `Referrals` section as `Leads`)**.
The
recommended way to do this is to grab the `_fprom_tid` **(_fprom_track
for accounts created prior to April 2021)** cookie value(which keeps the
tracking id and referral identification) on your server and send it
along with the sign-up data through the tid parameter.
**Alternative:** In some special cases, you can refer sign ups directly
to a promoter, by passing the referral id through ref_id parameter. Be
careful when using this because the referral id can be modified by the
promoter by default, however you can disable that from the campaign
configuration page.**HTTP Request**
`POST
https://firstpromoter.com/api/v1/track/signup`
parameters:
- name: email
in: query
description: |-
`required if uid is null`
Email of the lead/sign-up
schema:
type: string
- name: uid
in: query
description: >-
`required if email is null`
ID to match the sale with the lead if the email can be changed
before the first sale. If the sales are tracked by our built-in
integrations and not by our API, the `uid` must match customer ID on
Stripe, Braintree, Chargebee, Recurly. Since Stripe doesn't allow
pre-defined customer id, you can also pass the `uid` value as
`fp_uid` in customer metadata later, when you create the customer
object.
schema:
type: string
- name: tid
in: query
description: |-
`required if ref_id is null`
Visitor tracking ID. It's set when the visitor tracking script tracks the referral visit on our system. The value is found inside `_fprom_tid` cookie. Grab that value from the cookie and pass it here to match the lead with the referral.
schema:
type: string
- name: ref_id
in: query
description: |-
`required if tid is null`
Default referral id of the promoter. Use this only when you want to assign the lead to a specific promoter.
schema:
type: string
- name: ip
in: query
description: >-
IP of the visitor who generated the sign up. It's used for fraud
analysis.
schema:
type: string
- name: promoter_email
in: query
description: Email of the promoter
schema:
type: string
- name: created_at
in: query
description: ISO date string of the date of the signup event
schema:
type: string
- name: skip_email_notification
in: query
description: Set this to `true` to skip email notifications. Default is `false`.
schema:
type: boolean
- name: username
in: query
description: Username of the lead.
schema:
type: string
- name: first_name
in: query
description: First name of the lead.
schema:
type: string
- name: last_name
in: query
description: Last name of the lead.
schema:
type: string
- name: website
in: query
description: Website URL of the lead.
schema:
type: string
- name: custom_fields
in: query
description: JSON object of custom field key-value pairs to store on the lead.
schema:
type: object
- name: sub_id
in: query
description: Subscriber/visitor sub-ID for tracking sub-channels.
schema:
type: string
- name: override_existing_lead
in: query
description: >-
Set to `true` to overwrite an existing lead record with the supplied
data.
schema:
type: boolean
responses:
'200':
description: Successful signup response
content:
application/json:
schema:
type: object
properties:
id:
type: integer
example: 33765409
type:
type: string
example: signup
amount_cents:
type: integer
nullable: true
reward:
type: string
nullable: true
lead:
$ref: '#/components/schemas/Lead'
promoter:
$ref: '#/components/schemas/Promoter'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Error. Email and uid can not be blank!
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: >-
Visitor invalid, not found or you are trying to use the
signup tracking test via API which doesn't work on API
calls.
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
transaction_id:
type: string
example: there is already a signup event registered on this lead
components:
schemas:
Lead:
type: object
properties:
id:
type: integer
example: 20738339
state:
type: string
example: cancelled
email:
type: string
example: hello@testmintli.com
uid:
type: string
nullable: true
example: null
customer_since:
type: string
format: date-time
example: '2024-09-11T14:22:12.160Z'
cancelled_at:
type: string
format: date-time
example: '2024-09-11T15:07:46.174Z'
plan_name:
type: string
nullable: true
example: null
suspicion:
type: string
example: no_suspicion
username:
type: string
nullable: true
example: null
website:
type: string
nullable: true
example: null
created_at:
type: string
format: date-time
example: '2024-09-09T16:22:44.168Z'
split_promotion_id:
type: string
nullable: true
example: null
custom_fields:
type: string
nullable: true
example: null
split_percentage_value:
type: string
nullable: true
example: null
visitor_sub_id:
type: string
nullable: true
example: null
Promoter:
type: object
properties:
id:
type: integer
description: ID of the promoter
example: 3920164
status:
type: string
description: Status of the promoter
example: active
cust_id:
type: string
example: ''
email:
type: string
description: Email of the promoter
example: peluwydo@mailinator.com
created_at:
type: string
format: date-time
description: ISO date of when the promoter was created
example: '2022-04-26T15:28:24.800Z'
temp_password:
type: string
description: Temporary password created for the promoter
nullable: true
example: xxxxxxxxxx
default_promotion_id:
type: integer
example: 4210919
pref:
type: string
example: db1znwe
default_ref_id:
type: string
description: Default referral id of the promoter
example: 8yi2epelut
note:
type: string
description: A note/description of promoter
nullable: true
example: This is a note
w8_form_url:
type: string
description: Url of the w8 form
nullable: true
example: null
w9_form_url:
type: string
description: Url of the w9 form
nullable: true
example: null
parent_promoter_id:
type: integer
description: Parent promoter id
example: 577918
earnings_balance:
type: object
description: Earning balance of the promoter
properties:
cash:
type: integer
example: 50744
current_balance:
type: object
description: Current balance of the promoter
properties:
cash:
type: integer
example: 20044
paid_balance:
type: object
description: Paid balance of the promoter
properties:
cash:
type: integer
example: 30700
auth_token:
type: string
description: Authentication token generated when the promoter was created
example: xxxxxxxxxxxxxx
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
````