Nectar Flows API

openapi: 3.0.0
info:
  title: Nectar Public Analytics Flows API
  version: 0.1.0
  description: 'Welcome to the Nectar Public API. Here you can view and test the provided endpoints before integrating them into

    your automated systems/tools.


    After requesting access to the API through support, you can generate your API key from the integrations tab in Nectar.


    You can access the [Swagger Definition here](/swagger.yaml).


    ### Authentication


    All endpoints require an API Key. Be sure to set the `Authorization` header key to `Bearer <yourAPIKey>`

    '
  contact:
    name: Nectar Support
    url: https://nectarhr.com/contact-us
servers:
- url: https://api.nectarhr.com
  description: Nectar API Documentation
security:
- BearerAuth: []
tags:
- name: Flows
paths:
  /v1/flows/trigger/{triggerId}:
    post:
      summary: Trigger a Flow for specified users
      description: 'Enrolls users in a Flow via an API trigger. Users can be identified

        by email or userId. All specified users must be valid members of the

        company associated with the API key. If any users are not found, the

        request will fail without enrolling any users.

        '
      tags:
      - Flows
      security:
      - BearerAuth: []
      parameters:
      - name: triggerId
        in: path
        required: true
        description: The ID of the API trigger to invoke
        schema:
          type: string
      requestBody:
        description: 'Provide either `emails` or `userIds` (not both).

          The trigger must be a PAPI or INTEGRATION trigger type. INTEGRATION

          triggers require an API key with the INTEGRATION permission.

          The Flow is resolved automatically from the trigger.

          '
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlowsTriggerBody'
      responses:
        '200':
          description: Users enrolled successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SuccessfulResponse'
                - $ref: '#/components/schemas/FlowsTriggerResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
components:
  responses:
    NotImplemented:
      description: '`NOT IMPLEMENTED`: Method is not implemented on that endpoint.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FailedResponse'
          examples:
            body:
              value:
                status: failure
                error:
                  message: Bad Request
                  code: N0000
    Forbidden:
      description: '`FORBIDDEN`: Request was authenticated but the resource requested is missing or not accessible with that key'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FailedResponse'
          examples:
            body:
              value:
                status: failure
                error:
                  message: UNAUTHORIZED
                  code: N0002
    TooManyRequests:
      description: '`TOO MANY REQUESTS`: Company is being rate limited'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FailedResponse'
          examples:
            body:
              value:
                status: failure
                error:
                  message: TOO MANY REQUESTS
                  code: N0000
    NotFound:
      description: '`NOT FOUND`: The requested resource was not found'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FailedResponse'
          examples:
            body:
              value:
                status: failure
                error:
                  message: Not Found
                  code: N0005
    Unauthorized:
      description: '`UNAUTHORIZED`: Request was sent with an expired or missing API Key'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FailedResponse'
          examples:
            body:
              value:
                status: failure
                error:
                  message: UNAUTHORIZED
                  code: N0002
    BadRequest:
      description: '`BAD REQUEST`: Body or Query Params are malformed (missing, extra, or invalid values)'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FailedResponse'
          examples:
            body:
              value:
                status: failure
                error:
                  message: Bad Request
                  code: N0003
    InternalServerError:
      description: '`INTERNAL SERVER ERROR`: Request was unable to be processed due to a server error. Contact our support team.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FailedResponse'
          examples:
            body:
              value:
                status: failure
                error:
                  message: Bad Request
                  code: N0001
  schemas:
    Response:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          - failure
    FlowsTriggerBody:
      type: object
      description: Request body for triggering a Flow. Provide either emails or userIds.
      properties:
        emails:
          type: array
          items:
            type: string
            format: email
          description: List of user emails to enroll in the Flow
        userIds:
          type: array
          items:
            type: string
          description: List of user IDs to enroll in the Flow
      anyOf:
      - required:
        - emails
      - required:
        - userIds
    FlowsTriggerResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            flowId:
              type: string
            triggerId:
              type: string
            enrolledCount:
              type: number
              description: Number of users successfully enrolled in the flow
            enrolledUserIds:
              type: array
              items:
                type: string
              description: UUIDs of users successfully enrolled
            skippedCount:
              type: number
              description: Number of users skipped because they are already enrolled in this flow
    FailedResponse:
      allOf:
      - $ref: '#/components/schemas/Response'
      - type: object
        properties:
          status:
            type: string
            default: failure
          error:
            type: object
            properties:
              message:
                type: string
              code:
                type: string
                enum:
                - N0001
                - N0002
                - N0003
                - N1001
                - N1002
                - N1003
    Links:
      type: object
      properties:
        self:
          type: string
          format: uri
        related:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              href:
                type: string
                format: uri
    SuccessfulResponse:
      allOf:
      - $ref: '#/components/schemas/Response'
      - type: object
        properties:
          status:
            type: string
            enum:
            - success
          links:
            $ref: '#/components/schemas/Links'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT