> ## 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 subscribers

> Track a subscriber event — use this to attribute a newsletter or free-plan subscription to a promoter before the lead signs up for a paid plan. Unlike the `signup` endpoint, `subscriber` does not require the visitor to have been tracked by the FirstPromoter JS script (no `tid` required when using `ref_id`). <Note>**Expired referrals.** If the company has referral expiry set and the referral for this email or uid has expired, a call that names its current promoter (`ref_id`, `tid`, `promo_code` or `promoter_email`) restarts it for that promoter: a referral that never bought becomes a fresh lead dated now, and an expired customer gets a new referral with no `customer_since`, while the old one keeps its history. A call that names a different promoter moves the customer to that promoter. A call that names no promoter leaves an expired referral as it is.</Note><Tip>**HTTP Request** <br/>`POST https://firstpromoter.com/api/v1/track/subscriber`</Tip>



## OpenAPI

````yaml openapi-tracking POST /subscriber
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:
  /subscriber:
    post:
      description: >-
        Track a subscriber event — use this to attribute a newsletter or
        free-plan subscription to a promoter before the lead signs up for a paid
        plan. Unlike the `signup` endpoint, `subscriber` does not require the
        visitor to have been tracked by the FirstPromoter JS script (no `tid`
        required when using `ref_id`). <Note>**Expired referrals.** If the
        company has referral expiry set and the referral for this email or uid
        has expired, a call that names its current promoter (`ref_id`, `tid`,
        `promo_code` or `promoter_email`) restarts it for that promoter: a
        referral that never bought becomes a fresh lead dated now, and an
        expired customer gets a new referral with no `customer_since`, while the
        old one keeps its history. A call that names a different promoter moves
        the customer to that promoter. A call that names no promoter leaves an
        expired referral as it is.</Note><Tip>**HTTP Request** <br/>`POST
        https://firstpromoter.com/api/v1/track/subscriber`</Tip>
      parameters:
        - name: email
          in: query
          description: |-
            `required if uid is null`

            Email of the subscriber.
          schema:
            type: string
        - name: uid
          in: query
          description: |-
            `required if email is null`

            Unique identifier for the subscriber in your system.
          schema:
            type: string
        - name: tid
          in: query
          description: >-
            Visitor tracking ID from the `_fprom_tid` cookie. Required if
            `ref_id` is not provided.
          schema:
            type: string
        - name: ref_id
          in: query
          description: >-
            Promoter's referral ID. Use this to assign the subscriber directly
            to a promoter when `tid` is not available.
          schema:
            type: string
        - name: ip
          in: query
          description: IP address of the subscriber. Used for fraud analysis.
          schema:
            type: string
        - name: promoter_email
          in: query
          description: Email of the promoter to assign this subscriber to.
          schema:
            type: string
        - name: created_at
          in: query
          description: >-
            ISO 8601 date string of when the subscription occurred. Defaults to
            now.
          schema:
            type: string
            format: date-time
        - name: skip_email_notification
          in: query
          description: Set to `true` to suppress email notifications. Default is `false`.
          schema:
            type: boolean
        - name: username
          in: query
          description: Username of the subscriber.
          schema:
            type: string
        - name: first_name
          in: query
          description: First name of the subscriber.
          schema:
            type: string
        - name: last_name
          in: query
          description: Last name of the subscriber.
          schema:
            type: string
        - name: website
          in: query
          description: Website of the subscriber.
          schema:
            type: string
        - name: custom_fields
          in: query
          description: JSON object of custom field key-value pairs.
          schema:
            type: object
      responses:
        '200':
          description: Subscriber tracked successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 44812309
                  type:
                    type: string
                    example: subscriber
                  lead:
                    $ref: '#/components/schemas/Lead'
                  promoter:
                    $ref: '#/components/schemas/Promoter'
        '204':
          description: No Content — lead not found; subscriber is not a referral.
        '404':
          description: Not Found — visitor tracking ID or promoter referral ID not found.
        '409':
          description: Conflict — a subscriber event for this lead already exists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.