> ## 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 promoter details
> With this endpoint you can get the details of a promoter.
**HTTP Request**
`GET https://api.firstpromoter.com/api/v2/company/promoters/{id}`
## OpenAPI
````yaml openapi-v2-promoters get /promoters/{id}
openapi: 3.0.1
info:
title: FirstPromoter API
version: '1.0'
description: API documentation for FirstPromoter promoters management
servers:
- url: https://api.firstpromoter.com/api/v2/company
security:
- BearerAuth: []
paths:
/promoters/{id}:
get:
tags:
- Promoters
summary: Get promoter details
description: |-
With this endpoint you can get the details of a promoter.
**HTTP Request**
`GET https://api.firstpromoter.com/api/v2/company/promoters/{id}`
operationId: getPromoter
parameters:
- $ref: '#/components/parameters/AccountId'
- name: id
description: >-
The promoter's numeric ID, or the value of the attribute specified
in `find_by` (e.g. an email address, auth token, ref token, promo
code, or cust_id)
in: path
required: true
schema:
type: string
- name: find_by
in: query
description: Find by attribute
schema:
type: string
enum:
- email
- cust_id
- auth_token
- ref_token
- promo_code
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Promoter'
'401':
description: Unauthorized
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:
Promoter:
type: object
properties:
id:
type: integer
description: Id of the promoter
email:
type: string
description: Email address of the promoter
name:
type: string
description: Full name of the promoter
cust_id:
type: string
nullable: true
description: Cust ID of the promoter
note:
type: string
nullable: true
description: Optional note about the promoter
stats:
type: object
description: Performance statistics for the promoter
properties:
clicks_count:
type: integer
description: Number of clicks generated
referrals_count:
type: integer
description: Number of referrals generated
sales_count:
type: integer
description: Number of sales generated
customers_count:
type: integer
description: Number of customers referred
revenue_amount:
type: integer
description: Total revenue generated
active_customers_count:
type: integer
description: Number of active customers
is_customized:
type: boolean
description: Whether the promoter has customized settings
fraud_suspicions:
type: array
description: List of potential fraud flags
items:
type: string
is_confirmed:
type: boolean
description: Whether the promoter has confirmed their account
invoice_details_status:
type: string
description: Status of the promoter's invoice details
enum:
- pending
- approved
- denied
profile:
$ref: '#/components/schemas/PromoterProfile'
joined_at:
type: string
format: date-time
description: Date and time when the promoter joined.
last_login_at:
type: string
format: date-time
nullable: true
description: Date and time of the promoter's last login.
archived_at:
type: string
format: date-time
nullable: true
description: Date and time when the promoter was archived, if applicable.
custom_fields:
type: object
nullable: true
description: >-
Custom fields for the promoter, based on company settings. This is a
key-value pair object where keys are custom field identifiers and
values are the corresponding data.
password_setup_url:
type: string
nullable: true
description: URL for the promoter to set up their password
first_event_at:
type: string
format: date-time
description: Date and time of the promoter's first activity.
promoter_campaigns:
type: array
description: List of campaigns associated with the promoter
items:
type: object
properties:
id:
type: integer
description: ID of the promoter-campaign association
campaign_id:
type: integer
description: ID of the campaign
promoter_id:
type: integer
description: ID of the promoter
state:
type: string
description: State of the promoter in this campaign
enum:
- pending
- accepted
- rejected
- blocked
- inactive
- not_set
created_at:
type: string
format: date-time
description: When the promoter was added to the campaign
campaign:
type: object
properties:
id:
type: integer
description: ID of the campaign
name:
type: string
description: Name of the campaign
color:
type: string
description: Color code associated with the campaign
coupon:
type: string
description: Coupon code for this campaign
ref_token:
type: string
description: Referral token for this campaign
ref_link:
type: string
description: Referral link for this campaign
balances:
type: object
description: Earnings balance breakdown for the promoter
properties:
cash:
type: number
nullable: true
credits:
type: number
nullable: true
points:
type: number
nullable: true
free_months:
type: number
nullable: true
discount:
type: number
nullable: true
track_ad_traffic:
type: boolean
nullable: true
description: >-
Whether ad traffic tracking is enabled for this promoter. Null means
the campaign default is used.
auth_provider:
type: string
nullable: true
description: >-
OAuth provider used to authenticate (e.g. google). Null if using
email/password.
selected_payout_method:
type: object
nullable: true
description: >-
The promoter's currently selected payout method. Omitted when the
`exclude_payout_method=true` query parameter is set.
properties:
id:
type: integer
method:
type: string
date_added:
type: string
format: date-time
is_disabled:
type: boolean
parent_promoter:
type: object
nullable: true
description: >-
The parent promoter (for sub-affiliate relationships). Only included
when the `include_parent_promoter=true` query parameter is set.
properties:
id:
type: integer
email:
type: string
name:
type: string
nullable: true
PromoterProfile:
type: object
properties:
id:
type: integer
description: ID of the profile
first_name:
type: string
description: First name of the promoter
last_name:
type: string
description: Last name of the promoter
website:
type: string
nullable: true
description: Website of the promoter
company_name:
type: string
nullable: true
description: Company name of the promoter
company_number:
type: string
nullable: true
description: Company registration number
phone_number:
type: string
nullable: true
description: Phone number of the promoter
vat_id:
type: string
nullable: true
description: VAT ID of the promoter
country:
type: string
nullable: true
description: Country in 2 characters format
example: US
address:
type: string
nullable: true
description: Address of the promoter
avatar:
type: string
description: URL to the promoter's avatar image
w8_form_url:
type: string
nullable: true
description: URL to the promoter's W8 form if available
w9_form_url:
type: string
nullable: true
description: URL to the promoter's W9 form if available
description:
type: string
nullable: true
description: Description of the promoter
invoice_details_validation_errors:
type: object
nullable: true
description: Validation errors for invoice details
should_validate_invoice_details:
type: boolean
description: Should validate invoice details
instagram_url:
type: string
nullable: true
description: Promoter's Instagram URL
youtube_url:
type: string
nullable: true
description: Promoter's YouTube URL
linkedin_url:
type: string
nullable: true
description: Promoter's LinkedIn URL
facebook_url:
type: string
nullable: true
description: Promoter's Facebook URL
twitter_url:
type: string
nullable: true
description: Promoter's Twitter URL
twitch_url:
type: string
nullable: true
description: Promoter's Twitch URL
tiktok_url:
type: string
nullable: true
description: Promoter's TikTok URL
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 section → Manage API Keys
````