FirstPromoter

https://docs.firstpromoter.com/
Admin
FirstPromoter is a modern affiliate and referral marketing platform for SaaS companies that enables...
Tokens:102,167
Snippets:624
Trust Score:9.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example Authenticated GET Request

Source: https://docs.firstpromoter.com/api-reference-v2/api-admin/authentication

An example of a GET request to the referrals endpoint, demonstrating the required authentication headers.

```http
GET https://api.firstpromoter.com/api/v2/company/referrals
Authorization: Bearer 01234567890abcdef
ACCOUNT-ID: 123456
```

--------------------------------

### Logout Implementation Examples

Source: https://docs.firstpromoter.com/advanced/embed-dashboard-logout

Examples of how to trigger the logout request from a backend application.

```js
app.post("/logout", async (req, res) => {
  const promoterId = req.user.firstpromoterPromoterId;

  await fetch(
    `https://v2.firstpromoter.com/api/v2/promoters/iframe_logout?promoter_id=${promoterId}`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.FP_API_KEY}`,
        "Account-Id": process.env.FP_ACCOUNT_ID,
      },
    }
  );

  // ...continue your own app's logout flow
  res.redirect("/login");
});
```

```php
<?php
$promoterId = $currentUser->firstpromoter_promoter_id;

$ch = curl_init(
  "https://v2.firstpromoter.com/api/v2/promoters/iframe_logout?promoter_id=" . urlencode($promoterId)
);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . $_ENV["FP_API_KEY"],
  "Account-Id: " . $_ENV["FP_ACCOUNT_ID"],
]);
curl_exec($ch);
curl_close($ch);
?>
```

```sh
curl --request POST \
  --url 'https://v2.firstpromoter.com/api/v2/promoters/iframe_logout?promoter_id=12345' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Account-Id: YOUR_ACCOUNT_ID'
```

--------------------------------

### Example Payloads

Source: https://docs.firstpromoter.com/webhooks-v2/payload

Examples of webhook payloads for different event types.

```APIDOC
## Example Payloads

### promoter.created
```json
{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event_type": "promoter.created",
  "action": "created",
  "entity_type": "promoter",
  "entity_id": 12345,
  "changes": {},
  "data": {
    "id": 12345,
    "email": "jane@example.com",
    "name": "Jane Smith",
    "cust_id": "cus_abc123",
    "balances": {},
    "joined_at": "2025-01-15T10:30:00Z",
    "profile": {
      "id": 98765,
      "first_name": "Jane",
      "last_name": "Smith",
      "website": "https://janesmith.com",
      "company_name": "",
      "phone_number": "",
      "address": "",
      "country": "US",
      "paypal_email": "",
      "avatar": ""
    }
  },
  "timestamp": "2025-01-15T10:30:00Z"
}
```

### referral.updated
```json
{
  "event_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "event_type": "referral.updated",
  "action": "updated",
  "entity_type": "referral",
  "entity_id": 55678,
  "changes": {
    "state": ["pending", "active"],
    "customer_since": [null, "2025-01-20T14:00:00Z"]
  },
  "data": {
    "id": 55678,
    "state": "active",
    "email": "user@example.com",
    "uid": "user_ext_id",
    "customer_since": "2025-01-20T14:00:00Z",
    "fraud_check": "no_suspicion",
    "created_at": "2025-01-18T09:00:00Z"
  },
  "timestamp": "2025-01-20T14:00:05Z"
}
```

### commission.updated
```json
{
  "event_id": "c3d4e5f6-a7b8-9012-cdef-012345678902",
  "event_type": "commission.updated",
  "action": "updated",
  "entity_type": "commission",
  "entity_id": 88901,
  "changes": {
    "status": ["pending", "approved"]
  },
  "data": {
    "id": 88901,
    "status": "approved",
    "amount": 2500,
    "unit": "cash",
    "referral": {
      "id": 55678,
      "email": "user@example.com",
      "uid": "user_ext_id"
    },
    "created_at": "2025-01-18T09:00:00Z"
  },
  "timestamp": "2025-01-21T11:15:00Z"
}
```

### contract_document.signed
```json
{
  "event_id": "d4e5f6a7-b8c9-0123-defa-123456789012",
  "event_type": "contract_document.signed",
  "action": "updated",
  "entity_type": "contract_document",
  "entity_id": 4421,
  "changes": {
    "signed_at": [null, "2025-01-22T08:45:00Z"]
  },
  "data": {
    "id": 4421,
    "promoter_id": 12345,
    "signed_at": "2025-01-22T08:45:00Z",
    "created_at": "2025-01-10T12:00:00Z"
  },
  "timestamp": "2025-01-22T08:45:03Z"
}
```
```

--------------------------------

### OpenAPI Specification for Get Reports for Overview

Source: https://docs.firstpromoter.com/api-reference-v2/api-admin/reports/get-reports-for-overview

Defines the GET request structure, required query parameters, and expected response schemas for the reports overview endpoint.

```yaml
openapi: 3.0.1
info:
  title: FirstPromoter Reports API
  version: '1.0'
  description: API documentation for FirstPromoter reporting endpoints
servers:
  - url: https://api.firstpromoter.com/api/v2/company
security:
  - BearerAuth: []
paths:
  /reports/overview:
    get:
      tags:
        - Reports
      summary: Get reports for overview
      description: |-
        Get reports for overview 
         <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/reports/overview`</Tip>
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: columns
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
              enum:
                - active_customers
                - monthly_churn
                - clicks_count
                - net_revenue_amount
                - revenue_amount
                - referrals_count
                - customers_count
                - sales_count
                - refunds_count
                - cancelled_customers_count
                - promoter_earnings_amount
                - non_link_customers
                - referrals_to_customers_cr
                - 3m_epc
                - 6m_epc
                - clicks_to_customers_cr
                - clicks_to_referrals_cr
                - promoter_paid_amount
                - signups_count
        - name: q
          in: query
          required: false
          schema:
            type: string
        - name: group_by
          in: query
          required: true
          schema:
            type: string
            enum:
              - day
              - week
              - month
              - year
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date-time
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date-time
        - name: sorting
          in: query
          required: false
          schema:
            type: object
            additionalProperties:
              type: string
              enum:
                - asc
                - desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    period:
                      type: string
                    id:
                      type: string
                    data:
                      type: object
                      properties:
                        revenue_amount:
                          type: number
                        net_revenue_amount:
                          type: number
                        promoter_earnings_amount:
                          type: number
                        customers_count:
                          type: integer
                        referrals_count:
                          type: integer
                        clicks_count:
                          type: integer
                        active_customers:
                          type: integer
                        3m_epc:
                          type: number
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
components:
  parameters:
    AccountId:
      name: Account-ID
      in: header
      required: true
      description: >-
        Account id. You can find your Account ID on Your FirstPromoter
        Dashboard. Navigate to Settings → Integrations
      schema:
        type: string
        example: acc_123456
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key passed as a Bearer token in the Authorization header. You can
        find your API Key on Your FirstPromoter Dashboard. Navigate to Settings
        → Integrations → Manage API Keys
```

--------------------------------

### GET https://api.firstpromoter.com/api/v2/company/batch_processes

Source: https://docs.firstpromoter.com/llms.txt

List all batch processes that are currently in progress.

```APIDOC
## GET https://api.firstpromoter.com/api/v2/company/batch_processes

### Description
List batch processes that are in progress.

### Method
GET

### Endpoint
https://api.firstpromoter.com/api/v2/company/batch_processes
```

--------------------------------

### Initialize FirstPromoter

Source: https://docs.firstpromoter.com/script-docs/fpr-js-docs

Initializes FirstPromoter with provided options. Use 'cid' for Company ID and 'ref_id' to track a specific promoter. Other options like 'tid', 'url', 'domain', and 'referrer' can also be set.

```javascript
fpr("init", {cid:"xxxxxxxx"});
```

--------------------------------

### fpr("init", options, callback?)

Source: https://docs.firstpromoter.com/script-docs/fpr-js-docs

Initializes FirstPromoter with the provided options. Most options are loaded automatically but can be overwritten. The 'ref_id' option is commonly used to track a specific promoter.

```APIDOC
## fpr("init", options, callback?)

This method initializes FirstPromoter with the provided options. Most of these options are loaded automatically when the script loads, but they can be overwritten by passing different ones to the method. The most used one is "ref_id" which forces the script to track a specific promoter.

### Parameters

#### options (object) - Required
  This object contains configuration settings for FirstPromoter.

  ##### Available keys

  | Property | Description                                              |
  | -------- | -------------------------------------------------------- |
  | cid      | FirstPromoter Company Id (required)                      |
  | ref_id   | Referral id/token of the promoter                        |
  | tid      | Tracking ID, value stored in fprom_tid cookie           |
  | url      | Current URL                                              |
  | domain   | Current domain                                           |
  | referrer | Browser referrer/ domain of the previous visited website |

  Setting properties that are not in the list above will be ignored.

#### callback (function) - Optional
  A function that will be called after the init function is triggered.
```

--------------------------------

### GET /api/v2/company/reports/overview

Source: https://docs.firstpromoter.com/llms.txt

Gets reports for overview.

```APIDOC
## GET /api/v2/company/reports/overview

### Description
Get reports for overview.

### Method
GET

### Endpoint
https://api.firstpromoter.com/api/v2/company/reports/overview
```

--------------------------------

### GET /api/v2/company/reports/urls

Source: https://docs.firstpromoter.com/llms.txt

Gets report data grouped by URLs.

```APIDOC
## GET /api/v2/company/reports/urls

### Description
With this endpoint you can get the report data grouped by URLs.

### Method
GET

### Endpoint
https://api.firstpromoter.com/api/v2/company/reports/urls
```

--------------------------------

### Initialize FirstPromoter with Ref ID from Query String Parameter 'sa'

Source: https://docs.firstpromoter.com/script-docs/advanced

This script retrieves a referral ID from the URL query parameter 'sa' and initializes FirstPromoter. If 'sa' is not found, it initializes with a default cid. It also calls `fpr('click')`.

```html
<script>(function(w){w.fpr=w.fpr||function(){w.fpr.q = w.fpr.q||[];w.fpr.q[arguments[0]=='set'?'unshift':'push'](arguments);};})(window);
function getParam(param) {
return new URLSearchParams(window.location.search).get(param);
}
var ref_id = getParam("sa");
if (ref_id) {
fpr("init", { ref_id, cid: "xxxxxx" });
} else {
fpr("init", { cid: "xxxxxx" });
}
fpr("click");
</script>
<script src="https://cdn.firstpromoter.com/fpr.js" async></script>
```

--------------------------------

### GET /api/v2/company/reports/promoters

Source: https://docs.firstpromoter.com/llms.txt

Gets report data grouped by promoters.

```APIDOC
## GET /api/v2/company/reports/promoters

### Description
With this endpoint you can get the report data grouped by promoters.

### Method
GET

### Endpoint
https://api.firstpromoter.com/api/v2/company/reports/promoters
```

--------------------------------

### Initialize Tracking Script with Proxy

Source: https://docs.firstpromoter.com/guides/proxy-setup

Include this script on your website to initialize tracking. Replace <your-account-id-here> with your actual account ID and uncomment the proxy URL variables if you used custom paths.

```html
    <script>
       // window.proxy_fpr_tr_url =`/tr`;
       // window.proxy_fpr_get_details_url=`/get_details`

        (function (w) { w.fpr = w.fpr || function () { w.fpr.q = w.fpr.q || []; w.fpr.q[arguments[0] == 'set' ? 'unshift' : 'push'](arguments); }; })(window);
        fpr("init", { cid: "<your-account-id-here>" });
        fpr("click");
    </script>
    <script src="/fpr-prox.js" defer async=""></script>
```

--------------------------------

### GET /api/v2/company/reports/campaigns

Source: https://docs.firstpromoter.com/llms.txt

Gets report data grouped by campaigns.

```APIDOC
## GET /api/v2/company/reports/campaigns

### Description
With this endpoint you can get the report data grouped by campaigns.

### Method
GET

### Endpoint
https://api.firstpromoter.com/api/v2/company/reports/campaigns
```

--------------------------------

### Retrieve access token from backend

Source: https://docs.firstpromoter.com/advanced/embed-dashboard-login

Examples for fetching the access token from the FirstPromoter API using different backend environments.

```js
const express = require("express");
const app = express();

app.get("/dashboard", async (req, res) => {
  const promoterId = req.user.firstpromoterPromoterId; // your stored promoter ID

  const response = await fetch(
    `https://v2.firstpromoter.com/api/v2/promoters/iframe_login?promoter_id=${promoterId}`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.FP_API_KEY}`,
        "Account-Id": process.env.FP_ACCOUNT_ID,
      },
    }
  );

  const { access_token } = await response.json();
  res.render("dashboard", { accessToken: access_token });
});
```

```php
<?php
$promoterId = $currentUser->firstpromoter_promoter_id;

$ch = curl_init(
  "https://v2.firstpromoter.com/api/v2/promoters/iframe_login?promoter_id=" . urlencode($promoterId)
);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . $_ENV["FP_API_KEY"],
  "Account-Id: " . $_ENV["FP_ACCOUNT_ID"],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

$accessToken = $response["access_token"];
?>
```

```sh
curl --request POST \
  --url 'https://v2.firstpromoter.com/api/v2/promoters/iframe_login?promoter_id=12345' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Account-Id: YOUR_ACCOUNT_ID'
```

--------------------------------

### Initialize FirstPromoter with Ref ID from URL Hash

Source: https://docs.firstpromoter.com/script-docs/advanced

This script extracts a referral ID from the URL's hash fragment and initializes FirstPromoter. If no hash is present, it initializes with a default cid. It also calls `fpr('click')` to track clicks.

```html
<script>
  (function(w){w.fpr=w.fpr||function(){w.fpr.q = w.fpr.q||[];w.fpr.q[arguments[0]=='set'?'unshift':'push'](arguments);};})(window);
  var fullUrl= window.location.href;
  if(fullUrl.includes("#")){
      fpr("init", {ref_id:fullUrl.split("#")[1],cid:"xxxxxxx"});
  }else{
      fpr("init", {cid:"xxxxxxx"});
  }
  fpr("click");
  </script>
```

--------------------------------

### Get Reports for Campaigns

Source: https://docs.firstpromoter.com/api-reference-v2/api-admin/reports/get-reports-for-campaigns

Retrieve report data grouped by campaigns using the specified GET endpoint.

```APIDOC
## GET /api/v2/company/reports/campaigns

### Description
With this endpoint you can get the report data grouped by campaigns.

### Method
GET

### Endpoint
https://api.firstpromoter.com/api/v2/company/reports/campaigns
```

--------------------------------

### Add Referral Tracking with User ID

Source: https://docs.firstpromoter.com/guides/integrate-your-website

This example shows how to pass both the user's email and a unique user ID (uid) to FirstPromoter for referral tracking. This helps link signups to specific affiliates.

```javascript
fpr("referral", {email: "actual_user@email.com", uid: "cus_12345"});
```

--------------------------------

### GET /payouts/group_by_promoters

Source: https://docs.firstpromoter.com/api-reference-v2/api-admin/payouts/get-all-payouts-grouped-by-promoters

Retrieves all payouts, grouped by promoters. This endpoint is useful for getting an overview of payouts associated with each promoter.

```APIDOC
## GET /payouts/group_by_promoters

### Description
This endpoint returns all payouts but grouped by promoters.

### Method
GET

### Endpoint
/payouts/group_by_promoters

### Parameters
#### Header Parameters
- **Account-ID** (string) - Required - Account identifier that specifies which account is making the request

#### Query Parameters
- **q** (string) - Optional - Search params. Searches by 'promoter.profile.first_name`, `promoter.profile.last_name`, `promoter.user.email`
- **filters[status]** (string) - Optional - Filter by status. Allowed values: `pending`, `completed`, `failed`, `processing`, `cancelled`
- **filters[campaign_id]** (integer or array of integers) - Optional - Campaign ids. Can be Integer or Array of Integers
- **include_payout_method_details** (boolean) - Optional - Set it true to include the payout_method_details
- **filters[min_payment]** (integer) - Optional - Filters payouts by the minimum payment amount possible
- **filters[invoiceable]** (string) - Optional - Filters payouts by invoiceable. Allowed values: `'true'`, `'false'`, `'not_set'`

### Response
#### Success Response (200)
- **data** (array) - Array of payout objects, each grouped by promoter.
  - **promoter** (object)
    - **id** (integer) - ID of the promoter
    - **email** (string) - Email of the promoter
    - **name** (string) - Name of the promoter
    - **invoice_details_status** (string) - Status of invoice details
    - **fraud_suspicions** (array of strings) - List of fraud suspicions
    - **profile** (object)
      - **invoice_details_validation_errors** (object) - Validation errors for invoice details
  - **payout_method** (object)
    - **id** (integer) - ID of the payout method
    - **method** (string) - Payout method name
    - **date_added** (string) - Date when the payout method was added
    - **is_disabled** (boolean) - Whether the payout method is disabled
    - **meta** (object)

#### Error Response (401)
- **error** (object) - Error details

#### Error Response (403)
- **error** (object) - Error details

### Request Example
```json
{
  "example": "GET /api/v2/company/payouts/group_by_promoters?filters[status]=completed&include_payout_method_details=true"
}
```

### Response Example
```json
{
  "example": {
    "data": [
      {
        "promoter": {
          "id": 123,
          "email": "promoter@example.com",
          "name": "John Doe",
          "invoice_details_status": "valid",
          "fraud_suspicions": [],
          "profile": {
            "invoice_details_validation_errors": {}
          }
        },
        "payout_method": {
          "id": 456,
          "method": "paypal",
          "date_added": "2023-01-01T10:00:00Z",
          "is_disabled": false,
          "meta": {}
        }
      }
    ]
  }
}
```
```

--------------------------------

### Initialize FirstPromoter with Ref ID from URL Query Parameter

Source: https://docs.firstpromoter.com/script-docs/advanced

This script retrieves a referral ID from the URL's query parameter 'aff' and initializes FirstPromoter. If 'aff' is not present, it initializes with a default cid. Ensure the `fpr.js` script is included.

```html
<script>(function (w) { w.fpr = w.fpr || function () { w.fpr.q = w.fpr.q || []; w.fpr.q[arguments[0] == 'set' ? 'unshift' : 'push'](arguments); }; })(window);

    function getQueryParameter(qParam) {
      var searchParams = new URL(document.location.toString()).searchParams;
      if (searchParams.has(qParam)) {
        return searchParams.get(qParam);
      }
    }

    var customRefValue = getQueryParameter("aff");
    if (customRefValue) {
      fpr("init", { ref_id: customRefValue, cid: "xxxxxx" });
    } else {
      fpr("init", { cid: "xxxxxxx" });
    }
  </script>
  <script src="https://cdn.firstpromoter.com/fpr.js" async></script>
```

--------------------------------

### OpenAPI Specification for Get Referrals

Source: https://docs.firstpromoter.com/api-reference-v2/api-admin/referrals/get-referrals

Defines the GET /referrals endpoint, including request parameters for filtering by date, state, type, and promoter ID.

```yaml
openapi: 3.0.0
info:
  title: FirstPromoter Admin API
  version: 1.0.0
  description: Admin API endpoints for managing referrals in FirstPromoter
servers:
  - url: https://api.firstpromoter.com/api/v2/company
    description: Production server
security:
  - BearerAuth: []
paths:
  /referrals:
    get:
      tags:
        - Referrals
      summary: Get available referrals
      description: |-
        Get available referrals 
         <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/referrals`</Tip>
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - in: query
          name: q
          schema:
            type: string
          description: Search params. Searches by email, uid, username, website
        - name: ids[]
          in: query
          description: Array of referral ids to get
          required: false
          schema:
            type: array
            items:
              type: integer
        - in: query
          name: filters[type]
          schema:
            type: string
            enum:
              - lead
              - customer
          description: Filter the referrals by type (lead or customer)
        - in: query
          name: filters[promoter_id]
          schema:
            type: string
          description: Filter the referrals by a promoter id
        - in: query
          name: filters[state]
          schema:
            type: string
            enum:
              - subscribed
              - signup
              - active
              - cancelled
              - refunded
              - denied
              - pending
              - moved
          description: Filter the referrals by state
        - in: query
          name: filters[customer_since][from]
          schema:
            type: string
            format: date
          description: >-
            Filter referrals where customer_since is on or after this date (ISO
            8601 format: YYYY-MM-DD)
        - in: query
          name: filters[customer_since][to]
          schema:
            type: string
            format: date
          description: >-
            Filter referrals where customer_since is on or before this date (ISO
            8601 format: YYYY-MM-DD)
        - in: query
          name: filters[created_at][from]
          schema:
            type: string
            format: date
          description: >-
            Filter referrals created on or after this date (ISO 8601 format:
            YYYY-MM-DD)
        - in: query
          name: filters[created_at][to]
          schema:
            type: string
            format: date
          description: >-
            Filter referrals created on or before this date (ISO 8601 format:
            YYYY-MM-DD)
        - in: query
          name: filters[cancelled_at][from]
          schema:
            type: string
            format: date
          description: >-
            Filter referrals cancelled on or after this date (ISO 8601 format:
            YYYY-MM-DD)
        - in: query
          name: filters[cancelled_at][to]
          schema:
            type: string
            format: date
          description: >-
            Filter referrals cancelled on or before this date (ISO 8601 format:
            YYYY-MM-DD)
      responses:
        '200':
          description: List of referrals
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Referral'
        '401':
          description: >-
            Unauthorized — the Bearer access token is missing, invalid, expired,
            or revoked. No JSON response body is returned.
          content:
            application/json:
              schema:
                type: object
              example: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    AccountId:
      name: Account-ID
      in: header
      required: true
      description: >-
        Account id. You can find your Account ID on Your FirstPromoter
        Dashboard. Navigate to Settings → Integrations
      schema:
        type: string
  schemas:
    Referral:
      type: object
      properties:
        id:
          type: integer
          description: Id of the referral
        email:
          type: string
          format: email
          description: Email address of the referral
        uid:
```

--------------------------------

### OpenAPI Specification for Get All Commissions

Source: https://docs.firstpromoter.com/api-reference-v2/api-admin/commissions/get-all-commissions

Defines the GET /commissions endpoint, including required headers, query parameters for filtering, and expected response structures.

