swagger: '2.0'
info:
  title: Pulse Public Authentication User Details API API
  version: 1.0.1
  description: "The Pulse API is targeted towards developers looking to automate tasks in Pulse. \n\n# Authentication\nAll endpoints in Pulse require authentication.  Legacy endpoints require only a Private API Key, while all new endpoints incorporate JSON Web Tokens.  \n\n**API Key**\nTo consume a Pulse endpoint using API Key authentication, :\n  * Contact Pulse support at support@pulsesoftware.com to enable the Pulse Public API and issue your API key.\n  * Pass the API key in the **'x-Api-Key'** header with each request.\n\nNote: It is recommended to use a User Private API key where possible, rather than the Application Private Key. When using a User API key, functionality will be restricted based on the role of the User for which the API key was generated.  See API endpoint documentation for authorised roles. \n\n**JSON Web Token (JWT)**\nTo consume a Pulse endpoint using JWT authentication:\n  * Contact Pulse support at support@pulsesoftware.com to enable the Pulse Public API and issue your API key.\n  * Request a bearer token from /pulse/jwt, passing the API key in the **'x-Api-Key'** header with the request.\n  * Pass the token issued in the **'Authorization'** header of all requests as **'bearer [token]'**\n\n**Note** Tokens will expire 60 minutes after being issued, at which point your application will need to request a new token.\n\n# Requests\nThe Pulse API follows REST principles.  Data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint. Where possible, Web API uses appropriate HTTP verbs for each action.\nHTTP Verbs:\n  * **GET** Retrieves resources\n  * **POST** Creates resources\n  * **PUT** Changes and/or replaces resources or collections\n  * **DELETE** Deletes resources\n\nThe Pulse API accepts the following ISO-8601 formats for date strings:\n  * Date, Time, Timezone: e.g. \"2021-06-02T21:39:18+00:00\"\n  * Date, Time: e.g. \"2021-06-02T21:39:18Z\"\n  * Date: e.g. \"2021-06-02\"\n\n# Responses\nPulse API returns all response data as a JSON object.  \n\n# Response Status Codes\nPulse API uses the following status codes:\n  * **200** OK - Request succeeded.  Result provided in response body.\n  * **400** Bad Request - Malformed syntax.  See message body for information.\n  * **401** Unauthorised - Missing authentication (API Key or JWT).\n  * **403** Forbidden - API user is not authorised to access requested resource.\n  * **404** Not Found - Request resource does not exist.\n\n# Support\nContact support@pulsesoftware.com for any queries or issues related to this API\n"
  termsOfService: http://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    email: support@pulsesoftware.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
host: '*.pulsesoftware.com'
basePath: /webservices/api
schemes:
- https
- http
tags:
- name: User Details API
  description: API for managing user details in Pulse
