FirstPromoter Campaigns API - 5 operation(s) on the admin (api/v2/company) surface, from FirstPromoter's own published OpenAPI definition (3.0.1) indexed in https://docs.firstpromoter.com/llms.txt.
openapi: 3.0.1
info:
title: FirstPromoter Campaigns API
version: 2.0.0
description: API for managing campaigns in FirstPromoter
servers:
- url: https://api.firstpromoter.com/api/v2/company
security:
- BearerAuth: []
paths:
/campaigns:
get:
summary: Get all campaigns
tags:
- Campaigns
description: "With this endpoint you can list all campaigns. \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/campaigns`</Tip>"
parameters:
- $ref: '#/components/parameters/AccountId'
responses:
'200':
description: List of campaigns retrieved successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Campaign'
'401':
description: Unauthorized
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message
code:
type: string
description: Error code
post:
summary: Create a campaign
tags:
- Campaigns
description: "With this endpoint you can create a campaign. \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/campaigns`</Tip>"
parameters:
- $ref: '#/components/parameters/AccountId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignCreate'
responses:
'201':
description: Campaign created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'400':
description: Invalid parameters
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message
errors:
type: object
description: Validation errors by field
code:
type: string
description: Error code
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message
code:
type: string
description: Error code
/campaigns/{id}:
get:
summary: Get a campaign
tags:
- Campaigns
description: With this endpoint you can get a campaign.<Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/campaigns/{id}`</Tip>
parameters:
- $ref: '#/components/parameters/AccountId'
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Campaign retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'401':
description: Unauthorized
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message
code:
type: string
description: Error code
'404':
description: Campaign not found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message
code:
type: string
description: Error code
put:
summary: Update a campaign
tags:
- Campaigns
description: "With this endpoint you can update a campaign. \n <Tip>**HTTP Request** <br/>`PUT https://api.firstpromoter.com/api/v2/company/campaigns/{id}`</Tip>"
parameters:
- $ref: '#/components/parameters/AccountId'
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignUpdate'
responses:
'200':
description: Campaign updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'401':
description: Unauthorized
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message
code:
type: string
description: Error code
'404':
description: Campaign not found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message
code:
type: string
description: Error code
delete:
summary: Delete a campaign
tags:
- Campaigns
description: "With this endpoint you can delete a campaign. \n <Tip>**HTTP Request** <br/>`DELETE https://api.firstpromoter.com/api/v2/company/campaigns/{id}`</Tip>"
parameters:
- $ref: '#/components/parameters/AccountId'
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Campaign deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'401':
description: Unauthorized
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message
code:
type: string
description: Error code
'404':
description: Campaign not found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message
code:
type: string
description: Error code
components:
parameters:
AccountId:
name: Account-ID
in: header
required: true
description: Account identifier that specifies which account is making the request
schema:
type: string
example: acc_123456
schemas:
Campaign:
type: object
properties:
id:
type: integer
description: Campaign ID
name:
type: string
description: Campaign name
color:
type: string
description: Campaign color
stats:
type: object
properties:
referrals_count:
type: integer
description: Number of referrals in this campaign
sales_count:
type: integer
description: Number of sales in this campaign
customers_count:
type: integer
description: Number of customers in this campaign
promoters_count:
type: integer
description: Number of promoters in this campaign
revenue_amount:
type: integer
description: Total revenue in this campaign
landing_url:
type: string
description: Landing URL for the campaign
visitor_cookie_life:
type: integer
description: Visitor cookie lifetime in days
ref_token_param:
type: string
description: Referral token parameter
auto_approve_leads:
type: boolean
description: Whether to auto-approve leads
track_ad_traffic:
type: string
enum:
- pending
- allow
- block
description: How to handle ad traffic
auto_approve_promoters:
type: boolean
description: Whether to auto-approve promoters
is_private:
type: boolean
description: Whether the campaign is private
is_default:
type: boolean
description: Whether this is the default campaign
upgrade_details:
type: object
properties:
campaign_id:
type: integer
description: ID of the campaign to upgrade to
amount:
type: integer
description: Amount needed to trigger the upgrade
metric:
type: string
enum:
- customers
- revenue
- active_customers
description: Metric used for the upgrade
move_referrals_on_level_change:
type: boolean
description: Whether to move referrals when level changes
signup_url:
type: string
description: URL for promoters to sign up
links:
type: array
items:
type: object
properties:
id:
type: integer
description: Link ID
name:
type: string
description: Link name
url:
type: string
description: Link URL
rewards_for_promoters:
type: array
items:
type: object
properties:
apply_on:
type: string
enum:
- monthly
- yearly
- one_time
- all
- specific
description: When the reward applies
product_ids:
type: array
items:
type: integer
description: IDs of products this reward applies to
reward_id:
type: integer
description: ID of the reward
reward:
type: object
properties:
name:
type: string
description: Name of the reward
promoter_reward_type:
type: string
description: Type of promoter reward
hide_reward:
type: boolean
description: Whether to hide the reward
tier_level:
type: integer
description: Tier level of the reward
coupon:
type: string
description: Coupon code for the reward
products:
type: array
items:
type: object
properties:
id:
type: integer
description: Product ID
name:
type: string
description: Product name
rewards_for_referrals:
type: array
items:
type: object
properties:
apply_on:
type: string
enum:
- monthly
- yearly
- one_time
- all
- specific
description: When the reward applies
product_ids:
type: array
items:
type: integer
description: IDs of products this reward applies to
reward_id:
type: integer
description: ID of the reward
reward:
type: object
properties:
name:
type: string
description: Name of the reward
promoter_reward_type:
type: string
description: Type of promoter reward
hide_reward:
type: boolean
description: Whether to hide the reward
tier_level:
type: integer
description: Tier level of the reward
coupon:
type: string
description: Coupon code for the reward
products:
type: array
items:
type: object
properties:
id:
type: integer
description: Product ID
name:
type: string
description: Product name
Link:
type: object
required:
- name
- url
properties:
id:
type: integer
name:
type: string
url:
type: string
_destroy:
type: boolean
UpgradeDetails:
type: object
required:
- campaign_id
- amount
- metric
properties:
campaign_id:
type: integer
amount:
type: integer
metric:
type: string
enum:
- customers
- revenue
Reward:
type: object
required:
- apply_on
- product_ids
- reward_id
properties:
apply_on:
type: string
enum:
- monthly
- yearly
- one_time
- all
- specific
product_ids:
type: array
items: {}
reward_id:
type: integer
CampaignCreate:
type: object
required:
- name
- landing_url
- ref_token_param
- visitor_cookie_life
properties:
name:
type: string
landing_url:
type: string
ref_token_param:
type: string
enum:
- ?fpr
- ?via
- ?fp_ref
- ?deal
- ?ref
- ?_from
- ?_by
- ?_go
color:
type: string
visitor_cookie_life:
type: integer
auto_approve_promoters:
type: boolean
is_private:
type: boolean
track_ad_traffic:
type: string
enum:
- pending
- allow
- block
links:
type: array
items:
$ref: '#/components/schemas/Link'
upgrade_details:
$ref: '#/components/schemas/UpgradeDetails'
rewards_for_promoters:
type: array
items:
$ref: '#/components/schemas/Reward'
rewards_for_referrals:
type: array
items:
$ref: '#/components/schemas/Reward'
CampaignUpdate:
type: object
properties:
name:
type: string
landing_url:
type: string
ref_token_param:
type: string
enum:
- ?fpr
- ?via
- ?fp_ref
- ?deal
- ?ref
- ?_from
- ?_by
- ?_go
color:
type: string
visitor_cookie_life:
type: integer
auto_approve_promoters:
type: boolean
is_private:
type: boolean
track_ad_traffic:
type: string
enum:
- pending
- allow
- block
links:
type: array
items:
$ref: '#/components/schemas/Link'
upgrade_details:
$ref: '#/components/schemas/UpgradeDetails'
rewards_for_promoters:
type: array
items:
$ref: '#/components/schemas/Reward'
rewards_for_referrals:
type: array
items:
$ref: '#/components/schemas/Reward'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Access token passed as a Bearer token in the Authorization header
accountId:
type: apiKey
in: header
name: ACCOUNT-ID
description: Account ID required with bearer token