> ## 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.
# Get available referrals
> Get available referrals
**HTTP Request**
`GET https://api.firstpromoter.com/api/v2/company/referrals`
## OpenAPI
````yaml openapi-v2-referrals get /referrals
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
**HTTP Request**
`GET https://api.firstpromoter.com/api/v2/company/referrals`
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
'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:
type: string
description: uid of the referral
state:
type: string
enum:
- subscribed
- signup
- active
- cancelled
- refunded
- denied
- pending
- moved
description: State of the referral
metadata:
type: object
description: Additional metadata of the referral
entry_source:
type: string
enum:
- api
- coupon
- cookie
- manual_admin
- manual_affiliate
description: >-
Entry source of the referral. This shows where the referral was
captured from.
**Cookie** is set if the referral was captured using the tid cookie,
**Coupon** is for when the referral is captured via a coupon code.
**Manual admin** is for when the referral is added manually by an
admin.
**Manual affiliate** is for when the referral is added manually by
an affiliate.
created_at:
type: string
format: date-time
description: Date and time when the referral was created
customer_since:
type: string
format: date-time
nullable: true
description: Date and time when the referral became a customer
promoter_campaign:
$ref: '#/components/schemas/PromoterCampaign'
fraud_check:
type: string
enum:
- no_suspicion
- same_ip_suspicion
- same_promoter_email
- ad_source
description: >-
Fraud check (suspicion) status of the referral. `no_suspicion` means
the referral is clean or was manually cleared. `same_ip_suspicion`
means the referral shares an IP with the promoter.
`same_promoter_email` means the referral email matches the promoter
email. `ad_source` means the referral arrived via a paid ad click.
created_by_user_email:
type: string
format: email
nullable: true
description: Email address of the user who created the referral
username:
type: string
nullable: true
description: Username chosen by the referral
split_details:
type: array
nullable: true
description: >-
The commission split configuration for this referral. Each entry
represents a split partner. The primary promoter (the referral
owner) receives the remainder of the commission after all split
percentages are applied.
items:
type: object
properties:
promoter_campaign_id:
type: integer
description: The ID of the split partner's campaign enrollment
promoter_id:
type: integer
description: The ID of the split partner (promoter)
percentage:
type: integer
description: The percentage of each commission this promoter receives
first_name:
type: string
nullable: true
last_name:
type: string
nullable: true
website:
type: string
nullable: true
comment:
type: string
nullable: true
description: Internal note or comment on this referral
is_expired:
type: boolean
description: Whether the referral has expired
Error:
type: object
properties:
message:
type: string
code:
type: string
errors:
type: object
additionalProperties:
type: array
items:
type: string
PromoterCampaign:
type: object
properties:
id:
type: integer
description: Id of the promoter campaign
campaign_id:
type: integer
description: Id of the campaign
promoter_id:
type: integer
description: Id of the promoter
created_at:
type: string
format: date-time
description: Date and time when the promoter campaign was created
promoter:
$ref: '#/components/schemas/Promoter'
campaign:
$ref: '#/components/schemas/Campaign'
Promoter:
type: object
properties:
id:
type: integer
description: Id of the promoter
email:
type: string
format: email
description: Email address of the promoter
name:
type: string
description: Name of the promoter
Campaign:
type: object
properties:
id:
type: integer
description: Id of the campaign
name:
type: string
description: Name of the campaign
color:
type: string
nullable: true
description: Color assigned to the campaign
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
````