paths:
  /security/users/{value}:
    get:
      security:
      - ApiKey: []
      tags:
      - User Details API
      summary: Retrieve user details
      description: Retrieves a list of users matching a provided user identifier. Includes an 'active' flag which indicates whether or not a user is active.
      operationId: getUser
      parameters:
      - name: value
        in: path
        description: UserID, Username or Email of the desired user.
        required: true
        type: string
      produces:
      - application/json
      responses:
        200:
          description: OK. Request completed successfully.
          schema:
            type: array
            items:
              $ref: '#/definitions/GetResponse'
        403:
          description: Missing x-api-key or the given x-api-key does not grant client with access to this API.
        404:
          description: User not found in Pulse.
  /security/users:
    get:
      security:
      - ApiKey: []
      tags:
      - User Details API
      summary: Retrieve a complete list of users in Pulse
      description: Returns a list of all users in Pulse (including inactive users). Includes an 'active' flag which indicates whether or not a user is active.
      operationId: getUsers
      produces:
      - application/json
      responses:
        200:
          description: OK. Request completed successfully.
          schema:
            type: array
            items:
              $ref: '#/definitions/GetResponse'
        403:
          description: Missing x-api-key or the given x-api-key does not grant client with access to this API.
    post:
      security:
      - ApiKey: []
      tags:
      - User Details API
      summary: Add a new user to Pulse
      description: Notifications can be enabled for this endpoint. Contact Pulse support at support@pulsesoftware.com to enable notifications via the UserSyncEnableNotification config.
      operationId: addUser
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: User object to be created
        required: true
        schema:
          $ref: '#/definitions/User'
      responses:
        200:
          description: OK. Request completed successfully.
          schema:
            $ref: '#/definitions/UpdateUserResponse'
        403:
          description: Missing x-api-key or the given x-api-key does not grant client with access to this API.
    put:
      security:
      - ApiKey: []
      tags:
      - User Details API
      summary: Replaces an existing user in Pulse or creates a user if the specified user does not exist.
      description: Notifications can be enabled for this endpoint. Contact Pulse support at support@pulsesoftware.com to enable notifications via the UserSyncEnableNotification config.
      operationId: updateUser
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: User object to be updated to
        required: true
        schema:
          $ref: '#/definitions/UpdateUser'
      responses:
        200:
          description: OK. Request completed successfully.
          schema:
            $ref: '#/definitions/UpdateUserResponse'
        403:
          description: Missing x-api-key or the given x-api-key does not grant client with access to this API.
    delete:
      security:
      - ApiKey: []
      tags:
      - User Details API
      summary: Delete a user from Pulse
      description: Deletes a user from Pulse using the given userId or email
      operationId: deleteUser
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: Requires a <strong>UserId</strong> or <strong>Email</strong> in order lookup the user to delete from Pulse.
        required: true
        schema:
          $ref: '#/definitions/DeleteUser'
      responses:
        200:
          description: ''
        403:
          description: Missing x-api-key or the given x-api-key does not grant client with access to this API.
