> ## 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 a new promoter

> Use this endpoint to create new promoters using the API. The response will return the newly added promoter as JSON. Probably the most important value from the response is `auth_token`, which is a unique key auto-generated on creation and can be used to automatically log in your promoters to their dashboard. [Learn more](https://help.firstpromoter.com/faq/how-to-embed-the-promoter-dashboard-inside-your-website-and-log-your-users-in-automatically). <Note> If this call is successful and you enabled `Promoter sign up accepted` emails for the campaign, it will start sending emails to the promoter. To skip the emails, set the `skip_email_notification` parameter to `true`</Note><Tip>**HTTP Request** <br/><br/> `POST https://firstpromoter.com/api/v1/promoters/create`</Tip>

Use this endpoint to create new promoters using the API. The response will return the newly added promoter as JSON.

Probably the most important value from the response is "auth\_token", which is a unique key auto-generated on creation and can be used to automatically log in your promoters to their dashboard. Learn more

<Note>
  If this call is successful and you enabled "Promoter sign up accepted" emails for the campaign, it will start sending emails to the promoter. To skip the emails, set the skip\_email\_notification parameter to "true".
</Note>


## OpenAPI

````yaml openapi-promoters POST /create
openapi: 3.0.1
info:
  title: FirstPromoter Promoters API
  description: >-
    The Promoters API endpoint allows you to manage your affiliates/promoters
    through API calls. The most important use case is to automatically create
    promoter accounts for your customers.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://firstpromoter.com/api/v1/promoters
security:
  - apiKeyAuth: []
paths:
  /create:
    post:
      description: >-
        Use this endpoint to create new promoters using the API. The response
        will return the newly added promoter as JSON. Probably the most
        important value from the response is `auth_token`, which is a unique key
        auto-generated on creation and can be used to automatically log in your
        promoters to their dashboard. [Learn
        more](https://help.firstpromoter.com/faq/how-to-embed-the-promoter-dashboard-inside-your-website-and-log-your-users-in-automatically).
        <Note> If this call is successful and you enabled `Promoter sign up
        accepted` emails for the campaign, it will start sending emails to the
        promoter. To skip the emails, set the `skip_email_notification`
        parameter to `true`</Note><Tip>**HTTP Request** <br/><br/> `POST
        https://firstpromoter.com/api/v1/promoters/create`</Tip>
      parameters:
        - name: email
          in: query
          required: true
          description: Promoter's email
          schema:
            type: string
            format: email
        - name: first_name
          in: query
          description: Promoter's first name
          schema:
            type: string
        - name: last_name
          in: query
          description: Promoter's last name
          schema:
            type: string
        - name: cust_id
          in: query
          description: >-
            Your customer's user ID inside your application/system for the
            promoter. It will be avaliable in the webhooks to identify the
            promoter in your system if you subscribe for FirstPromoter webhooks.
          schema:
            type: string
        - name: ref_id
          in: query
          description: >-
            Referral ID. If this is blank an ID is assigned based on the first
            name. Can be only `lower-case letters` , `numbers` , `-`(hyphen) and
            `_`(underscore)
          schema:
            type: string
        - name: promo_code
          in: query
          description: >-
            Unique promo code from your billing provider to assign to this
            affiliate for coupon tracking. This is also known as the `Coupon
            Code` or `Coupon ID`
          schema:
            type: string
        - name: customer_promo_code
          in: query
          description: >-
            Customer promo code from your billing provider to assign to this
            affiliate for coupon tracking. This is also known as `discount code`
            or `promotion code` or `display code`. This is the code your
            customer(s) can use on the checkout form/page.
          schema:
            type: string
        - name: campaign_id
          in: query
          description: >-
            The ID of the campaign to assign the promoter to. On the campaigns
            sections you can see the id as `camp_id` query parameter on
            'Promoter Sign Up page URL'. If there is no `camp_id` it means the
            campaign is the default campaign and this parameter is not required.
          schema:
            type: string
        - name: temp_password
          in: query
          description: >-
            A temporary password promoters can use to log in to their dashboard
            if you don't use authentication tokens(`auth_token`) to sign
            promoters in automatically.
          schema:
            type: string
        - name: landing_url
          in: query
          description: >-
            You can set up a custom landing page url for this promoter. The
            referral id will be appended to it, unless the `url_tracking`
            parameter(below) is used.
          schema:
            type: string
        - name: url_tracking
          in: query
          description: >-
            Set `true` to enable direct url tracking feature. FirstPromoter will
            do the tracking based on `landing_url`(above) without requiring the
            referral id to be appended to the url. The `landing_url` needs to be
            unique for each promoter. Default is `false`. 
          schema:
            type: string
        - name: website
          in: query
          description: 'Promoter''s website '
          schema:
            type: string
        - name: paypal_email
          in: query
          description: Promoter's Paypal email address
          schema:
            type: string
        - name: avatar_url
          in: query
          description: URL of the profile picture promoters can see on their dashboard
          schema:
            type: string
        - name: parent_promoter_id
          in: query
          description: Id of the parent if the promoter is a sub-affiliate
          schema:
            type: string
        - name: parent_promoter_email
          in: query
          description: Email of the parent promoter if the promoter is a sub-affiliate
          schema:
            type: string
        - name: linkedin_url
          in: query
          description: Promoter's linkedin url
          schema:
            type: string
        - name: twitter_url
          in: query
          description: Promoter's twitter url
          schema:
            type: string
        - name: facebook_url
          in: query
          description: Promoter's facebook url
          schema:
            type: string
        - name: instagram_url
          in: query
          description: Promoter's instagram url
          schema:
            type: string
        - name: youtube_url
          in: query
          description: Promoter's youtube url
          schema:
            type: string
        - name: country
          in: query
          description: Promoter's country
          schema:
            type: string
        - name: company_name
          in: query
          description: Promoter's company name
          schema:
            type: string
        - name: phone_number
          in: query
          description: Promoter's phone number
          schema:
            type: string
        - name: address
          in: query
          description: Promoter's address
          schema:
            type: string
        - name: note
          in: query
          description: A note/description of promoter
          schema:
            type: string
        - name: created_at
          in: query
          description: ISO date string of the date of the signup event
          schema:
            type: string
        - name: skip_email_notification
          in: query
          description: Set this to `true` to skip email notifications. Default is `false`.
          schema:
            type: boolean
        - name: always_approve
          in: query
          description: >-
            Set this to `true` to automatically approve the promoter into the
            campaign without having to manually review the promoter. Please note
            that this feature only works when `Auto approve new promoters` is
            enabled/toggle on your FirstPromoter Admin panel under the Campaign
            settings.
          schema:
            type: boolean
      responses:
        '200':
          description: Promoters created response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Promoter'
        '401':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '422':
          description: 422 Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityError'
components:
  schemas:
    Promoter:
      type: object
      properties:
        id:
          description: The promoter's ID inside FirstPromoter
          type: integer
        status:
          description: Promoter's status
          type: string
          enum:
            - approved
            - pending
            - denied
        cust_id:
          description: >-
            Your customer's user ID inside your application/system for the
            promoter. 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 webhooks.
          type: string
        email:
          description: Promoter's email
          type: string
        created_at:
          description: ISO date string when 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
          example: 128833
        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:
          description: The w8 form url
          type: string
        w9_form_url:
          description: The w9 form url
          type: string
        parent_promoter_id:
          description: Parent promoter id
          type: string
        earnings_balance:
          description: >-
            Promoter's earnings balance. This object can contain `cash`,
            `credits`, `discount_per` 
          type: object
          properties:
            cash:
              description: The cash earnings
              type: integer
              example: 3000
            credits:
              description: The earning credits
              type: integer
              example: 300
            discount_per:
              description: The earning discount percentage
              type: integer
              example: 30
        current_balance:
          description: >-
            Promoter's current balance. This object can contain `cash`,
            `credits`, `discount_per` 
          type: object
          properties:
            cash:
              description: The current cash balance
              type: integer
              example: 1000
            credits:
              description: The current credits
              type: integer
              example: 200
            discount_per:
              description: The current discount percentage
              type: integer
              example: 15
        paid_balance:
          description: >-
            Promoter's paid balance. This object can contain `cash`, `credits`,
            `discount_per`
          type: object
          properties:
            cash:
              description: The cash paid
              type: integer
              example: 2000
            credits:
              description: The credits given
              type: integer
              example: 100
            discount_per:
              description: The discount percentage given
              type: integer
              example: 15
        auth_token:
          description: Authentication token generated when the promoter was created
          type: string
        profile:
          $ref: '#/components/schemas/PromoterProfile'
        promotions:
          type: array
          items:
            $ref: '#/components/schemas/Promotion'
        custom_fields:
          type: object
          nullable: true
          description: Key-value pairs of custom fields configured for this promoter
        promo_codes:
          type: array
          description: Promo codes associated with this promoter
          items:
            type: object
            properties:
              id:
                type: integer
              code:
                type: string
              reward:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
    AuthenticationError:
      type: string
    UnprocessableEntityError:
      required:
        - company_user.user.email
        - message
      type: object
      properties:
        company_user.user.email:
          type: array
          items:
            type: string
        promotions:
          type: array
          items:
            type: object
    PromoterProfile:
      type: object
      properties:
        first_name:
          description: Promoter's first name
          type: string
        last_name:
          description: Promoter's last name
          type: string
        website:
          description: Promoter's website
          type: string
        company_name:
          description: Promoter's company name
          type: string
        phone_number:
          description: Promoter's phone number
          type: string
        address:
          description: Promoter's address
          type: string
        vat_id:
          description: Promoter's vat id
          type: string
        country:
          description: Promoter's country
          type: string
        paypal_email:
          description: Promoter's Paypal email address
          type: string
        avatar_url:
          description: URL of the profile picture promoters can see on their dashboard
          type: string
        description:
          description: A note/description of promoter
          type: string
        social_accounts:
          $ref: '#/components/schemas/SocialAccounts'
    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: ' Unique promo code from your billing provider to assign to this affiliate for coupon tracking. This is also known as the `Coupon Code` or `Coupon ID`'
          type: string
        customer_promo_code:
          description: >-
            Customer promo code from your billing provider assigned to this
            affiliate for coupon tracking. This is also known as `discount code`
            or `promotion code` or `display code`. This is the code your
            customer(s) used on the checkout form/page.
          type: string
        target_reached_at:
          type: object
        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
    SocialAccounts:
      type: object
      properties:
        twitter:
          type: object
          properties:
            url:
              description: Promoter's twitter url
              type: string
        youtube:
          type: object
          properties:
            url:
              description: Promoter's youtube url
              type: string
        facebook:
          type: object
          properties:
            url:
              description: Promoter's Facebook url
              type: string
        linkedin:
          type: object
          properties:
            url:
              description: Promoter's linkedin url
              type: string
        instagram:
          type: object
          properties:
            url:
              description: Promoter's instagram url
              type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````