openapi: 3.0.3
info:
  title: Everflow Network API - Affiliate Users
  description: >
    Endpoints for managing affiliate (partner) user accounts from the network
    level. Affiliate users are individual people who belong to a partner
    account. Networks can create, update, and retrieve these users to control
    who has access to the partner portal.
  version: 1.0.0
servers:
  - url: https://api.eflow.team/v1
tags:
  - name: Affiliate Users
paths:
  /networks/affiliates/{affiliateId}/users:
    get:
      summary: List Affiliate Users
      tags:
        - Affiliate Users
      parameters:
        - in: path
          name: affiliateId
          required: true
          schema:
            type: integer
          description: The ID of the affiliate whose users you want to fetch.
        - in: query
          name: relationship
          required: false
          schema:
            type: string
            enum:
              - logins
              - api
              - affiliate_status
              - customizations
          description: >
            Include additional related data in the response. Multiple relationships can be supplied
            by repeating the `relationship` query parameter. Supported values: `logins` (includes
            the users' list of logins), `api` (includes the users' API key and whitelisted IPs),
            `affiliate_status` (includes the status of the affiliate to which the user belongs),
            `customizations` (includes the users' customizations).

            `affiliate_status` populates `relationship.affiliate_account_status` (always returned,
            whether requested or not) and `customizations` populates `relationship.customization`
            (singular). An unrecognised value is ignored.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    description: List of affiliate users.
                    items:
                      $ref: "#/components/schemas/AffiliateUser"
              example:
                users:
                  - network_affiliate_user_id: 17
                    network_id: 1
                    network_affiliate_id: 1
                    first_name: "Bob"
                    last_name: "Smith"
                    email: "my.everflow@gmail.com"
                    title: ""
                    work_phone: "9655433513"
                    cell_phone: ""
                    instant_messaging_id: 0
                    instant_messaging_identifier: ""
                    language_id: 1
                    timezone_id: 75
                    currency_id: "USD"
                    account_status: "active"
                    relationship:
                      affiliate_account_status: "active"
      security:
        - API Key: []
    post:
      summary: Create Affiliate User
      tags:
        - Affiliate Users
      parameters:
        - in: path
          name: affiliateId
          required: true
          schema:
            type: integer
          description: The ID of the affiliate for whom to create a user.
        - in: query
          name: notification
          schema:
            type: boolean
            default: true
          description: Whether to send a welcome notification email to the user. Defaults to `true` when omitted.
      requestBody:
        required: true
        content:
          application/json:
            example:
              first_name: "Bob"
              last_name: "Smith"
              email: "aff.user.doctest.new@example.com"
              language_id: 1
              timezone_id: 90
              currency_id: "USD"
              account_status: "active"
              initial_password: ""
              title: "CEO"
              work_phone: "1234567788"
              instant_messaging_id: 0
            schema:
              type: object
              required:
                - first_name
                - last_name
                - email
                - language_id
                - timezone_id
                - currency_id
                - account_status
              properties:
                first_name:
                  type: string
                  description: The affiliate user's first name.
                last_name:
                  type: string
                  description: The affiliate user's last name.
                email:
                  type: string
                  description: The affiliate user's email. Must be unique among all affiliate users. Is used to log in the platform.
                language_id:
                  type: integer
                  description: The affiliate user's language ID. This is limited to the value `1` (English).
                timezone_id:
                  type: integer
                  description: >
                    The affiliate user's timezone ID. Can be found using the
                    [metadata API](/api-reference/get-metatimezones).
                title:
                  type: string
                  description: The affiliate user's title.
                work_phone:
                  type: string
                  description: The affiliate user's work phone number.
                cell_phone:
                  type: string
                  description: The affiliate user's cell phone number.
                instant_messaging_id:
                  type: integer
                  description: >
                    The ID of an instant messaging platform. Allows you to save their
                    identifier for further reference. `0` = None, `1` = Skype,
                    `2` = Yahoo Messenger, `3` = Telegram, `4` = WhatsApp, `5` = Other.
                instant_messaging_identifier:
                  type: string
                  description: The affiliate user's instant messaging identifier, if `instant_messaging_id` was different than `0`.
                currency_id:
                  type: string
                  description: >
                    The affiliate user's currency ID. Can be found using the
                    [metadata API](/api-reference/get-metacurrencies).
                account_status:
                  type: string
                  enum:
                    - active
                    - inactive
                  description: The affiliate user's account status. Can be either `active` or `inactive`.
                initial_password:
                  type: string
                  description: >
                    The affiliate user's login password. If left empty, the affiliate will
                    be sent an email asking to set their password. If supplied, the password
                    must have a length of at least 12 characters.
      responses:
        "200":
          description: ""
          content:
            application/json:
              example:
                network_affiliate_user_id: 166
                network_id: 1
                network_affiliate_id: 36
                first_name: "Jane"
                last_name: "Doe"
                email: "jane.doe@example.com"
                title: ""
                work_phone: ""
                cell_phone: ""
                instant_messaging_id: 0
                instant_messaging_identifier: ""
                language_id: 1
                timezone_id: 90
                currency_id: "USD"
                account_status: "active"
                time_created: 1774701394
                time_saved: 1774701394
                relationship:
                  affiliate_account_status: "active"
              schema:
                $ref: "#/components/schemas/AffiliateUser"
      security:
        - API Key: []
  /networks/affiliates/{affiliateId}/users/{userId}:
    get:
      summary: Get Affiliate User
      description: >
        Retrieve a single affiliate user by their user ID.
      tags:
        - Affiliate Users
      parameters:
        - in: path
          name: affiliateId
          required: true
          schema:
            type: integer
          description: The ID of the affiliate whose user you want to fetch.
        - in: path
          name: userId
          required: true
          schema:
            type: integer
          description: The ID of the user you want to fetch.
        - in: query
          name: relationship
          required: false
          schema:
            type: string
            enum:
              - logins
              - api
              - affiliate_status
              - customizations
          description: >
            Include additional related data in the response. Multiple relationships can be supplied
            by repeating the `relationship` query parameter. Supported values: `logins` (includes
            the user's list of logins), `api` (includes the user's API key and whitelisted IPs),
            `affiliate_status` (includes the status of the affiliate to which the user belongs),
            `customizations` (includes the user's customizations).

            `affiliate_status` populates `relationship.affiliate_account_status` (always returned,
            whether requested or not) and `customizations` populates `relationship.customization`
            (singular). An unrecognised value is ignored.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AffiliateUser"
              example:
                network_affiliate_user_id: 17
                network_id: 1
                network_affiliate_id: 13
                first_name: "Bob"
                last_name: "Smith"
                email: "my.everflow@gmail.com"
                title: "CEO"
                work_phone: "9655433513"
                cell_phone: ""
                instant_messaging_id: 0
                instant_messaging_identifier: ""
                language_id: 1
                timezone_id: 75
                currency_id: "USD"
                account_status: "active"
                relationship:
                  affiliate_account_status: "active"
        "404":
          description: Affiliate user not found.
      security:
        - API Key: []
    put:
      summary: Update Affiliate User
      tags:
        - Affiliate Users
      parameters:
        - in: path
          name: affiliateId
          required: true
          schema:
            type: integer
          description: The ID of the affiliate whose user you want to update.
        - in: path
          name: userId
          required: true
          schema:
            type: integer
          description: The ID of the user you want to update.
      requestBody:
        required: true
        content:
          application/json:
            example:
              first_name: "Bob"
              last_name: "Smith"
              email: "aff.user.updated@example.com"
              language_id: 1
              timezone_id: 90
              currency_id: "USD"
              account_status: "active"
              title: "CEO"
              work_phone: "1234567788"
              instant_messaging_id: 0
            schema:
              type: object
              required:
                - first_name
                - last_name
                - email
                - language_id
                - timezone_id
                - currency_id
                - account_status
              properties:
                first_name:
                  type: string
                  description: The affiliate user's first name.
                last_name:
                  type: string
                  description: The affiliate user's last name.
                email:
                  type: string
                  description: The affiliate user's email. Must be unique among all affiliate users. Is used to log in the platform.
                language_id:
                  type: integer
                  description: The affiliate user's language ID. This is limited to the value `1` (English).
                timezone_id:
                  type: integer
                  description: >
                    The affiliate user's timezone ID. Can be found using the
                    [metadata API](/api-reference/get-metatimezones).
                title:
                  type: string
                  description: The affiliate user's title.
                work_phone:
                  type: string
                  description: The affiliate user's work phone number.
                cell_phone:
                  type: string
                  description: The affiliate user's cell phone number.
                instant_messaging_id:
                  type: integer
                  description: >
                    The ID of an instant messaging platform. Allows you to save their
                    identifier for further reference. `0` = None, `1` = Skype,
                    `2` = Yahoo Messenger, `3` = Telegram, `4` = WhatsApp, `5` = Other.
                instant_messaging_identifier:
                  type: string
                  description: The affiliate user's instant messaging identifier, if `instant_messaging_id` was different than `0`.
                currency_id:
                  type: string
                  description: >
                    The affiliate user's currency ID. Can be found using the
                    [metadata API](/api-reference/get-metacurrencies).
                account_status:
                  type: string
                  enum:
                    - active
                    - inactive
                  description: The affiliate user's account status. Can be either `active` or `inactive`.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AffiliateUser"
        "404":
          description: Affiliate user not found.
      security:
        - API Key: []
  /networks/affiliates/{affiliateId}/users/{userId}/sendpasswordresetemail:
    post:
      summary: Reset Affiliate User Password
      tags:
        - Affiliate Users
      parameters:
        - in: path
          name: affiliateId
          required: true
          schema:
            type: integer
          description: The ID of the affiliate.
        - in: path
          name: userId
          required: true
          schema:
            type: integer
          description: The unique affiliate user ID.
      requestBody:
        required: true
        content:
          application/json:
            example:
              email: "affiliate.user@example.com"
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  description: The email address of the affiliate user to send the password reset email to.
      responses:
        "200":
          description: Password reset email sent successfully.
      security:
        - API Key: []
  /networks/affiliateusers:
    get:
      summary: List All Affiliate Users
      tags:
        - Affiliate Users
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AffiliateUser"
      security:
        - API Key: []
components:
  schemas:
    AffiliateUser:
      type: object
      properties:
        network_affiliate_user_id:
          type: integer
          description: Unique affiliate user ID.
        network_id:
          type: integer
          description: The network ID this user belongs to.
        network_affiliate_id:
          type: integer
          description: The affiliate ID this user belongs to.
        first_name:
          type: string
          description: The affiliate user's first name.
        last_name:
          type: string
          description: The affiliate user's last name.
        email:
          type: string
          description: The affiliate user's email address. Is used to log in the platform.
        title:
          type: string
          description: The affiliate user's title.
        work_phone:
          type: string
          description: The affiliate user's work phone number.
        cell_phone:
          type: string
          description: The affiliate user's cell phone number.
        instant_messaging_id:
          type: integer
          description: The ID of an instant messaging platform.
        instant_messaging_identifier:
          type: string
          description: The affiliate user's instant messaging identifier.
        language_id:
          type: integer
          description: The affiliate user's language ID.
        timezone_id:
          type: integer
          description: The affiliate user's timezone ID.
        currency_id:
          type: string
          description: The affiliate user's currency ID.
        account_status:
          type: string
          enum:
            - active
            - inactive
          description: The affiliate user's account status. Can be either `active` or `inactive`.
        relationship:
          type: object
          nullable: true
          description: >
            Related data for this affiliate user. Populate by passing `relationship` query
            parameters (e.g. `?relationship=logins&relationship=api`).
          properties:
            logins:
              type: object
              description: Login history for this user.
              properties:
                total:
                  type: integer
                  description: Total number of login records.
                entries:
                  type: array
                  description: List of login records.
                  items:
                    type: object
            customization:
              type: object
              description: User customization settings.
            audits:
              type: object
              description: Audit history for this user.
              properties:
                total:
                  type: integer
                  description: Total number of audit records.
                entries:
                  type: array
                  description: List of audit records.
                  items:
                    type: object
            api:
              type: object
              description: API key and whitelisted IPs for this user.
              properties:
                total:
                  type: integer
                  description: Total number of API key records.
                entries:
                  type: array
                  description: List of API key records.
                  items:
                    type: object
            affiliate_account_status:
              type: string
              description: >
                The account status of the affiliate this user belongs to.
                Always included in the response, even without requesting
                the `affiliate_status` relationship.
        time_created:
          type: integer
          example: 1734455015
          description: Unix timestamp of when the user was created.
        time_saved:
          type: integer
          example: 1734455015
          description: Unix timestamp of when the user was last updated.
  securitySchemes:
    API Key:
      description: The Everflow API key generated from the Control Center > Security.
      in: header
      name: X-Eflow-Api-Key
      type: apiKey