definitions:
  AdditionalPosition:
    type: object
    required:
    - startDate
    - endDate
    properties:
      positionNumber:
        type: string
        example: '1006'
      positionName:
        type: string
        example: Financial Accountant
      startDate:
        type: string
        example: '2021-02-11'
      endDate:
        type: string
        example: '2021-08-11'
  UpdateUser:
    type: object
    required:
    - userId
    - email
    properties:
      userId:
        type: string
        example: 00000000-0000-0000-0000-000000000000
      email:
        type: string
        example: testuser@mail.com
      firstName:
        type: string
        example: Johnny
      lastName:
        type: string
        example: Samson
      additionalPositions:
        type: array
        items:
          $ref: '#/definitions/AdditionalPosition'
      roles:
        type: array
        items:
          type: string
          example: cpruser
      phone:
        type: string
        example: (02) 9983 0039
      mobile:
        type: string
        example: +61 412 030 992
      streetAddress:
        type: string
        example: 1 Talavera Rd
      suburb:
        type: string
        example: Macquarie Park
      state:
        type: string
        example: NSW
      postcode:
        type: string
        example: '2113'
      country:
        type: string
        example: Australia
      payrollNumber:
        type: string
        example: A123B
      positionNumber:
        type: string
        example: '1005'
      positionName:
        type: string
        example: Financial Accountant
      supervisorEmail:
        type: string
        example: super@gmail.com
      divisionName:
        type: string
        example: Business Performance
      divisionCode:
        type: string
        example: BP
      unitName:
        type: string
        example: Finance
      unitCode:
        type: string
        example: FIN
      sectionName:
        type: string
        example: Financial Accounting
      sectionCode:
        type: string
        example: FA
  OnboardingEnrolment:
    type: object
    required:
    - enrol
    properties:
      enrol:
        type: boolean
        example: 'true'
      portalId:
        type: integer
        example: '1'
      dueDate:
        type: string
        example: '2021-12-30'
      activeDate:
        type: string
        example: '2020-12-30'
  DeleteUser:
    type: object
    required:
    - userId
    - email
    properties:
      userId:
        type: string
        example: 00000000-0000-0000-0000-000000000000
      email:
        type: string
        example: jbjovi@gmail.com
    xml:
      name: DeleteUser
  User:
    type: object
    required:
    - firstName
    - lastName
    - email
    properties:
      active:
        type: boolean
        example: true
      firstName:
        type: string
        example: John
      lastName:
        type: string
        example: Jovi
      networkLogin:
        type: string
        example: johnj
      phone:
        type: string
        example: (02) 9983 0039
      mobile:
        type: string
        example: +61 412 030 992
      streetAddress:
        type: string
        example: 1 Talavera Rd
      suburb:
        type: string
        example: Macquarie Park
      state:
        type: string
        example: NSW
      postcode:
        type: string
        example: '2113'
      country:
        type: string
        example: Australia
      payrollNumber:
        type: string
        example: A123B
      positionNumber:
        type: string
        example: '1005'
      positionName:
        type: string
        example: Financial Accountant
      applicationDate:
        type: string
        example: '2020-12-30'
      supervisorEmail:
        type: string
        example: super@gmail.com
      onboarding:
        $ref: '#/definitions/OnboardingEnrolment'
      additionalPositions:
        type: array
        items:
          $ref: '#/definitions/AdditionalPosition'
      roles:
        type: array
        items:
          type: string
          example: cpruser
      divisionName:
        type: string
        example: Business Performance
      divisionCode:
        type: string
        example: BP
      unitName:
        type: string
        example: Finance
      unitCode:
        type: string
        example: FIN
      sectionName:
        type: string
        example: Financial Accounting
      sectionCode:
        type: string
        example: FA
      userId:
        type: string
        example: 00000000-0000-0000-0000-000000000000
      email:
        type: string
        example: jbjovi@gmail.com
    xml:
      name: User
  UpdateUserResponse:
    type: object
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/PulseApiError'
      data:
        $ref: '#/definitions/GetResponse'
  GetResponse:
    type: object
    properties:
      active:
        type: boolean
        example: true
      firstName:
        type: string
        example: John
      lastName:
        type: string
        example: Jovi
      networkLogin:
        type: string
        example: johnj
      phone:
        type: string
        example: (02) 9983 0039
      mobile:
        type: string
        example: +61 412 030 992
      streetAddress:
        type: string
        example: 1 Talavera Rd
      suburb:
        type: string
        example: Macquarie Park
      state:
        type: string
        example: NSW
      postcode:
        type: string
        example: '2113'
      country:
        type: string
        example: Australia
      payrollNumber:
        type: string
        example: A123B
      positionNumber:
        type: string
        example: '1005'
      positionName:
        type: string
        example: Financial Accountant
      applicationDate:
        type: string
        example: '2020-12-30'
      supervisorEmail:
        type: string
        example: super@gmail.com
      onboarding:
        $ref: '#/definitions/OnboardingEnrolment'
      additionalPositions:
        type: array
        items:
          $ref: '#/definitions/AdditionalPosition'
      roles:
        type: array
        items:
          type: string
          example: cpruser
      divisionName:
        type: string
        example: Business Performance
      divisionCode:
        type: string
        example: BP
      unitName:
        type: string
        example: Finance
      unitCode:
        type: string
        example: FIN
      sectionName:
        type: string
        example: Financial Accounting
      sectionCode:
        type: string
        example: FA
      userId:
        type: string
        example: 00000000-0000-0000-0000-000000000000
      email:
        type: string
        example: jbjovi@gmail.com
    xml:
      name: User
  PulseApiError:
    type: object
    properties:
      code:
        type: string
        example: PRF/ProgressUpdate/Reference_MissingReference
      detail:
        type: string
        example: Mandatory field Reference was not supplied.
      source:
        type: string
        example: /data/0/uniqueReference
securityDefinitions:
  ApiKey:
    type: apiKey
    name: x-Api-Key
    in: header
  BearerJWT:
    type: apiKey
    name: Authorisation
    in: header
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io