Nectar Recognition API

openapi: 3.0.0
info:
  title: Nectar Public Analytics Recognition 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: Recognition
paths:
  /v1/recognition/feed:
    get:
      summary: Gets the companies recognition feed
      security:
      - BearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SuccessfulResponse'
                - $ref: '#/components/schemas/ShoutoutsResponse'
            text/csv:
              schema:
                type: string
        '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'
      parameters:
      - name: type
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - nomination_post
            - nomination_response
            - birthday
            - anniversary
            - award
            - challenge
            - welcome
            - setup
            - shoutout
        explode: false
        style: form
        description: Type of post
      - name: private
        in: query
        schema:
          type: boolean
      - name: hidden_from_leaderboard
        in: query
        schema:
          type: boolean
      - name: deleted
        in: query
        schema:
          type: boolean
          default: false
      - name: minify
        in: query
        schema:
          type: boolean
          default: false
        description: Get only minified user data. Only for 'text/csv' format
      - name: expand
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - user
        explode: false
        style: form
        description: Return each users' expanded data
      - name: cursor
        in: query
        schema:
          type: number
        description: Unix timestamp for next date range of feed entries
      - name: start-date
        in: query
        schema:
          type: string
          format: date
        description: 'Start Date of range to get data from as defined by RFC 3339,

          section 5.6, for example, 2017-07-21.'
      - name: end-date
        in: query
        schema:
          type: string
          format: date
        description: 'End Date of range to get data from as defined by RFC 3339,

          section 5.6, for example, 2017-07-21.

          If defined, start-date is required.'
      - name: all_time
        in: query
        schema:
          type: boolean
        description: Gets all time data with no pagination. Only keys with the `AI_INSIGHT` scope can use this.
      tags:
      - Recognition
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
    BaseUser:
      allOf:
      - type: object
        properties:
          id:
            type: string
          email:
            type: string
            format: email
          employee_id:
            type: string
            nullable: true
          first_name:
            type: string
          last_name:
            type: string
          username:
            type: string
          phone_number:
            type: string
            example: 123-456-7890
            nullable: true
          department:
            type: string
            nullable: true
          office_location:
            type: string
            nullable: true
          job_title:
            type: string
            nullable: true
          language:
            type: string
            nullable: true
          active:
            type: boolean
          invite_email_sent:
            type: boolean
            description: Indicates whether an invite email was sent for this user during this request. Only present in PUT responses. Returns true when the send_invites query parameter is present and user_invited is true in the request body for this user.
      - $ref: '#/components/schemas/Links'
    ExpandedUser:
      allOf:
      - $ref: '#/components/schemas/BaseUser'
      - type: object
        properties:
          user_role:
            type: string
            enum:
            - Administrator
            - Manager
            - Employee
          preferred_name:
            type: string
            nullable: true
          birth_date:
            type: string
            nullable: true
          hire_date:
            type: string
            format: date
            nullable: true
          inactive_date:
            type: string
            format: date
            nullable: true
          user_invited:
            type: boolean
          user_onboarded:
            type: boolean
          manager_email:
            type: string
            format: email
            nullable: true
          workspaces:
            type: array
            items:
              type: string
          giveable_points:
            type: number
          redeemable_points:
            type: number
          logged_in_once:
            type: boolean
          custom_properties:
            type: object
            additionalProperties: true
            example:
              custom_property_1: string
    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
    Shoutout:
      type: object
      properties:
        id:
          type: string
        user:
          anyOf:
          - $ref: '#/components/schemas/BaseUser'
          - $ref: '#/components/schemas/ExpandedUser'
        receivers:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/BaseUser'
            - $ref: '#/components/schemas/ExpandedUser'
        message:
          type: string
        amount:
          type: number
        core_values:
          type: array
          items:
            type: string
        created_at:
          type: string
        comments:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              sender:
                anyOf:
                - $ref: '#/components/schemas/BaseUser'
                - $ref: '#/components/schemas/ExpandedUser'
                - type: string
              message:
                type: string
              reactions:
                type: string
        private:
          type: boolean
        image_url:
          type: string
        reactions:
          type: array
          items:
            type: object
            properties:
              reaction:
                type: string
              user:
                anyOf:
                - $ref: '#/components/schemas/BaseUser'
                - $ref: '#/components/schemas/ExpandedUser'
        scoring_type:
          type: string
          enum:
          - openAI
          - simple
        score:
          type: number
        action:
          type: array
          items:
            type: string
            enum:
            - Admin Added Giveable Points
            - Admin Added Redeemable Points
            - Admin Added Swag Points
            - Anniversary Bonus
            - Approved Claimable Award
            - Birthday Bonus
            - Redeemable to Giveable Point Conversion
            - Challenge Approved
            - Community Recognition
            - Custom Award Redemption
            - Employee Giveable Point Reset
            - Employee Giveable Point Top Off
            - Gave Points
            - Manager Giveable Point Reset
            - Manager Giveable Point Top Off
            - Initial Redeemable Points
            - Nomination Post
            - Nomination Response Post
            - Setup Bonus
            - Welcome Bonus
        type:
          type: string
          enum:
          - nomination_post
          - nomination_response
          - birthday
          - anniversary
          - award
          - challenge
          - welcome
          - setup
          - shoutout
          - community_recognition
    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'
    ShoutoutsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            meta:
              type: object
              properties:
                total:
                  type: integer
                start_date:
                  type: string
                  format: date-time
                end_date:
                  type: string
                  format: date-time
                cursor:
                  type: number
                  nullable: true
            feed:
              type: array
              items:
                $ref: '#/components/schemas/Shoutout'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT