Create a new Staff Member

post

https://api.servicem8.com/api_1.0/staff.json

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.

Body Params

Staff Member record to create

first

string

required

length ≤ 30

Staff First Name

last

string

required

length ≤ 30

Staff Last Name

string

required

Staff Email Address. This is also your login name.

mobile

string

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

lng

float

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

lat

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_timestamp

string

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_title

string

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_uuid

uuid

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

navigating_timestamp

string

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_timestamp

string

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.

color

string

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_url

string

DEPRECATED

status_message

string

Short message summarising the staff's current status.

status_message_timestamp

string

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_schedule

integer

enum

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]

Allowed:

uuid

Unique identifier for this record

can_receive_push_notification

string

security_role_uuid

uuid

labour_material_uuid

uuid

Responses

200Success

400Bad Request - The request is malformed or contains invalid parameters

401Unauthorized - Authentication credentials are missing or invalid

403Forbidden - You don't have permission to create this resource

429Too Many Requests - You have exceeded the rate limit

500Internal Server Error - An unexpected error occurred on the server