openapi: 3.2.0
info:
  title: Firstpromoter Campaigns API
  version: '1.0'
  description: 'Operations tagged Campaigns across 2 of this provider''s published API definitions: firstpromoter-v2-affiliate-campaigns-openapi.yml, firstpromoter-v2-campaigns-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.firstpromoter.com/api/v2/affiliate
- url: https://api.firstpromoter.com/api/v2/company
security:
- BearerAuth: []
tags:
- name: Campaigns
paths:
  /campaigns:
    get:
      summary: Get all campaigns
      description: "Returns all campaigns  \n <Tip>**HTTP Request** <br/>` GET  https://api.firstpromoter.com/api/v2/affiliate/campaigns`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      description: ID of the campaign
                    name:
                      type: string
                      description: Name of the campaign
                    color:
                      type:
                      - string
                      - 'null'
                      description: Color associated with the campaign
                  description: Campaign object
        '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
                description: Error response
        '404':
          description: Record not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
                  code:
                    type: string
                    description: Error code
                description: Error response
      tags:
      - Campaigns
    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
    servers:
    - url: https://api.firstpromoter.com/api/v2/affiliate
  /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
    servers:
    - url: https://api.firstpromoter.com/api/v2/company
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:
    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'
    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
    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'
    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
    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
  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
x-refined-from:
- firstpromoter-v2-affiliate-campaigns-openapi.yml
- firstpromoter-v2-campaigns-openapi.yml