openapi: 3.1.0
info:
  title: Influencer Hero API
  version: 1.4.2
  description: API documentation for the Influencer Hero platform.
  contact:
    name: Influencer Hero Support
    url: https://help.influencer-hero.com/
    email: support@influencer-hero.com
servers:
  - url: https://api.influencer-hero.com
paths:
  /v1/public/hello:
    get:
      operationId: publicHello
      tags:
        - Test endpoints
      summary: Public Hello Endpoint
      description: |
        A public endpoint to verify the API is working without authentication.
        Use `/v1/account/hello` to test authenticated requests.
      responses:
        '200':
          description: Public request well received.
          content:
            application/json:
              example:
                message: >-
                  Public request well received. Use /v1/account/hello to test
                  authenticated requests.
  /v1/account/hello:
    get:
      operationId: accountHello
      tags:
        - Test endpoints
      summary: Authenticated Hello Endpoint
      description: |
        An authenticated endpoint to verify user credentials.
      responses:
        '201':
          description: Authenticated request successfully processed.
          content:
            application/json:
              example:
                message: You are logged in - <account_id> - <user_id>
  /v1/search/identify_influencers:
    post:
      operationId: identifyInfluencers
      tags:
        - CRM
      summary: Identify Influencers
      description: >-
        Identifies influencers based on contact details. Matched influencers
        will appear in the "Your customers" tab of the influencer finder.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                influencer_list:
                  type: array
                  items:
                    type: string
                  description: List of email addresses.
                  example:
                    - influencer1@example.com
                    - influencer2@example.com
                brand_id:
                  type: integer
                  description: >-
                    ID of the brand. If not provided, the first brand in the
                    account will be used.
                  example: 4819
                source_type:
                  type: string
                  description: >-
                    Source type for your reference (will be shown in the IH
                    dashboard).
                  example: sendinblue
              required:
                - influencer_list
      responses:
        '200':
          description: Successfully sent contact details to the processing queue.
          content:
            application/json:
              example:
                message: >-
                  Successfully sent contact details to queue. Please allow for
                  up to an hour for processing.
                success: true
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                missingInfluencers:
                  summary: Missing influencer_list
                  value:
                    message: influencer_list is required
                noBrandsFound:
                  summary: No Brands in Account
                  value:
                    message: No brands found in account
                brandNotFound:
                  summary: Brand Not Found
                  value:
                    message: Brand not found
  /v1/crm/new_influencer_click:
    post:
      operationId: increaseInfluencerClicks
      tags:
        - Affiliate Tracking
      summary: New Influencer Click
      description: Increases the number of tracked clicks on an influencer's deal page.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                influencer_handle:
                  type: string
                  description: Influencer handle.
                  example: therock
                deal_id:
                  type: string
                  description: >-
                    Deal ID or URL. Either deal_id or influencer_handle is
                    required.
                  example: ETUNQ6ZTW1
                collab_id:
                  type: string
                  description: Collaboration ID (optional)
                  example: V2KYU6F9
                brand_id:
                  type: integer
                  description: Brand ID (optional)
                  example: 4819
                increase_clicks:
                  type: integer
                  description: Number of clicks to add. Defaults to 0.
                  example: 10
                country_code:
                  type: string
                  description: Country code for click origin.
                  example: US
              required:
                - increase_clicks
      responses:
        '200':
          description: Clicks successfully added.
          content:
            application/json:
              example:
                deal_id: ETUNQ6ZTW1
                collab_id: V2KYU6F9
                new_clicks_value: 150
                message: Clicks successfully added.
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                missingDealOrHandle:
                  summary: Missing Deal/Handle
                  value:
                    message: deal_id or influencer_handle is required
                collaborationNotFound:
                  summary: Collaboration Not Found
                  value:
                    message: Collaboration not found
        '404':
          description: Deal Not Found
          content:
            application/json:
              example:
                message: Deal not found
  /v1/crm/new_influencer_referral:
    post:
      operationId: newInfluencerReferral
      tags:
        - Affiliate Tracking
      summary: New Influencer Referral
      description: Adds a new order/referral to an influencer's affiliate performance.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                influencer_handle:
                  type: string
                  description: Influencer handle.
                  example: therock
                deal_id:
                  type: string
                  description: >-
                    Deal ID or URL. Either deal_id or influencer_handle is
                    required.
                  example: ETUNQ6ZTW1
                collab_id:
                  type: string
                  description: Collaboration ID (optional).
                  example: V2KYU6F9
                brand_id:
                  type: integer
                  description: Brand ID (optional).
                  example: 4819
                order_id:
                  type: string
                  description: Order ID.
                  example: '891237123'
                order_revenue:
                  type: number
                  description: Revenue of the order.
                  example: 150.5
                order_platform:
                  type: string
                  description: Platform of the order.
                  example: shopify
                order_discount_codes_used:
                  type: string
                  description: Discount codes used.
                  example: DISCOUNT50
                order_notes:
                  type: string
                  description: Notes about the order.
                  example: High-value customer.
              required:
                - deal_id
                - order_id
                - order_revenue
      responses:
        '200':
          description: Order successfully added.
          content:
            application/json:
              example:
                deal_id: ETUNQ6ZTW1
                collab_id: V2KYU6F9
                message: Order successfully added.
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                missingDealOrHandle:
                  summary: Missing Deal/Handle
                  value:
                    message: deal_id or influencer_handle is required
                collaborationNotFound:
                  summary: Collaboration Not Found
                  value:
                    message: Collaboration not found
        '404':
          description: Deal Not Found
          content:
            application/json:
              example:
                message: Deal not found
  /v1/crm/get_deal_details:
    get:
      operationId: getDealDetails
      tags:
        - CRM
      summary: Get Deal Information
      description: Retrieves information about a specific deal in the CRM.
      parameters:
        - name: influencer_handle
          in: query
          required: false
          schema:
            type: string
          description: Influencer handle. Either deal_id or influencer_handle is required.
          example: therock
        - name: deal_id
          in: query
          required: false
          schema:
            type: string
          description: Deal ID or URL. Either deal_id or influencer_handle is required.
          example: ETUNQ6ZTW1
      responses:
        '200':
          description: Success response
          content:
            application/json:
              example:
                deal_info:
                  id: ETUNQ6ZTW1
                  influencer_handle: therock
                  brand_id: 4819
                  is_active: true
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                message: username is required
        '404':
          description: Not Found
          content:
            application/json:
              example:
                message: Deal not found
  /v1/crm/create_deal:
    post:
      operationId: createDeal
      tags:
        - CRM
      summary: Import Influencer
      description: Creates a new deal in your CRM.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                influencer_handle:
                  type: string
                  description: Influencer handle.
                  example: therock
                platform:
                  type: string
                  description: Social media platform.
                  example: instagram
                first_name:
                  type: string
                  description: Influencer's first name.
                  example: Dwayne
                last_name:
                  type: string
                  description: Influencer's last name.
                  example: Johnson
                email:
                  type: string
                  description: Influencer's email address.
                  example: dwayne.johnson@example.com
                brand_id:
                  type: integer
                  description: Brand ID.
                  example: 4819
                dealflow_id:
                  type: string
                  description: Dealflow ID.
                  example: D_FSSI4P
                funnel_step:
                  type: integer
                  description: The funnel step to set for the deal.
                  example: 2
                address_line:
                  type: string
                  description: Street address or other address details.
                  example: 123 Hollywood Blvd
                postcode:
                  type: string
                  description: Postal code.
                  example: '90038'
                region:
                  type: string
                  description: Region or state.
                  example: California
                city:
                  type: string
                  description: City of residence.
                  example: Los Angeles
                country_code:
                  type: string
                  description: Country code (e.g., 'US', 'GB').
                  example: US
                phone_nr:
                  type: string
                  description: Phone number.
                  example: +1 310 555 0100
                total_payouts:
                  type: number
                  description: Total payouts already made to this influencer.
                  example: 250
                total_commission_earned:
                  type: number
                  description: Total commission earned by this influencer so far.
                  example: 500.5
                total_fixed_fee_earned:
                  type: number
                  description: Total fixed fee earned by this influencer so far.
                  example: 1000
                total_sales:
                  type: number
                  description: Total sales so far attributed to this influencer.
                  example: 4500
                total_referrals:
                  type: number
                  description: Total referral count from this influencer.
                  example: 25
                code:
                  type: string
                  description: Discount code to associate with the collaboration.
                  example: THEROCK50
                code_perc:
                  type: number
                  description: Percentage discount for the code (0 to 100).
                  example: 15
                custom_url:
                  type: string
                  description: Custom affiliate URL to track.
                  example: /therock
                custom_url_target:
                  type: string
                  description: Landing page or reference name for `custom_url`.
                  example: /
                commission_perc:
                  type: number
                  description: Commission percentage for affiliate sales.
                  example: 10
                create_affiliate_details:
                  type: boolean
                  description: >-
                    Whether to create affiliate details automatically. If true,
                    we will create the discount code and custom link (if there
                    are any) in your shopify/CMS integration. If not we will
                    just insert it in the deal page (sales with that discount
                    code will still be correctly tracked)
                  example: true
              required:
                - influencer_handle
                - platform
                - brand_id
                - dealflow_id
      responses:
        '200':
          description: Successfully created deal.
          content:
            application/json:
              example:
                deal_id: ETUNQ6ZTW1
                deal_page_url: https://app.influencer-hero.com/deal/ETUNQ6ZTW1
                message: Successfully created deal.
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                missingField:
                  summary: Missing required fields
                  value:
                    message: platform is required
                brandNotFound:
                  summary: Brand Not Found
                  value:
                    message: Brand not found
                dealflowNotFound:
                  summary: Dealflow Not Found
                  value:
                    message: Dealflow not found
  /v1/account/search_dealflows:
    get:
      operationId: searchDealflows
      tags:
        - Account
      summary: Dealflow Search
      description: Retrieves all dealflows in the user's account.
      responses:
        '200':
          description: Success response
          content:
            application/json:
              example:
                - id: D_FSSI4P
                  name: Dealflow 1
                - id: '67890'
                  name: Dealflow 2
  /v1/account/search_brands:
    get:
      operationId: searchBrands
      tags:
        - Account
      summary: Brand ID Search
      description: Searches for brands in the platform account.
      responses:
        '200':
          description: Success response
          content:
            application/json:
              example:
                - id: 4819
                  name: Brand A
                - id: 6789
                  name: Brand B
  /v1/account/create_webhook:
    post:
      operationId: createWebhook
      tags:
        - Account
      summary: Create Webhook
      description: Creates a webhook for various triggers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                webhook_url:
                  type: string
                  description: Webhook target URL.
                  example: https://example.com/webhook
                webhook_type:
                  type: string
                  description: >-
                    Type of webhook. Must be one of
                    ["product_sent","update_discount_code","update_custom_link",
                    "new_payout_request","new_email_sent","new_influencer_reply",
                    "new_influencer_post","new_max_bid"].
                  example: new_influencer_reply
              required:
                - webhook_url
                - webhook_type
      responses:
        '200':
          description: Successfully created webhook.
          content:
            application/json:
              example:
                message: Successfully created webhook.
        '400':
          description: Invalid Webhook Type
          content:
            application/json:
              example:
                message: Invalid webhook type
  /v1/account/delete_webhook:
    delete:
      operationId: deleteWebhook
      tags:
        - Account
      summary: Delete Webhook
      description: Deletes an existing webhook.
      parameters:
        - name: webhook_url
          in: query
          required: true
          schema:
            type: string
          description: Webhook URL to delete.
          example: https://example.com/webhook
      responses:
        '200':
          description: Successfully deleted webhook.
          content:
            application/json:
              example:
                message: Successfully deleted webhook.
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                invalidWebhook:
                  summary: Invalid or not found
                  value:
                    message: Invalid webhook type or Webhook URL not found.
