Staff Members

Create a new Staff Member

Changed on

OAuth Scope

This endpoint requires the following OAuth scope manage_staff.

Record UUID

UUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the x-record-uuid response header.

post/staff.json

Request

  • Base URL
    https://api.servicem8.com/api_1.0
  • URL
    https://api.servicem8.com/api_1.0/staff.json
  • Auth
    • API key in header X-Api-Key
    • or OAuth 2
      Authorization code: https://api.servicem8.com/oauth/authorize
      Token URL: https://api.servicem8.com/oauth/access_token scopes: manage_staff

Request body

firststring required

Staff First Name

laststring required

Staff Last Name

emailstring email required

Staff Email Address. This is also your login name.

mobilestring

Mobile phone number of the staff member. Used for SMS communications and identification when calling.

lngnumber float

Longitude coordinate of the staff member's current or last known location. Used for tracking staff locations and calculating routes and travel distances.

latnumber float

Latitude coordinate of the staff member's current or last known location. Used for tracking staff locations and calculating routes and travel distances.

geo_timestampstring

The date and time when the staff member's geographic location (lat/lng) was last updated. Format is YYYY-MM-DD HH:MM:SS. Used to determine how recent the location data is.

job_titlestring

The staff member's job title or role within the organization. Used for organizational purposes and displayed in various places throughout the system.

navigating_to_job_uuidstring uuid

UUID of the job the staff member is currently navigating to. Used to track which job a staff member is traveling toward.

navigating_timestampstring

The date and time when the staff member started navigating to a job. Format is YYYY-MM-DD HH:MM:SS. Used to track when navigation began.

navigating_expiry_timestampstring

The date and time when navigation to a job is expected to complete or expire. Format is YYYY-MM-DD HH:MM:SS. Used to determine if navigation is still active.

colorstring

The color assigned to this staff member, represented as a hex color code. Used for visual identification in the schedule, dispatch board, and other interfaces.

custom_icon_urlunknown
status_messagestring

Short message summarising the staff's current status.

status_message_timestampstring

The date and time when the staff member's status message was last updated. Format is YYYY-MM-DD HH:MM:SS. Used to determine how recent the status message is.

hide_from_schedule0 | 1

Boolean flag controlling whether this staff member appears in the schedule view. When true (1), the staff member is hidden from the schedule. When false (0), they appear normally in scheduling interfaces.. Valid values are [0,1]

uuidstring uuid

Unique identifier for this record

can_receive_push_notificationstring
security_role_uuidstring uuid
labour_material_uuidstring uuid

Example request

{
  "geo_timestamp": "2026-03-01 12:00:00",
  "navigating_to_job_uuid": "123e4567-36f6-43f9-9e5e-23f94b960ebb",
  "navigating_timestamp": "2026-03-01 12:00:00",
  "navigating_expiry_timestamp": "2026-03-01 12:00:00",
  "status_message_timestamp": "2026-03-01 12:00:00",
  "uuid": "123e4567-9d5c-42e8-b767-23f9483bb5fb",
  "security_role_uuid": "123e4567-9d7d-4185-ab9c-23f94afa452b",
  "labour_material_uuid": "123e4567-2b10-4d9e-abea-23f946dd59fb"
}

Response

Success

errorCodenumber
messagestring

Example response

{
  "message": "OK"
}

Changes