Locus PersonnelMaster API

openapi: 3.2.0
info:
  title: Locus HomebaseMaster Personnel Master API
  description: Manage your deliveries with the Locus API
  version: 1.0.0
servers:
- url: https://oms.locus-api.com/v1
tags:
- name: PersonnelMaster
paths:
  /client/{clientId}/personnel-master/create-compact:
    parameters:
    - $ref: '#/components/parameters/ClientIdParam'
    post:
      summary: Create personnel with minimal request
      description: Create personnel in the system, with minimal fields required
      operationId: createPersonnelCompact
      parameters:
      - $ref: '#/components/parameters/OverwriteParam'
      tags:
      - PersonnelMaster
      responses:
        '200':
          description: Personnel object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonnelResponse'
      security:
      - locusauth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompactCreatePersonnelRequest'
        description: Request object
        required: true
  /client/{clientId}/personnel-master/{personnelId}/status:
    parameters:
    - $ref: '#/components/parameters/ClientIdParam'
    - $ref: '#/components/parameters/PersonnelIdParam'
    post:
      summary: Update personnel status
      description: Enable or disable the personnel
      operationId: updatePersonnelStatus
      tags:
      - PersonnelMaster
      responses:
        '200':
          description: Personnel object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonnelResponse'
      security:
      - locusauth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityStatusUpdateRequest'
        description: Request object
        required: true
components:
  schemas:
    EntityStatusUpdateRequest:
      description: Wrapper for entity status update request
      required:
      - status
      properties:
        status:
          $ref: '#/components/schemas/EntityStatus'
    TransporterId:
      type: object
    CompactCreatePersonnelRequest:
      description: Minimal request for creating personnels
      required:
      - id
      - name
      - email
      - role
      - teams
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
        role:
          type: string
        hasAllTeamsAccess:
          description: Boolean indicating whether the personnel has access to all teams or not
          type: boolean
          default: false
        teams:
          description: Ids of the teams to which this personnel belongs
          type: array
          items:
            type: string
        customProperties:
          description: Additional properties which clients wants to have along with standard entity properties
          type: object
          additionalProperties:
            type: string
    PersonnelResponse:
      description: Wrapper for personnel create request
      allOf:
      - $ref: '#/components/schemas/BasePersonnel'
      - type: object
        properties:
          accessType:
            $ref: '#/components/schemas/AccessType'
          authToken:
            $ref: '#/components/schemas/AuthToken'
          role:
            description: Role assigned to personnel
            type: string
          businessUnitIds:
            description: Id of the business units to which personnel belongs.
            type: array
            items:
              $ref: '#/components/schemas/BusinessUnitId'
    BasePersonnel:
      description: Base class for personnel related models
      allOf:
      - $ref: '#/components/schemas/EntityDefinition'
      - type: object
        properties:
          email:
            $ref: '#/components/schemas/EmailAddress'
          phone:
            $ref: '#/components/schemas/PhoneNumber'
          photoUrl:
            type: string
          personnelType:
            description: Type of personnel
            $ref: '#/components/schemas/PersonnelType'
          roleMasterId:
            $ref: '#/components/schemas/RoleMasterId'
          roleMaster:
            $ref: '#/components/schemas/MasterRole'
          teams:
            description: Ids of the teams to which this personnel belongs
            type: array
            items:
              $ref: '#/components/schemas/TeamId'
          transporters:
            description: Ids of the transporters which this personnel has access to
            type: array
            items:
              $ref: '#/components/schemas/TransporterId'
          hasAllTeamsAccess:
            description: Boolean indicating whether the personnel has access to all teams or not
            type: boolean
            default: false
          canManageEntities:
            description: Boolean indicating whether the personnel can manage entities or not. Only personnel with write access can have manage permission
            type: boolean
            default: false
          canVerifyEntities:
            description: Boolean indicating whether the personnel can verify entities or not. Only personnel with write access can have verify permission
            type: boolean
            default: false
          canManagePersonnel:
            description: Boolean indicating whether the personnel can manage entities or not. Only personnel with write access can have manage permission
            type: boolean
            default: false
          language:
            description: Language preference of the personnel
            type: string
          customRole:
            description: Client specified custom role of personnel
            type: string
          timezone:
            description: Time zone of the personnel
            type: string
    PersonnelType:
      type: object
    MasterRole:
      description: Role Master entity
      allOf:
      - $ref: '#/components/schemas/EntityDefinition'
      - type: object
        required:
        - id
        properties:
          allowedOperations:
            type: array
            items:
              type: string
          roleType:
            $ref: '#/components/schemas/RoleType'
    BusinessUnitId:
      required:
      - clientId
      - businessUnitId
      properties:
        clientId:
          type: string
        businessUnitId:
          type: string
    EntityDefinition:
      type: object
    AuthToken:
      required:
      - token
      - userId
      - authProvider
      properties:
        token:
          type: string
        userId:
          type: string
        authProvider:
          type: string
          enum:
          - TAXY_CLIENT
    RoleType:
      type: string
      enum:
      - CLIENT_PERSONNEL
      - TRANSPORTER_PERSONNEL
      - RIDER
      - CLIENT
      - SYSTEM
      - API_CREDENTIAL
    EmailAddress:
      type: object
    TeamId:
      type: object
    EntityStatus:
      type: object
    PhoneNumber:
      description: Phone number information
      required:
      - phoneNumber
      properties:
        phoneNumber:
          type: string
        isVerified:
          description: Flag to denote if rider's phone number is verified
          type: boolean
          default: false
        verifiedAt:
          description: Timestamp of verification of phone number
          type: string
          format: date-time
    RoleMasterId:
      type: object
    AccessType:
      description: User's access
      type: string
      enum:
      - READ
      - WRITE
  parameters:
    ClientIdParam:
      name: clientId
      in: path
      description: Id of the client
      required: true
      schema:
        type: string
    PersonnelIdParam:
      name: personnelId
      in: path
      description: Id of the personnel
      required: true
      schema:
        type: string
    OverwriteParam:
      name: overwrite
      in: query
      description: Boolean flag if true, will overwrite the existing entity
      required: false
      schema:
        type: boolean
  securitySchemes:
    locusauth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization