openapi: 3.0.0
info:
  title: Nectar Public Analytics Custom Awards 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: Custom Awards
paths:
  /v1/custom-awards:
    get:
      summary: Gets custom awards
      description: Returns a page (default 25) of custom awards
      security:
      - BearerAuth: []
      parameters:
      - name: page
        in: query
        description: The page number
        schema:
          type: number
          default: 1
      - name: automationEnabled
        in: query
        description: Only fetch awards that are enabled for automation
        schema:
          type: boolean
          default: false
      - name: allTime
        in: query
        description: Gets all time data with no pagination. Only keys with the `INTEGRATION` scope can use this.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SuccessfulResponse'
                - $ref: '#/components/schemas/CustomAwardsResponse'
                - $ref: '#/components/schemas/PageInfo'
        '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'
      tags:
      - Custom Awards
  /v1/custom-awards/send:
    post:
      summary: Sends a custom award to recipients
      description: 'Sends a custom award to one or more recipients within the company.

        Awards can include optional messages and point values. All recipients

        must be valid user UUIDs within the organization.

        '
      security:
      - BearerAuth: []
      requestBody:
        description: The request body requires `awardUuid` and either `recipientUuids` or `recipientEmails` to be provided, but not both.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomAwardsBody'
      responses:
        '200':
          description: Custom award sent successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SuccessfulResponse'
        '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'
      tags:
      - Custom Awards
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:
    CustomAwardsBody:
      type: object
      description: Request body for sending custom awards. Either `recipientUuids`, `recipientEmails`, or both must be provided.
      required:
      - awardUuid
      properties:
        awardUuid:
          type: string
          description: UUID of the custom award template to send (required)
        recipientUuids:
          type: array
          description: Array of recipient user UUIDs. Required if `recipientEmails` is not provided.
          items:
            type: string
        recipientEmails:
          type: array
          description: Array of recipient user emails. Required if `recipientUuids` is not provided.
          items:
            type: string
        message:
          type: string
          description: Optional personal message to include with the award.
        points:
          type: number
          description: Optional point value to include with the award (must be positive).
      anyOf:
      - required:
        - recipientEmails
      - required:
        - recipientUuids
    Response:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          - failure
    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
    CustomAwardsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            awards:
              type: array
              items:
                type: object
                properties:
                  uuid:
                    type: string
                  name:
                    type: string
                  points:
                    type: number
                    nullable: true
                  message:
                    type: string
                  fixed_points:
                    type: boolean
    SuccessfulResponse:
      allOf:
      - $ref: '#/components/schemas/Response'
      - type: object
        properties:
          status:
            type: string
            enum:
            - success
          links:
            $ref: '#/components/schemas/Links'
    PageInfo:
      type: object
      properties:
        data:
          type: object
          properties:
            pageInfo:
              type: object
              properties:
                page:
                  type: number
                pageSize:
                  type: number
                total:
                  type: number
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT