MRI Software Employees API

openapi: 3.2.0
info:
  title: Mri Software Employees API
  version: '0.1'
  contact:
    email: support@whosonlocation.com
  description: 'Operations tagged Employees across 2 of this provider''s published API definitions: mri-software-onlocation-openapi.json, mri-software-onlocation-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.whosonlocation.com/v1
tags:
- name: Employees
  description: 'Each employee has a profile in OnLocation. It contains their name, contact information, locations, department, user roles and role types, and tokens.


    Use the employee API to return a list of all employees, add, update or delete employees, retrieve photos, and sign employees in or out.


    We recommend that bulk employee changes are managed using our SyncPortal integration rather than the API. Check the OnLocation Help Center for more information.'
paths:
  /staff:
    get:
      tags:
      - Employees
      summary: List all employees
      description: 'Retrieves a list of all employees.


        A comma separated list of tag:value search parameters, a colon separator performs an exact match, a percent separator performs a starts-with search and greater/less than search number/date ranges.


        A person can be matched to an external token which has been assigned to their profile such as RFID card number, a security turnstile controller may search for a staff account to update the onsite status, eg q=token:C1BB7F.'
      operationId: getStaffList
      parameters:
      - name: q
        in: query
        description: Filter by any employee value. It is not possible to filter by custom field elements at this point.
        required: false
        schema:
          type: string
          format: string
        example: location:sydney,name%john,last_login>2015-02-01
      - name: order
        in: query
        description: Order by any element returned, prefix with a - to reverse order.
        required: false
        schema:
          type: string
          format: string
        example: id
      - name: limit
        in: query
        description: Limits the amount of records to return.
        required: false
        schema:
          type: integer
          format: int32
        example: '10'
      - name: If-Modified-Since
        in: header
        description: A UTC timestamp (yyyy-mm-ddThh:mm:ss) . Only entities created or modified since this timestamp will be returned e.g. 2009-11-12T00:00:00
        required: false
        schema:
          type: string
          format: int32
      responses:
        '200':
          description: List of employees
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StaffResponse'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StaffResponse'
        '403':
          description: Access denied to this resource
        '404':
          description: Resource not found
        '500':
          description: Internal server error
    put:
      tags:
      - Employees
      summary: Update multiple employees
      description: 'Updates a list of multiple employees.


        The request body contains a bulk staff list which will be processed by OnLocation for adds/updates/deletes. Set the Content-Type header to identify the the format of the bulk data.


        Tokens can be imported by supplying at least tokenXtype and tokenXnumber columns where X is a arbitrary number, ie token1type. Token issued and expires will only be imported if set, multiple tokens are designated by using a different number for each set.'
      operationId: updateStaffList
      parameters:
      - name: group
        in: query
        description: If uploading a subset of all employees then a group name is mandatory, this allows OnLocation to properly track removed items.
        required: false
        schema:
          type: string
          format: string
      - name: location
        in: query
        description: Override location for all uploaded employees.
        required: false
        schema:
          type: string
          format: string
      - name: content type
        in: header
        description: <p>The format of the uploaded bulk, must be one of:</p><ul><li>Text/csv - comma separated values (,)</li><li>Text/psv - pipe separated values (|)</li><li>Application/json - JSON array type containing one or more JSON objects</li><li>Application/xml - XML, a root node with one or more <staff> elements</li>
        required: false
        schema:
          type: integer
          format: int32
      requestBody:
        description: 'Information used to update an employee or list of employees:'
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/StaffRequest'
      responses:
        '200':
          description: Updated employee record
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StaffResponse'
        '403':
          description: Access denied to this resource
        '500':
          description: Internal server error
    post:
      tags:
      - Employees
      summary: Create an employee
      description: Creates a new employee profile
      operationId: createStaff
      parameters:
      - name: Content-Type
        in: header
        description: The format of the uploaded image data. It must be one of image/png or image/jpeg.
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        description: 'Information used to create an employee:'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StaffRequest'
      responses:
        '201':
          description: Employee created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StaffResponse'
        '403':
          description: Access denied to this resource
        '409':
          description: Staff already exists as
        '500':
          description: Internal server error
    servers:
    - url: https://api.whosonlocation.com/v1
  /staff/{id}/photo:
    get:
      tags:
      - Employees
      summary: Retrieve employee photo
      description: Retrieves an employee's image, filtering with the provided ID. The request body contains the binary image data in the format specified by the Content-Type header.
      operationId: getStaffPhoto
      parameters:
      - name: id
        in: path
        description: ID of the employee
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: The employee's photo, if they have one
        '403':
          description: Access denied to resource
        '404':
          description: Resource not found
        '500':
          description: Internal server error
    put:
      tags:
      - Employees
      summary: Update an employee photo
      description: Updates an employee profile image.
      operationId: updateStaffProfileImage
      parameters:
      - name: id
        in: path
        description: ID of the employee to update
        required: true
        schema:
          type: integer
          format: int32
      - name: Content-Type
        in: header
        description: The format of the uploaded image data, must be image/png or image/jpg
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Updated photo
        '403':
          description: Access denied to this resource
        '404':
          description: Employee not found
        '500':
          description: Internal server error
    head:
      tags:
      - Employees
      summary: Retrieve employee photo metadata
      description: Retrieves a single employee's profile image metadata.'
      operationId: getStaffProfileImage
      parameters:
      - name: id
        in: path
        description: ID of the employee
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Employee profile image data
          content:
            image/png: {}
            image/jpeg: {}
        '403':
          description: Access denied to resource
        '404':
          description: Resource not found
        '500':
          description: Internal server error
    servers:
    - url: https://api.whosonlocation.com/v1
  /staff/{id}:
    get:
      tags:
      - Employees
      summary: Retrieve an employee
      description: 'Retrieves a single employee record, filtering with the provided ID.


        A person can be matched to an external token which has been assigned to their profile such as RFID card number, a security turnstile controller may search for a staff account to update the onsite status, eg q=token:C1BB7F.'
      operationId: getStaff
      parameters:
      - name: id
        in: path
        description: ID of the employee record to retrieve
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Employee matching the provided ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StaffResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/StaffResponse'
        '403':
          description: Access denied to resource
        '404':
          description: Resource not found
        '500':
          description: Internal server error
    put:
      tags:
      - Employees
      summary: Update an employee
      description: Updates a one or more employee profiles.
      operationId: updateStaff
      parameters:
      - name: id
        in: path
        description: ID of the employee or employees to update
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        description: 'Information used to update an employee or list of employees:'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StaffRequest'
      responses:
        '204':
          description: Updated employee record
        '403':
          description: Access denied to this resource
        '500':
          description: Internal server error
    delete:
      tags:
      - Employees
      summary: Delete an employee
      description: Removes the specified employee.
      operationId: deleteStaff
      parameters:
      - name: id
        in: path
        description: ID of the employee to delete
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '204':
          description: Employee deleted
        '403':
          description: Access denied to resource
        '404':
          description: Resource not found
        '500':
          description: Internal server error
    servers:
    - url: https://api.whosonlocation.com/v1
  /staff/roletype:
    get:
      tags:
      - Employees
      summary: List employee role types
      description: 'Returns all employee role types for the organization.


        Without location_id filter: returns each role type with a locations array showing which locations it has been assigned to.


        With q=location_id:N filter: returns only the role types assigned to that location (flat list, no locations array).'
      operationId: getStaffRoleTypeList
      parameters:
      - name: q
        in: query
        description: Filter parameters. Use <code>location_id:N</code> to return only roles for a specific location.
        required: false
        schema:
          type: string
          format: string
        example: location_id:1
      - name: order
        in: query
        description: Specifies an element to order by. Prefix with - to reverse order.
        required: false
        schema:
          type: string
          format: string
        example: name
      - name: limit
        in: query
        description: Limits the number of records to return.
        required: false
        schema:
          type: integer
          format: int32
        example: '100'
      - name: If-Modified-Since
        in: header
        description: A UTC timestamp (yyyy-mm-ddThh:mm:ss). Only entities created or modified since this timestamp will be returned.
        required: false
        schema:
          type: string
          format: string
      responses:
        '200':
          description: List of employee role types
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StaffRoleTypeResponse'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StaffRoleTypeResponse'
        '400':
          description: Invalid input
        '403':
          description: Access denied to this resource
        '500':
          description: Internal server error
    servers:
    - url: https://api.whosonlocation.com/v1
components:
  schemas:
    StaffListResponse:
      properties:
        id:
          type: integer
          format: int32
          example: 823562
        created:
          type: string
          format: date-time
          example: '2021-10-06T15:35:50+13:00'
        modified:
          type: string
          format: date-time
          example: '2021-10-06T16:35:50+13:00'
        account_status:
          type: string
          format: string
          example: new
        last_login:
          type: string
          format: date-time
          example: '2021-11-15T16:35:50+13:00'
        onsite_status:
          type: string
          format: string
          example: offsite
        name:
          type: string
          format: string
          example: Staff Name
        title:
          type: string
          format: string
          example: Mr
        altname:
          type: string
          format: string
          example: Daffy
        email:
          type: string
          format: string
          example: john.doe@example.org
        phone:
          type: string
          format: string
          example: +1 206 555 0123
        mobile:
          type: string
          format: string
          example: +1 206 555 0123
        ice:
          type: string
          format: string
          example: +1 206 555 0123
        setup_method:
          type: string
          format: string
          example: manual
        employee_id:
          type: string
          format: string
          example: '1005'
        location:
          type: string
          format: string
          example: Head Office
        cur_location:
          type: string
          format: string
          example: Head Office
        department:
          type: string
          format: string
          example: Administration
        roles:
          type: array
          items:
            format: string
            example:
            - Safety Office
            - Fire Warden
        role_types:
          type: array
          items:
            format: string
            example:
            - Non-Host
            - Safety Operator
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/StaffTokens'
        remote:
          type: integer
          format: int32
          example: 1
        customfields:
          description: This will return an array of custom fields set for employees. The ID of the custom field corresponds to the ID of the custom fields when using the Customfield endpoint
          type: object
          example:
            '123': custom-field value
          additionalProperties: true
        globalroaming:
          description: This determines whether the employee has global roaming permission.
          type: integer
          format: int32
          enum:
          - 0
          - 1
          example: 1
      type: object
    StaffTokens:
      properties:
        type:
          type: string
          format: string
        number:
          type: integer
          format: int64
        issued:
          type: string
          format: date-time
        expiry:
          type: string
          format: date-time
      type: object
    StaffGlobalRoamingLocation:
      properties:
        id:
          description: The ID of the roaming location
          type: integer
          format: int32
          example: 1
        name:
          description: The name of the roaming location
          type: string
          example: Head Office
      type: object
    StaffResponse:
      allOf:
      - properties:
          globalroaming_locations:
            type: array
            items:
              $ref: '#/components/schemas/StaffGlobalRoamingLocation'
      - $ref: '#/components/schemas/StaffListResponse'
    StaffRequest:
      required:
      - name
      - location
      properties:
        name:
          type: string
          format: string
          example: Staff Name
        title:
          type: string
          format: string
          example: Mr
        altname:
          type: string
          format: string
          example: Daffy
        email:
          type: string
          format: string
          example: example.staff@whosonlocation.com
        phone:
          type: string
          format: string
          example: +1 206 555 0123
        mobile:
          type: string
          format: string
          example: +1 206 555 0123
        ice:
          type: string
          format: string
          example: +1 206 555 0123
        employee_id:
          type: integer
          format: int32
          example: 301
        onsite_status:
          type: string
          format: string
          example: offsite
        location:
          type: string
          format: string
          example: Head Office
        roletype:
          type: array
          items:
            format: string
            example:
            - Non-Host
            - Safety Operator
        customfields:
          description: This field is deprecated and will be removed in the future. Please use the `cf` field instead.
          type: array
          items:
            format: string
            example:
            - Deprecated, please use the cf-parameter instead
          deprecated: true
        cf:
          description: This will return an object of custom fields set for employees. The key of the custom field corresponds to the ID of the custom fields when using the Customfield endpoint
          type: object
          example:
            '123': custom-field value
          additionalProperties: true
        globalroaming:
          description: This determines whether the employee has global roaming permission.
          type: integer
          format: int32
          enum:
          - 0
          - 1
          example: 1
        globalroaming_locations:
          description: The IDs of the global roaming locations to which the employee has access. This field is effective when `globalroaming` is set to `true` or the `globalroaming` parameter is ommitted and the employee already has global roaming permission.
          type: array
          items:
            format: integer
            example:
            - 1500
            - 3000
            - 2600
      type: object
    StaffRoleTypeResponse:
      title: StaffRoleTypeResponse
      description: Employee role type. When no location_id filter is provided, includes a 'locations' array showing which locations the role is assigned to. When filtered by location_id, returns a flat list where id is the role ID and created/modified are from the location_role assignment record.
      properties:
        id:
          description: Role ID.
          type: integer
          format: int32
          example: 5
        name:
          description: Name of the role
          type: string
          format: string
          example: Account Manager
        created:
          description: Date and time the role was created
          type: string
          format: date-time
          example: '2025-01-08T06:04:00+00:00'
        modified:
          description: Date and time the role was last modified
          type:
          - string
          - 'null'
          format: date-time
          example: '2025-06-01T10:00:00+00:00'
        locations:
          description: Locations this role is assigned to. Only returned when no location_id filter is applied.
          type:
          - array
          - 'null'
          items:
            properties:
              id:
                type: integer
                example: 1
              name:
                type: string
                example: Head Office
            type: object
      type: object
x-refined-from:
- mri-software-onlocation-openapi.json
- mri-software-onlocation-openapi.yml