webhooks:
  new_payout_request:
    post:
      summary: New payout request
      description: >
        This webhook is fired whenever a user creates a payout request in
        Influencer Hero.   The request body contains all the details of the
        requested payout as well as  minimal information about the associated
        deal.  

        **Security / Verification**   - Each request includes a timestamp
        (`X-InfluencerHero-Timestamp`) and  
          an HMAC-SHA256 signature (`X-InfluencerHero-Signature`) in the headers.  
        - The payload can be used along with the secret key your system has
        stored 
          (provided by Influencer Hero) to verify authenticity of the request.
      operationId: newPayoutRequest
      parameters:
        - $ref: '#/components/parameters/InfluencerHeroTimestamp'
        - $ref: '#/components/parameters/InfluencerHeroSignature'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                payout_information:
                  type: object
                  description: Key information about the requested payout.
                  properties:
                    payout_comment:
                      type: string
                      description: A comment or note associated with the payout.
                    brand_id:
                      type: string
                      description: >-
                        Identifier for the brand requesting or associated with
                        the payout.
                    payout_currency:
                      type: string
                      description: >-
                        The currency in which the payout is requested (e.g.,
                        USD).
                    payout_amount:
                      type: number
                      description: The numerical value of the payout.
                  required:
                    - payout_comment
                    - brand_id
                    - payout_currency
                    - payout_amount
                deal_info:
                  $ref: '#/components/schemas/DealInfo'
                deal_id:
                  type: string
                  description: Internal ID of the deal for reference.
              required:
                - payout_information
                - deal_info
                - deal_id
            examples:
              default:
                summary: Example Payout Request
                value:
                  payout_information:
                    payout_comment: January bonus payment
                    brand_id: '12345'
                    payout_currency: USD
                    payout_amount: 1500
                  deal_info:
                    deal_name: therock
                    is_active: true
                    dealflow_funnel_step: 3
                    dealflow_type: outreach
                    dealflow_name: Spring Collection Promo
                    picture_url: >-
                      https://imgp.sptds.icu/v2?mb0KwpL92uYofJiSjDn1%2F6peL1lBwv3s%2BUvShHERlDbrEEwrWumIvR20xZeZXa0LDeIrcniqZeG9S%2F1a5s2Rx3FZdXrWpY%2BmSBJp1l%2FmBGon3rcHA4EfuatZqMhVBzAT
                    nr_followers: 60000
                    full_name: Dwayne Johnson
                    platform: instagram
                    profile_url: https://instagram.com/therock
                  deal_id: DEAL-67890
      responses:
        '200':
          description: >-
            Your server should return a 2xx response to acknowledge successful
            receipt of the event.
  new_max_bid:
    post:
      summary: New Max Bid Requested
      description: >
        This webhook is triggered when a new Max Bid is requested for a deal. 
        The receiving endpoint can use `X-InfluencerHero-Timestamp` and 
        `X-InfluencerHero-Signature` to verify authenticity via HMAC-SHA256.
      operationId: newMaxBid
      parameters:
        - $ref: '#/components/parameters/InfluencerHeroTimestamp'
        - $ref: '#/components/parameters/InfluencerHeroSignature'
      requestBody:
        description: Payload containing information about the new Max Bid request.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                webhook_timestamp:
                  type: string
                  description: Server-side timestamp included in the webhook body.
                max_bid_information:
                  type: object
                  description: Additional details about the Max Bid request.
                  properties:
                    max_bid_comment:
                      type: string
                      description: Notes or comments provided with the Max Bid request.
                deal_info:
                  $ref: '#/components/schemas/DealInfo'
                deal_id:
                  type: string
                  description: >-
                    Unique identifier of the deal for which the Max Bid is
                    requested.
              required:
                - webhook_timestamp
                - max_bid_information
                - deal_id
            examples:
              default:
                summary: Example New Max Bid Webhook
                value:
                  webhook_timestamp: '1693427202'
                  max_bid_information:
                    max_bid_comment: >-
                      Please provide the highest possible bid for this
                      influencer.
                  deal_info:
                    deal_name: therock
                    is_active: true
                    dealflow_funnel_step: 3
                    dealflow_type: outreach
                    dealflow_name: Spring Collection Promo
                    picture_url: >-
                      https://imgp.sptds.icu/v2?mb0KwpL92uYofJiSjDn1%2F6peL1lBwv3s%2BUvShHERlDbrEEwrWumIvR20xZeZXa0LDeIrcniqZeG9S%2F1a5s2Rx3FZdXrWpY%2BmSBJp1l%2FmBGon3rcHA4EfuatZqMhVBzAT
                    nr_followers: 60000
                    full_name: Dwayne Johnson
                    platform: instagram
                    profile_url: https://instagram.com/therock
                  deal_id: abc123
      responses:
        '200':
          description: >-
            The server processing the webhook should generally return a 200
            status indicating successful receipt.
        4XX:
          description: Client error – e.g., signature mismatch or invalid payload.
        5XX:
          description: Server error – e.g., issue on the receiving endpoint.
  update_discount_code:
    post:
      summary: Update Discount Code
      description: >
        This webhook is triggered when a discount code is updated for a
        collaboration.  The receiving endpoint can use
        `X-InfluencerHero-Timestamp` and  `X-InfluencerHero-Signature` to verify
        authenticity via HMAC-SHA256.
      operationId: updateDiscountCode
      parameters:
        - $ref: '#/components/parameters/InfluencerHeroTimestamp'
        - $ref: '#/components/parameters/InfluencerHeroSignature'
      requestBody:
        description: Payload containing information about the updated discount code.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                webhook_timestamp:
                  type: string
                  description: Server-side timestamp included in the webhook body.
                code_information:
                  type: object
                  description: Details about the previous and new discount codes.
                  properties:
                    old_discount_code:
                      type: string
                      description: The existing discount code before the update.
                    old_discount_perc:
                      type: number
                      description: The existing discount percentage before the update.
                    new_discount_code:
                      type: string
                      description: The new discount code, if changed.
                    new_discount_perc:
                      type: number
                      description: The new discount percentage, if changed.
                collab_id:
                  type: string
                  description: >-
                    Unique identifier of the collaboration receiving the
                    discount code.
                deal_info:
                  $ref: '#/components/schemas/DealInfo'
                deal_id:
                  type: string
                  description: >-
                    Unique identifier of the deal associated with this discount
                    code.
              required:
                - webhook_timestamp
                - code_information
                - collab_id
                - deal_id
            examples:
              default:
                summary: Example Update Discount Code Webhook
                value:
                  webhook_timestamp: '1693427202'
                  code_information:
                    old_discount_code: FIT2023
                    old_discount_perc: 15
                    new_discount_code: FIT2024
                    new_discount_perc: 20
                  collab_id: collab987
                  deal_info:
                    deal_name: therock
                    is_active: true
                    dealflow_funnel_step: 3
                    dealflow_type: outreach
                    dealflow_name: Spring Collection Promo
                    picture_url: >-
                      https://imgp.sptds.icu/v2?mb0KwpL92uYofJiSjDn1%2F6peL1lBwv3s%2BUvShHERlDbrEEwrWumIvR20xZeZXa0LDeIrcniqZeG9S%2F1a5s2Rx3FZdXrWpY%2BmSBJp1l%2FmBGon3rcHA4EfuatZqMhVBzAT
                    nr_followers: 60000
                    full_name: Dwayne Johnson
                    platform: instagram
                    profile_url: https://instagram.com/therock
                  deal_id: xyz789
      responses:
        '200':
          description: >-
            The server processing the webhook should generally return a 200
            status indicating successful receipt.
        4XX:
          description: Client error – e.g., signature mismatch or invalid payload.
        5XX:
          description: Server error – e.g., issue on the receiving endpoint.
  update_custom_link:
    post:
      summary: Update Custom Link
      description: >
        This webhook is triggered when a custom link is updated (or deleted) for
        a collaboration.  The receiving endpoint can use
        `X-InfluencerHero-Timestamp` and  `X-InfluencerHero-Signature` to verify
        authenticity via HMAC-SHA256.
      operationId: updateCustomLink
      parameters:
        - $ref: '#/components/parameters/InfluencerHeroTimestamp'
        - $ref: '#/components/parameters/InfluencerHeroSignature'
      requestBody:
        description: Payload containing information about the updated custom link.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                webhook_timestamp:
                  type: string
                  description: Server-side timestamp included in the webhook body.
                custom_link_information:
                  type: object
                  description: Details about the previous and new custom link.
                  properties:
                    old_custom_link:
                      type: string
                      nullable: true
                      description: The existing custom link before the update.
                    old_custom_link_target:
                      type: string
                      nullable: true
                      description: The existing target URL for the old custom link.
                    new_custom_link:
                      type: string
                      nullable: true
                      description: The new custom link, if changed.
                    new_custom_link_target:
                      type: string
                      nullable: true
                      description: The new target URL for the updated custom link.
                deal_info:
                  $ref: '#/components/schemas/DealInfo'
                collab_id:
                  type: string
                  description: >-
                    Unique identifier of the collaboration receiving the custom
                    link.
                deal_id:
                  type: string
                  description: >-
                    Unique identifier of the deal associated with this custom
                    link.
              required:
                - webhook_timestamp
                - custom_link_information
                - collab_id
                - deal_id
            examples:
              default:
                summary: Example Update Custom Link Webhook
                value:
                  webhook_timestamp: '1693427202'
                  custom_link_information:
                    old_custom_link: /the-old-link
                    old_custom_link_target: https://old.example.com
                    new_custom_link: /the-new-link
                    new_custom_link_target: https://new.example.com
                  deal_info:
                    deal_name: therock
                    is_active: true
                    dealflow_funnel_step: 3
                    dealflow_type: outreach
                    dealflow_name: Spring Collection Promo
                    picture_url: >-
                      https://imgp.sptds.icu/v2?mb0KwpL92uYofJiSjDn1%2F6peL1lBwv3s%2BUvShHERlDbrEEwrWumIvR20xZeZXa0LDeIrcniqZeG9S%2F1a5s2Rx3FZdXrWpY%2BmSBJp1l%2FmBGon3rcHA4EfuatZqMhVBzAT
                    nr_followers: 60000
                    full_name: Dwayne Johnson
                    platform: instagram
                    profile_url: https://instagram.com/therock
                  collab_id: collab123
                  deal_id: deal321
      responses:
        '200':
          description: >-
            The server processing the webhook should generally return a 200
            status indicating successful receipt.
        4XX:
          description: Client error – e.g., signature mismatch or invalid payload.
        5XX:
          description: Server error – e.g., issue on the receiving endpoint.
  product_sent:
    post:
      summary: Product Sent
      description: >
        This webhook is fired whenever a user sends a product to an influencer
        or contact.   The request body contains core details of the shipped
        order (in a simplified form),  along with minimal information about the
        related deal.

        **Security / Verification**   - Each request includes a timestamp
        (`X-InfluencerHero-Timestamp`) and  
          an HMAC-SHA256 signature (`X-InfluencerHero-Signature`) in the headers.  
        - The payload can be used along with the secret key your system has
        stored 
          (provided by Influencer Hero) to verify authenticity of the request.
      operationId: productSent
      parameters:
        - $ref: '#/components/parameters/InfluencerHeroTimestamp'
        - $ref: '#/components/parameters/InfluencerHeroSignature'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                send_product_info:
                  type: object
                  description: >-
                    Details about the product and recipient information being
                    sent.
                  properties:
                    line_items:
                      type: array
                      description: A list of items being sent in this order.
                      items:
                        type: object
                        properties:
                          variant_id:
                            type: integer
                            description: Variant identifier in the e-commerce system.
                          quantity:
                            type: integer
                            description: Number of units of this variant to send.
                          variant_name:
                            type: string
                            description: Optional name or descriptor for this variant.
                        required:
                          - variant_id
                          - quantity
                    customer:
                      type: object
                      description: Basic customer/influencer information.
                      properties:
                        first_name:
                          type: string
                          description: Customer's first name.
                        last_name:
                          type: string
                          description: Customer's last name.
                        email:
                          type: string
                          format: email
                          description: Customer's email address.
                      required:
                        - first_name
                        - last_name
                        - email
                    shipping_address:
                      type: object
                      description: Shipping address where items should be delivered.
                      properties:
                        name:
                          type: string
                          description: Full name as provided on shipping details.
                        first_name:
                          type: string
                          description: First name (for shipping).
                        last_name:
                          type: string
                          description: Last name (for shipping).
                        address1:
                          type: string
                          description: Primary address line.
                        city:
                          type: string
                          description: City for shipping address.
                        province:
                          type: string
                          description: State/region/province for shipping address.
                        country:
                          type: string
                          description: Country for shipping address.
                        zip:
                          type: string
                          description: Postal or ZIP code.
                        phone:
                          type: string
                          description: Phone number associated with the shipping address.
                      required:
                        - name
                        - first_name
                        - last_name
                        - address1
                        - city
                        - province
                        - country
                        - zip
                    phone:
                      type: string
                      description: >-
                        Optional phone number for the order (duplicate of
                        shipping/billing).
                deal_info:
                  $ref: '#/components/schemas/DealInfo'
                deal_id:
                  type: string
                  description: Internal ID of the deal for reference.
              required:
                - send_product_info
                - deal_info
                - deal_id
            examples:
              default:
                summary: Example Product Sent
                value:
                  send_product_info:
                    line_items:
                      - variant_id: 123456
                        quantity: 2
                        variant_name: Blue T-Shirt, Large
                    customer:
                      first_name: John
                      last_name: Doe
                      email: john@example.com
                    shipping_address:
                      name: John Doe
                      first_name: John
                      last_name: Doe
                      address1: 123 Maple St
                      city: Sample City
                      province: Sample Province
                      country: Sample Country
                      zip: '12345'
                      phone: 555-555-5555
                    phone: 555-555-5555
                  deal_info:
                    deal_name: therock
                    is_active: true
                    dealflow_funnel_step: 3
                    dealflow_type: outreach
                    dealflow_name: Spring Collection Promo
                    picture_url: >-
                      https://imgp.sptds.icu/v2?mb0KwpL92uYofJiSjDn1%2F6peL1lBwv3s%2BUvShHERlDbrEEwrWumIvR20xZeZXa0LDeIrcniqZeG9S%2F1a5s2Rx3FZdXrWpY%2BmSBJp1l%2FmBGon3rcHA4EfuatZqMhVBzAT
                    nr_followers: 60000
                    full_name: Dwayne Johnson
                    platform: instagram
                    profile_url: https://instagram.com/therock
                  deal_id: DEAL-12345
      responses:
        '200':
          description: >-
            Your server should return a 2xx response to acknowledge successful
            receipt of the event.
  new_email_sent:
    post:
      summary: New Email Sent
      description: >
        This webhook is triggered when a new email is sent to a deal contact. 
        The receiving endpoint can use `X-InfluencerHero-Timestamp` and 
        `X-InfluencerHero-Signature` to verify authenticity via HMAC-SHA256.
      operationId: newEmailSent
      parameters:
        - $ref: '#/components/parameters/InfluencerHeroTimestamp'
        - $ref: '#/components/parameters/InfluencerHeroSignature'
      requestBody:
        description: Payload containing information about the newly sent email.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                webhook_timestamp:
                  type: string
                  description: Server-side timestamp included in the webhook body.
                email_information:
                  type: object
                  description: Details about the email that was just sent.
                  properties:
                    sent_from_email_account:
                      type: string
                      description: Email address from which the email was sent.
                    recipient:
                      type: string
                      description: Primary recipient of the email.
                    cc_address:
                      type: string
                      nullable: true
                      description: CC recipient of the email, if any.
                    email_subject:
                      type: string
                      description: Subject line of the email.
                    email_body:
                      type: string
                      description: Plaintext version of the email body.
                    sent_by_user:
                      type: string
                      description: The name or identifier of the user who sent the email.
                deal_info:
                  $ref: '#/components/schemas/DealInfo'
                deal_id:
                  type: string
                  description: Unique identifier of the deal to which the email was sent.
              required:
                - webhook_timestamp
                - email_information
                - deal_id
            examples:
              default:
                summary: Example New Email Sent Webhook
                value:
                  webhook_timestamp: '1693427202'
                  email_information:
                    sent_from_email_account: brand@mycompany.com
                    recipient: influencer@example.com
                    cc_address: manager@example.com
                    email_subject: Collaboration Proposal
                    email_body: Hello, I'd like to collaborate on our new campaign...
                    sent_by_user: John Marketer
                  deal_info:
                    deal_name: therock
                    is_active: true
                    dealflow_funnel_step: 3
                    dealflow_type: outreach
                    dealflow_name: Spring Collection Promo
                    picture_url: >-
                      https://imgp.sptds.icu/v2?mb0KwpL92uYofJiSjDn1%2F6peL1lBwv3s%2BUvShHERlDbrEEwrWumIvR20xZeZXa0LDeIrcniqZeG9S%2F1a5s2Rx3FZdXrWpY%2BmSBJp1l%2FmBGon3rcHA4EfuatZqMhVBzAT
                    nr_followers: 60000
                    full_name: Dwayne Johnson
                    platform: instagram
                    profile_url: https://instagram.com/therock
                  deal_id: deal123
      responses:
        '200':
          description: >-
            The server processing the webhook should generally return a 200
            status indicating successful receipt.
        4XX:
          description: Client error – e.g., signature mismatch or invalid payload.
        5XX:
          description: Server error – e.g., issue on the receiving endpoint.
  new_influencer_post:
    post:
      summary: New Influencer Post
      description: >
        This webhook is triggered when an influencer publishes a new post on
        social  media that is linked to a deal.  

        The receiving endpoint can use `X-InfluencerHero-Timestamp` and 
        `X-InfluencerHero-Signature` to verify authenticity via HMAC-SHA256.
      operationId: newInfluencerPost
      parameters:
        - $ref: '#/components/parameters/InfluencerHeroTimestamp'
        - $ref: '#/components/parameters/InfluencerHeroSignature'
      requestBody:
        description: Payload containing information about the new influencer post.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                post_information:
                  type: object
                  description: Details of the influencer's social media post.
                  properties:
                    account_id:
                      type: integer
                      description: Unique account ID from Influencer Hero.
                    brand_id:
                      type: integer
                      description: ID of the brand or organization the post is for.
                    post_type:
                      type: string
                      description: >-
                        Type of post (e.g., 'story_post', 'feed_post',
                        'reel_post')
                    post_assets:
                      type: array
                      description: >-
                        List of media assets associated with the post (URLs,
                        file references, etc.).
                      items:
                        type: string
                    post_timestamp:
                      type: string
                      description: Timestamp at which the influencer made the post.
                    platform_media_code:
                      type: string
                      description: Platform-specific code or identifier for the post.
                    platform_user_id:
                      type: string
                      description: User ID of the influencer on the social media platform.
                    platform_handle:
                      type: string
                      description: Influencer's handle on the platform (e.g., 'therock').
                    platform:
                      type: string
                      description: Social media platform (e.g., 'instagram', 'youtube').
                deal_info:
                  $ref: '#/components/schemas/DealInfo'
                deal_id:
                  type: string
                  description: Unique identifier of the deal this post belongs to.
                collab_id:
                  type: string
                  description: Unique identifier of the collaboration.
                deal_url:
                  type: string
                  format: uri
                  description: A direct link to view the deal inside Influencer Hero.
              required:
                - post_information
                - deal_info
                - deal_id
                - collab_id
                - deal_url
            examples:
              default:
                summary: Example New Influencer Post Webhook
                value:
                  post_information:
                    account_id: 3218
                    brand_id: 12398
                    post_type: story_post
                    post_assets:
                      - https://example.com/reel_video_1.mp4
                    post_timestamp: '2025-01-15 10:30:00'
                    platform_media_code: ABC123XYZ
                    platform_user_id: '923478147'
                    platform_handle: therock
                    platform: instagram
                  deal_info:
                    deal_name: therock
                    is_active: true
                    dealflow_funnel_step: 3
                    dealflow_type: outreach
                    dealflow_name: Spring Collection Promo
                    picture_url: >-
                      https://imgp.sptds.icu/v2?mb0KwpL92uYofJiSjDn1%2F6peL1lBwv3s%2BUvShHERlDbrEEwrWumIvR20xZeZXa0LDeIrcniqZeG9S%2F1a5s2Rx3FZdXrWpY%2BmSBJp1l%2FmBGon3rcHA4EfuatZqMhVBzAT
                    nr_followers: 60000
                    full_name: Dwayne Johnson
                    platform: instagram
                    profile_url: https://instagram.com/therock
                  deal_id: deal12345
                  collab_id: collab5678
                  deal_url: https://app.influencer-hero.com/deal/deal12345
      responses:
        '200':
          description: >-
            The server processing the webhook should generally return a 200
            status indicating successful receipt.
        4XX:
          description: Client error – e.g., signature mismatch or invalid payload.
        5XX:
          description: Server error – e.g., issue on the receiving endpoint.
  new_influencer_reply:
    post:
      summary: New Influencer Reply
      description: >
        This webhook is triggered when an influencer replies to an email 
        associated with a particular deal.  

        The receiving endpoint can use `X-InfluencerHero-Timestamp` and 
        `X-InfluencerHero-Signature` to verify authenticity via HMAC-SHA256.
      operationId: newInfluencerReply
      parameters:
        - $ref: '#/components/parameters/InfluencerHeroTimestamp'
        - $ref: '#/components/parameters/InfluencerHeroSignature'
      requestBody:
        description: Payload containing information about the influencer's email reply.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email_information:
                  type: object
                  description: Details about the received email reply.
                  properties:
                    from_addr:
                      type: string
                      description: The sender (influencer's) email address.
                    recipient:
                      type: string
                      description: The primary recipient of the email (brand or user).
                    cc_address:
                      type: string
                      nullable: true
                      description: Any CC recipients for this reply, if present.
                    email_subject:
                      type: string
                      description: Subject line of the reply email.
                    email_body:
                      type: string
                      description: Plaintext version of the email body.
                    received_time:
                      type: string
                      format: date-time
                      description: Timestamp of when the email reply was received.
                deal_info:
                  $ref: '#/components/schemas/DealInfo'
                deal_id:
                  type: string
                  description: Unique identifier of the deal this email reply is for.
                deal_url:
                  type: string
                  format: uri
                  description: A direct link to view the deal inside Influencer Hero.
              required:
                - email_information
                - deal_info
                - deal_id
                - deal_url
            examples:
              default:
                summary: Example New Influencer Reply Webhook
                value:
                  email_information:
                    from_addr: janedoe@example.com
                    recipient: brand@mycompany.com
                    cc_address: team@mycompany.com
                    email_subject: 'Re: Collaboration Proposal'
                    email_body: >-
                      Thank you for reaching out. I'd love to discuss more
                      details...
                    received_time: '2025-01-16 09:15:00'
                  deal_info:
                    deal_name: therock
                    is_active: true
                    dealflow_funnel_step: 3
                    dealflow_type: outreach
                    dealflow_name: Spring Collection Promo
                    picture_url: >-
                      https://imgp.sptds.icu/v2?mb0KwpL92uYofJiSjDn1%2F6peL1lBwv3s%2BUvShHERlDbrEEwrWumIvR20xZeZXa0LDeIrcniqZeG9S%2F1a5s2Rx3FZdXrWpY%2BmSBJp1l%2FmBGon3rcHA4EfuatZqMhVBzAT
                    nr_followers: 60000
                    full_name: Dwayne Johnson
                    platform: instagram
                    profile_url: https://instagram.com/therock
                  deal_id: deal12345
                  deal_url: https://app.influencer-hero.com/deal/deal12345
      responses:
        '200':
          description: >-
            The server processing the webhook should generally return a 200
            status indicating successful receipt.
        4XX:
          description: Client error – e.g., signature mismatch or invalid payload.
        5XX:
          description: Server error – e.g., issue on the receiving endpoint.
components:
  parameters:
    InfluencerHeroTimestamp:
      name: X-InfluencerHero-Timestamp
      in: header
      required: true
      schema:
        type: string
      description: |
        Unix timestamp (in seconds) at which the webhook was sent.
    InfluencerHeroSignature:
      name: X-InfluencerHero-Signature
      in: header
      required: true
      schema:
        type: string
      description: >
        HMAC-SHA256 signature computed using your webhook signing key  and the
        request body.
  schemas:
    DealInfo:
      type: object
      description: A lightweight summary of the influencers deal.
      properties:
        deal_name:
          type: string
          description: Deal name / Influencer handle
        is_active:
          type: boolean
          description: Indicates if the deal is still active.
        dealflow_funnel_step:
          type: integer
          description: Funnel step of the deal in the respective dealflow (0-4)
        dealflow_type:
          type: string
          description: Whether the dealflow is an outreach or relationship dealflow
        dealflow_name:
          type: string
          description: Name of the dealflow
        picture_url:
          type: string
          format: uri
          description: Influencer Profile Picture URL
        nr_followers:
          type: integer
          description: Number of followers of the influencer
        full_name:
          type: string
          description: >-
            Full name for the influencer, as indicated on his social media
            account
        platform:
          type: string
          description: Indicates which social media platform is primarily used.
        profile_url:
          type: string
          format: uri
          description: Link to the influencer's social media page
tags:
  - name: Test endpoints
    description: Endpoints to test authenticated and public requests
  - name: CRM
    description: Endpoints related to CRM functionalities.
  - name: Affiliate Tracking
    description: >-
      [Advanced] Server-side endpoints for tracking affiliate actions and
      performance. For most use cases, the [client-side tracking
      script](https://docs.influencer-hero.com/tracking_script) will be
      sufficient.
  - name: Account
    description: Account-related functionalities for dealflow and brand searching.
