--- title: "Get available promoters" method: GET path: "/promoters" tags: ["Promoters"] --- # Get available promoters `GET /promoters` With this endpoint you can list all promoters. **HTTP Request**
`GET https://api.firstpromoter.com/api/v2/company/promoters` ## Query parameters - `q` string - `ids[]` integer[] - `filters` PromoterFilters - `revenue_amount` object — Revenue amount filter - `from` integer — Minimum revenue amount - `to` integer — Maximum revenue amount - `customers_count` object — Customers count filter - `from` integer — Minimum customers count - `to` integer — Maximum customers count - `referrals_count` object — Referrals count filter - `from` integer — Minimum referrals count - `to` integer — Maximum referrals count - `clicks_count` object — Clicks count filter - `from` integer — Minimum clicks count - `to` integer — Maximum clicks count - `joined_at` object — Joined at filter - `from` string, date — Minimum joined at date, ISO date format (YYYY-MM-DD HH:MM:SS) - `to` string, date — Maximum joined at date, ISO date format (YYYY-MM-DD HH:MM:SS) - `last_login_at` object — Last login at filter - `from` string, date — Minimum last login at date, ISO date format (YYYY-MM-DD HH:MM:SS) - `to` string, date — Maximum last login at date, ISO date format (YYYY-MM-DD HH:MM:SS) - `campaign_id` union - integer — Campaign id - integer[] — Array of campaign ids - `state` 'pending' | 'accepted' | 'rejected' | 'blocked' | 'inactive' | 'not_set' — Promoter state filter - `has_wform` 'yes' | 'no' — Has wform filter - `parent_promoter_id` integer — Parent promoter id - `archived` 'true' | 'false' | '`true`' | '`false`' | '`yes`' | '`no`' — Archived filter - `subscribed_to_email` 'true' | 'false' | '`true`' | '`false`' | '`yes`' | '`no`' — Subscribed to email filter - `custom_field1` CustomFieldFilter - `key` string, required — The key custom_field key - `operator` 'exact' | 'partial', required — The custom field operator - `value` union, required — The value of the custom field. Must be String or Array of strings - string - string[] - `custom_field2` CustomFieldFilter - `key` string, required — The key custom_field key - `operator` 'exact' | 'partial', required — The custom field operator - `value` union, required — The value of the custom field. Must be String or Array of strings - string - string[] - `fraud_suspicions` string[] - `inactivity` object — Filter promoters by inactivity — promoters who have not performed the specified metric within the given number of days - `metric` 'referral' | 'customer' | 'click' | 'sale' — The activity metric to measure inactivity against - `days` integer — Number of days of inactivity - `invoice_details_status` 'approved' | 'pending' | 'rejected' | 'not_submitted' — Filter promoters by their invoice details status - `sorting` object - `clicks_count` 'asc' | 'desc' - `referrals_count` 'asc' | 'desc' - `customers_count` 'asc' | 'desc' - `revenue_amount` 'asc' | 'desc' - `joined_at` 'asc' | 'desc' ## Headers - `Account-ID` string, required ## Response `200` Successful response - object - `data` PromoterListItem[] — List of Promoters - `id` integer — Id of the promoter - `email` string — Email address of the promoter - `name` string — Full name of the promoter - `cust_id` string, nullable — Cust ID of the promoter - `note` string, nullable — Optional note about the promoter - `stats` object — Performance statistics for the promoter - `clicks_count` integer — Number of clicks generated - `referrals_count` integer — Number of referrals generated - `sales_count` integer — Number of sales generated - `customers_count` integer — Number of customers referred - `revenue_amount` integer — Total revenue generated - `active_customers_count` integer — Number of active customers - `is_customized` boolean — Whether the promoter has customized settings - `fraud_suspicions` string[] — List of potential fraud flags - `is_confirmed` boolean — Whether the promoter has confirmed their account - `invoice_details_status` 'pending' | 'approved' | 'denied' — Status of the promoter's invoice details - `profile` PromoterProfile - `id` integer — ID of the profile - `first_name` string — First name of the promoter - `last_name` string — Last name of the promoter - `website` string, nullable — Website of the promoter - `company_name` string, nullable — Company name of the promoter - `company_number` string, nullable — Company registration number - `phone_number` string, nullable — Phone number of the promoter - `vat_id` string, nullable — VAT ID of the promoter - `country` string, nullable — Country in 2 characters format - `address` string, nullable — Address of the promoter - `avatar` string — URL to the promoter's avatar image - `w8_form_url` string, nullable — URL to the promoter's W8 form if available - `w9_form_url` string, nullable — URL to the promoter's W9 form if available - `description` string, nullable — Description of the promoter - `invoice_details_validation_errors` object, nullable — Validation errors for invoice details - `should_validate_invoice_details` boolean — Should validate invoice details - `instagram_url` string, nullable — Promoter's Instagram URL - `youtube_url` string, nullable — Promoter's YouTube URL - `linkedin_url` string, nullable — Promoter's LinkedIn URL - `facebook_url` string, nullable — Promoter's Facebook URL - `twitter_url` string, nullable — Promoter's Twitter URL - `twitch_url` string, nullable — Promoter's Twitch URL - `tiktok_url` string, nullable — Promoter's TikTok URL - `joined_at` string, date-time — Date and time when the promoter joined. - `last_login_at` string, date-time, nullable — Date and time of the promoter's last login. - `archived_at` string, date-time, nullable — Date and time when the promoter was archived, if applicable. - `custom_fields` object, nullable — 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` string, nullable — URL for the promoter to set up their password - `first_event_at` string, date-time — Date and time of the promoter's first activity. - `promoter_campaigns` object[] — List of campaigns associated with the promoter - `id` integer — ID of the promoter-campaign association - `campaign_id` integer — ID of the campaign - `promoter_id` integer — ID of the promoter - `state` 'pending' | 'accepted' | 'rejected' | 'blocked' | 'inactive' | 'not_set' — State of the promoter in this campaign - `created_at` string, date-time — When the promoter was added to the campaign - `campaign` object - `id` integer — ID of the campaign - `name` string — Name of the campaign - `color` string — Color code associated with the campaign - `coupon` string — Coupon code for this campaign - `ref_token` string — Referral token for this campaign - `ref_link` string — Referral link for this campaign - `balances` object — Earnings balance breakdown for the promoter - `cash` number, nullable - `credits` number, nullable - `points` number, nullable - `free_months` number, nullable - `discount` number, nullable - `track_ad_traffic` boolean, nullable — Whether ad traffic tracking is enabled for this promoter. Null means the campaign default is used. - `auth_provider` string, nullable — OAuth provider used to authenticate (e.g. google). Null if using email/password. - `selected_payout_method` object, nullable — The promoter's currently selected payout method. Omitted when the `exclude_payout_method=true` query parameter is set. - `id` integer - `method` string - `date_added` string, date-time - `is_disabled` boolean - `meta` object - `pending_count` integer ## Other responses - `401` — Unauthorized --- [API](https://skmtc.net/firstpromoter/apis/firstpromoter-batch-processes-api.md) · [All operations](https://skmtc.net/firstpromoter/apis/firstpromoter-batch-processes-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/firstpromoter/firstpromoter-batch-processes-api/versions/e15f0d026ccf/schema)