> ## 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

> Create a promoter and get back their auth_token, referral ID and campaign details (legacy v1 API).

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".


## 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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.