> ## 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.
# Create new reward
> With this endpoint, you can assign a commission generated by a referral, and it will be recorded to the promoter who referred the lead/customer. You can find the referral by lead_id, email, or UID.
If the reward/commission is not generated by a lead/customer, you can assign it directly to a promoter through its promotion. You can find the promotion by `promotion_id` or `ref_id`. Note: To assign rewards/commission for sales via the API use the Tracking APIIf this call is successful and you enabled 'Promoter gets a new commission/reward' emails for the campaign, it will send emails to the promoter. To skip the emails, set the `skip_email_notification` parameter to `true`**HTTP Request**
`POST https://firstpromoter.com/api/v1/rewards/create`
## OpenAPI
````yaml openapi-rewards POST /create
openapi: 3.0.1
info:
title: FirstPromoter Rewards API
description: Rewards API allows you to manage the rewards of your promoters.
license:
name: MIT
version: 1.0.0
servers:
- url: https://firstpromoter.com/api/v1/rewards
security:
- apiKeyAuth: []
paths:
/create:
post:
description: >-
With this endpoint, you can assign a commission generated by a referral,
and it will be recorded to the promoter who referred the lead/customer.
You can find the referral by lead_id, email, or UID.
If the
reward/commission is not generated by a lead/customer, you can assign it
directly to a promoter through its promotion. You can find the promotion
by `promotion_id` or `ref_id`. Note: To assign rewards/commission
for sales via the API use the Tracking APIIf this call is
successful and you enabled 'Promoter gets a new commission/reward'
emails for the campaign, it will send emails to the promoter. To skip
the emails, set the `skip_email_notification` parameter to
`true`**HTTP Request**
`POST
https://firstpromoter.com/api/v1/rewards/create`
parameters:
- name: lead_id
in: query
description: Lead's id who generated the reward
schema:
type: string
- name: uid
in: query
description: UID of the lead who generated the reward
schema:
type: string
- name: email
in: query
description: Email of the lead who generated the reward.
schema:
type: string
- name: promotion_id
in: query
description: Promotion id of the promoter who owns the reward
schema:
type: string
- name: ref_id
in: query
description: Promotion referral id of the promoter who owns the reward
schema:
type: string
- name: reward_type
in: query
required: true
description: Type of reward
schema:
type: string
enum:
- points
- credits
- free_months
- discount_per
- discount_mon
- name: amount
in: query
required: true
description: Amount of the reward
schema:
type: integer
- name: status
in: query
description: >-
can be `approved`(default if this param is omitted), `pending` or
`denied`
schema:
type: string
enum:
- approved
- pending
- denied
- name: skip_email_notification
in: query
description: Set this to `true` to skip email notifications. Default is `false`.
schema:
type: boolean
responses:
'200':
description: Rewards created response
content:
application/json:
schema:
$ref: '#/components/schemas/RewardWithoutLead'
'401':
description: Authentication Error
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationError'
'422':
description: Unprocessable Entity error 422 response
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
components:
schemas:
RewardWithoutLead:
type: object
properties:
id:
description: ID of the reward
type: number
status:
description: status of the reward.
type: string
enum:
- approved
- pending
- denied
amount:
description: amount of the reward
type: integer
unit:
description: The reward unit.
type: string
enum:
- cash
- credits
- points
- free_months
created_at:
description: ISO date string at which the reward is created
type: string
lead: {}
event_id:
type: string
conversion_amount:
type: integer
tier_level:
description: The reward tier level
type: integer
promoter:
$ref: '#/components/schemas/PromoterWithoutPromotionsAndProfile'
promotion:
$ref: '#/components/schemas/Promotion'
AuthenticationError:
type: string
NotFoundError:
type: object
properties:
error:
type: string
PromoterWithoutPromotionsAndProfile:
type: object
properties:
id:
description: promoter's id
type: integer
status:
description: promoter's status
type: string
cust_id:
description: >-
customer/user ID of the promoter inside your application. This will
be included in the webhook event and can be used to identify the
promoter in your system if you subscribe for FirstPromoter's
'promoter_accepted' webhook.
email:
description: Promoter's email
type: string
created_at:
description: ISO date string at which the promoter signed up
type: string
temp_password:
description: >-
A temporary password the promoter can use to log in to their
dashboard if you don't use authentication tokens(auth_token) to sign
promoters in automatically.
type: string
default_promotion_id:
description: Promoter's default promotion id
type: number
pref:
description: Promoter's parent referral id.
type: string
default_ref_id:
description: Promoter's default referral id
type: string
note:
description: A note/description of promoter
type: string
w8_form_url: {}
w9_form_url: {}
parent_promoter_id:
description: parent promoter id
type: string
earnings_balance:
description: promoter's earnings balance
type: object
current_balance:
description: promoter's current balance
type: object
paid_balance:
description: promoter's paid balance
type: object
auth_token:
description: authentication token generated when the promoter was created
type: string
Promotion:
type: object
properties:
id:
description: ID of the promotion.
type: number
status:
description: Current offer status.
type: string
ref_id:
type: string
promo_code:
description: >-
The unique coupon id or coupon code from your billing provider to
assign to this affiliate for coupon tracking. This is also known as
promo code.
type: string
customer_promo_code:
description: >-
This is discount code/promotion code your customer used or applied
on your checkout page. This is also known as display code
type: string
target_reached_at:
type: string
promoter_id:
description: ID of the promoter/affiliate.
type: number
campaign_id:
description: ID of the campaign where the promotion runs.
type: number
referral_link:
description: Promoter's referral link
type: string
current_offer:
type: object
properties:
id:
description: The reward id
type: number
name:
description: The reward name
type: string
amount:
description: The reward amount
type: number
unit:
description: The reward unit (e.g., 'credits', 'free_months', 'cash').
type: string
default_promo_code:
type: string
current_referral_reward:
type: object
properties:
id:
type: number
amount:
type: number
unit:
type: string
name:
type: string
per_of_sale:
type: number
default_promo_code:
type: string
current_promotion_reward:
type: object
current_target_reward:
type: object
campaign_name:
type: string
hidden:
type: boolean
visitors_count:
type: number
leads_count:
type: number
customers_count:
type: number
refunds_count:
type: number
cancellations_count:
type: number
sales_count:
type: number
sales_total:
type: number
refunds_total:
type: number
active_customers_count:
type: number
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
````