```yaml
openapi: 3.0.1
info:
  title: FirstPromoter Commissions API
  version: 2.0.0
  description: API for managing commissions in FirstPromoter
servers:
  - url: https://api.firstpromoter.com/api/v2/company
security:
  - BearerAuth: []
paths:
  /commissions:
    get:
      tags:
        - Commissions
      summary: Get all commissions
      description: >-
        With this endpoint you can list all rewards and commissions assigned to
        a promotion, promoter, campaign or entire account using the API. 
         <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/commissions`</Tip>
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: q
          in: query
          description: Search params. Searches by event_id, referral.email, referral.uid
          schema:
            type: string
        - name: ids[]
          in: query
          description: Array of commission ids to get
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: filters
          in: query
          schema:
            $ref: '#/components/schemas/CommissionFilters'
        - name: sorting
          in: query
          schema:
            $ref: '#/components/schemas/CommissionSorting'
      responses:
        '200':
          description: Successfully retrieved commissions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Commission'
        '401':
          description: >-
            Unauthorized — the Bearer access token is missing, invalid, expired,
            or revoked. No JSON response body is returned.
          content:
            application/json:
              schema:
                type: object
              example: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    AccountId:
      name: Account-ID
      in: header
      required: true
      description: >-
        Account id. You can find your Account ID on Your FirstPromoter
        Dashboard. Navigate to Settings → Integrations
      schema:
        type: string
  schemas:
    CommissionFilters:
      type: object
      properties:
        status:
          type: string
          enum:
            - pending
            - approved
            - denied
        paid:
          type: string
          enum:
            - 'yes'
            - 'no'
          description: Paid filter for monetary commissions
        fulfilled:
          type: string
          enum:
            - 'yes'
            - 'no'
          description: Fulfilled filter for non-monetary commissions
        sale_amount:
          type: object
          properties:
            from:
              type: integer
              description: Sale amount from
            to:
              type: integer
              description: Sale amount to
        amount:
          type: object
          properties:
            from:
              type: integer
              description: Amount from
            to:
              type: integer
              description: Amount to
        created_at:
          type: object
          properties:
            from:
              type: string
              format: date
              description: created_at start date
            to:
              type: string
              format: date
              description: created_at end date
        campaign_id:
          oneOf:
            - type: integer
            - type: array
              items:
                type: integer
          description: Campaign ids. Can be Integer or Array of Integers
        payout_id:
          oneOf:
            - type: integer
            - type: array
              items:
                type: integer
          description: Payout ids. Can be Integer or Array of Integers
        due_period:
          type: string
          enum:
            - next
            - overdue
            - custom
          description: Due period filter
        promoter_id:
          type: integer
          description: Promoter id
        first_commission:
          type: boolean
          description: First commission
        refunded:
          type: boolean
          description: Refunded reward
        fraud_check:
```

--------------------------------

### Webhooks v2 Subscription Setup

Source: https://docs.firstpromoter.com/webhooks-v2/overview

This section details the fields required to set up a new webhook subscription.

```APIDOC
## POST /webhooks/subscriptions

### Description
Creates a new webhook subscription to receive real-time event notifications.

### Method
POST

### Endpoint
/webhooks/subscriptions

### Parameters
#### Request Body
- **url** (string) - Required - The HTTPS endpoint that will receive webhook payloads. Must be a valid URL.
- **event_types** (array) - Required - One or more event type strings to subscribe to. See [Event Types](/webhooks-v2/event-types) for the full list.
- **campaign_ids** (array) - Optional - Limit this subscription to events from specific campaigns. Use `[1]` (the default) to receive events from all campaigns.
- **description** (string) - Optional - Optional human-readable label for this subscription.
- **active** (boolean) - Optional - Enable or pause delivery without deleting the subscription. Defaults to `true`.
- **headers** (object) - Optional - Custom HTTP headers to include on every request. Useful for API keys or authorization tokens your endpoint requires.

### Request Example
{
  "url": "https://example.com/webhook",
  "event_types": ["referral.created", "user.registered"],
  "campaign_ids": [123],
  "description": "My custom webhook",
  "active": true,
  "headers": {
    "Authorization": "Bearer my-token",
    "X-My-Header": "value"
  }
}

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the subscription.
- **url** (string) - The configured webhook URL.
- **event_types** (array) - The subscribed event types.
- **campaign_ids** (array) - The campaign IDs this subscription applies to.
- **description** (string) - The description of the subscription.
- **active** (boolean) - The active status of the subscription.
- **headers** (object) - The custom headers configured for the subscription.
- **created_at** (string) - The timestamp when the subscription was created.

#### Response Example
{
  "id": "sub_abc123",
  "url": "https://example.com/webhook",
  "event_types": ["referral.created", "user.registered"],
  "campaign_ids": [123],
  "description": "My custom webhook",
  "active": true,
  "headers": {
    "Authorization": "Bearer my-token",
    "X-My-Header": "value"
  },
  "created_at": "2023-10-27T10:00:00Z"
}
```

--------------------------------

### Initialize fpr.js and Track Clicks

Source: https://docs.firstpromoter.com/guides/tracking-with-fprjs

Add these scripts to your website to initialize FirstPromoter tracking and automatically track visitor clicks. Replace '<your-account-id-here>' with your actual account ID.

```html
<script>
    (function (w) { w.fpr = w.fpr || function () { w.fpr.q = w.fpr.q || []; w.fpr.q[arguments[0] == 'set' ? 'unshift' : 'push'](arguments); }; })(window);
    fpr("init", { cid: "<your-account-id-here>" });
    fpr("click");
</script>
<script src="https://cdn.firstpromoter.com/fpr.js" async></script>
```

--------------------------------

### Include fpr.js in HTML

Source: https://docs.firstpromoter.com/script-docs/fpr-js-docs

Add this script to the HEAD section of your website for global tracking. It initializes FirstPromoter and loads the library asynchronously.

```html
<script>(function(w){w.fpr=w.fpr||function(){w.fpr.q = w.fpr.q||[];w.fpr.q[arguments[0]=='set'?'unshift':'push'](arguments);}})(window);
fpr("init", {cid:"xxxxxxxx"}); 
fpr("click");</script>
<script src="https://cdn.firstpromoter.com/fpr.js" async></script>
```

--------------------------------

### GET /api/v2/company/payouts/stats

Source: https://docs.firstpromoter.com/llms.txt

Returns statistics about payouts.

```APIDOC
## GET /api/v2/company/payouts/stats

### Description
This endpoint returns statistics about payouts.

### Method
GET

### Endpoint
https://api.firstpromoter.com/api/v2/company/payouts/stats
```

--------------------------------

### Report a signup via FirstPromoter API

Source: https://docs.firstpromoter.com/guides/mobile-deep-linking

Use this request to track a new user signup. Send either email or uid, and include the ref_id captured from the mobile app.

```sh
curl --request POST \
  --url https://api.firstpromoter.com/api/v2/track/signup \
  --header 'Account-ID: YOUR_ACCOUNT_ID' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "customer@email.com",
    "uid": "cus_12345",
    "ref_id": "joe13",
    "skip_email_notification": true
}'
```

--------------------------------

### GET /api/v2/company/promo_codes

Source: https://docs.firstpromoter.com/llms.txt

Lists all promo codes.

```APIDOC
## GET /api/v2/company/promo_codes

### Description
With this endpoint you can list all promo codes.

### Method
GET

### Endpoint
https://api.firstpromoter.com/api/v2/company/promo_codes
```

--------------------------------

### GET /api/v2/company/promoters

Source: https://docs.firstpromoter.com/llms.txt

Lists all available promoters.

```APIDOC
## GET /api/v2/company/promoters

### Description
Retrieves a list of all promoters associated with the company.

### Method
GET

### Endpoint
https://api.firstpromoter.com/api/v2/company/promoters
```

--------------------------------

### Render iframe in frontend

Source: https://docs.firstpromoter.com/advanced/embed-dashboard-login

Examples for fetching the token from your backend and rendering the iframe in React, Vue, and Vanilla JS.

```jsx
import { useEffect, useState } from "react";

export function PromoterDashboard() {
  const [token, setToken] = useState(null);

  useEffect(() => {
    fetch("/api/fp-token")
      .then((res) => res.json())
      .then((data) => setToken(data.token));
  }, []);

  if (!token) return <p>Loading dashboard…</p>;

  return (
    <iframe
      src={`https://your.custom.domain/iframe?tk=${token}`}
      allow="clipboard-write"
      width="100%"
      height="850px"
      frameBorder="0"
    />
  );
}
```

```vue
<template>
  <iframe
    v-if="token"
    :src="`https://your.custom.domain/iframe?tk=${token}`"
    allow="clipboard-write"
    width="100%"
    height="850px"
    frameborder="0"
  />
  <p v-else>Loading dashboard…</p>
</template>

<script setup>
import { ref, onMounted } from "vue";

const token = ref(null);

onMounted(async () => {
  const res = await fetch("/api/fp-token");
  const data = await res.json();
  token.value = data.token;
});
</script>
```

```html
<div id="fp-dashboard"></div>

<script>
  fetch("/api/fp-token")
    .then((res) => res.json())
    .then(({ token }) => {
      const iframe = document.createElement("iframe");
      iframe.src = `https://your.custom.domain/iframe?tk=${token}`;
      iframe.allow = "clipboard-write";
      iframe.width = "100%";
      iframe.height = "850px";
      iframe.frameBorder = "0";
      document.getElementById("fp-dashboard").appendChild(iframe);
    });
</script>
```

--------------------------------

### GET /api/v2/company/payouts/group_by_promoters

Source: https://docs.firstpromoter.com/llms.txt

Returns all payouts grouped by promoters.

```APIDOC
## GET /api/v2/company/payouts/group_by_promoters

### Description
This endpoint returns all payouts but grouped by promoters.

### Method
GET

### Endpoint
https://api.firstpromoter.com/api/v2/company/payouts/group_by_promoters
```

--------------------------------

### Track Lead/Signup with cURL

Source: https://docs.firstpromoter.com/guides/tracking-without-fprjs

Use this cURL command to send lead or signup data to the FirstPromoter API. You can provide email, uid, or both. Ensure actual visitor data is included in the API call.

```sh
curl --request POST \
  --url https://api.firstpromoter.com/api/v2/track/signup \
  --header 'Account-ID: <account-id>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ \
	  "email": "customer1@gmail.com", \
	  "uid": "cus_000001", \
	  "ref_id": "joe13", \
	  "skip_email_notification": true \
}'
```

--------------------------------

### GET /api/v2/company/referrals

Source: https://docs.firstpromoter.com/llms.txt

Retrieves a list of available referrals.

```APIDOC
## GET /api/v2/company/referrals

### Description
Fetches all available referrals for the company.

### Method
GET

### Endpoint
https://api.firstpromoter.com/api/v2/company/referrals
```

--------------------------------

### GET /api/v2/company/promoters/{id}

Source: https://docs.firstpromoter.com/llms.txt

Retrieves details for a specific promoter.

```APIDOC
## GET /api/v2/company/promoters/{id}

### Description
Fetches the details of a specific promoter by their ID.

### Method
GET

### Endpoint
https://api.firstpromoter.com/api/v2/company/promoters/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the promoter.
```

--------------------------------

### FirstPromoter Tracking Script Integration

Source: https://docs.firstpromoter.com/guides/proxy-setup

Add this script to your website to initialize tracking, replacing the placeholder worker URL and account ID.

```html
    <script>
        const WORKER_URL = "<worker-url-here>";
        window.proxy_fpr_tr_url =`${WORKER_URL}/tr`;
        window.proxy_fpr_get_details_url=`${WORKER_URL}/get_details`

        (function (w) { w.fpr = w.fpr || function () { w.fpr.q = w.fpr.q || []; w.fpr.q[arguments[0] == 'set' ? 'unshift' : 'push'](arguments); }; })(window);
        fpr("init", { cid: "<your-account-id-here>" });
        fpr("click");
    </script>
    <script src="/fpr-prox.js" defer async=""></script>
```

--------------------------------

### GET /api/v2/company/referrals/{id}

Source: https://docs.firstpromoter.com/llms.txt

Retrieves details for a specific referral.

```APIDOC
## GET /api/v2/company/referrals/{id}

### Description
Fetches details for a specific referral identified by its ID.

### Method
GET

### Endpoint
https://api.firstpromoter.com/api/v2/company/referrals/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the referral.
```

--------------------------------

### Track Sales via FirstPromoter API

Source: https://docs.firstpromoter.com/guides/integrate-your-website

Use this cURL command to send a sale event to FirstPromoter from your backend. Ensure you replace 'YOUR_ACCOUNT_ID' and 'YOUR_API_KEY' with your actual credentials. The 'sale_amount' is in cents.

```sh
curl --request POST \
  --url https://api.firstpromoter.com/api/v2/track/sale \
  --header 'Account-ID: YOUR_ACCOUNT_ID' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ \
    "email": "customer@email.com", \
    "uid": "cus_12345", \
    "sale_amount": 4900, \
    "currency": "usd", \
    "order_id": "order_001" \
  }'
```

--------------------------------

### GET https://api.firstpromoter.com/api/v2/company/reports/overview

Source: https://docs.firstpromoter.com/api-reference-v2/api-admin/reports/get-reports-for-overview

Retrieves the report overview for the company.

```APIDOC
## GET https://api.firstpromoter.com/api/v2/company/reports/overview

### Description
Retrieves the report overview for the company.

### Method
GET

### Endpoint
https://api.firstpromoter.com/api/v2/company/reports/overview
```
Tokens:
Raw