Documentation Powered by ReDoc

Field Service API (v1)

Download OpenAPI specification:Download

API for Satalia Field Service.

Base Url

https://ondemand.satalia.com/api/v1

Authentication

apiKeyHeader

API key which can be found in the settings page of the fieldservice app.

Security Scheme Type API Key
Header parameter name: api-key

accIdHeader

Account ID which can be found in the settings page of the fieldservice app.

Security Scheme Type API Key
Header parameter name: acc-id

Employees

Employees scheduled via this application.

Get employees

Return a list of employees

Authorizations:
apiKeyHeaderaccIdHeader
query Parameters
sort_by
string

The field to sort the results by

order_by
any
Enum: "asc" "desc"
Example: order_by=asc

Whether to sort results in ascending or descending order

region_id
string

Return only employees attached to this region

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": [
    ]
}

Add new employee

Add employee

Authorizations:
apiKeyHeaderaccIdHeader
Request Body schema: application/json

Employee to add

name
required
string

The name of the employee

enabled
required
boolean

Whether the employee is enabled or disabled in the system

original_id
string

If item is copied, the original id of this employee.

code
required
string

A user defined reference code for the employee

region_id
required
string

The id of the region the employee belongs to

team_id
required
string

The id of the team the employee belongs to

start_location_lat
required
number

The latitude value of the employee start location

start_location_lng
required
number

The longitude value of the employee start location

end_location_lat
required
number

The latitude value of the employee end location

end_location_lng
required
number

The longitude value of the employee end location

start_location_hub_id
string

The id of the start location hub if present

end_location_hub_id
string

The id of the end location hub if present

shift_pattern_id
string

The id of the shift pattern the employee uses

rolling_pattern_from
string

If the shift pattern is a rolling template, the date from when this applies for this employee

rolling_pattern_to
string

If the shift pattern is a rolling template, the last date for when this applies for this employee

working_rules_id
string

The id of the working rule the employee uses

vehicle_id
string

The id of the vehicle the employee uses

cost_per_hour_of_duty
integer

The cost per hour of using this employee. (Use Pennies/Cents). Optional

skill_ids
Array of strings

Array of skill ids

start_address
string

Employee start location address

start_postcode
string

Employee start location postcode

end_address
string

Employee end location address

end_postcode
string

Employee end location postcode

start_time
string

Employee earliest start time

end_time
string

Employee latest finish time

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "original_id": "string",
  • "code": "string",
  • "region_id": "string",
  • "team_id": "string",
  • "start_location_lat": 0,
  • "start_location_lng": 0,
  • "end_location_lat": 0,
  • "end_location_lng": 0,
  • "start_location_hub_id": "string",
  • "end_location_hub_id": "string",
  • "shift_pattern_id": "string",
  • "rolling_pattern_from": "string",
  • "rolling_pattern_to": "string",
  • "working_rules_id": "string",
  • "vehicle_id": "string",
  • "cost_per_hour_of_duty": 0,
  • "skill_ids": [
    ],
  • "start_address": "string",
  • "start_postcode": "string",
  • "end_address": "string",
  • "end_postcode": "string",
  • "start_time": "string",
  • "end_time": "string"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Get employee

Return an employee by ID

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Update an employee

Update an existing employee

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Request Body schema: application/json

employee to update

name
required
string

The name of the employee

enabled
required
boolean

Whether the employee is enabled or disabled in the system

original_id
string

If item is copied, the original id of this employee.

code
required
string

A user defined reference code for the employee

region_id
required
string

The id of the region the employee belongs to

team_id
required
string

The id of the team the employee belongs to

start_location_lat
required
number

The latitude value of the employee start location

start_location_lng
required
number

The longitude value of the employee start location

end_location_lat
required
number

The latitude value of the employee end location

end_location_lng
required
number

The longitude value of the employee end location

start_location_hub_id
string

The id of the start location hub if present

end_location_hub_id
string

The id of the end location hub if present

shift_pattern_id
string

The id of the shift pattern the employee uses

rolling_pattern_from
string

If the shift pattern is a rolling template, the date from when this applies for this employee

rolling_pattern_to
string

If the shift pattern is a rolling template, the last date for when this applies for this employee

working_rules_id
string

The id of the working rule the employee uses

vehicle_id
string

The id of the vehicle the employee uses

cost_per_hour_of_duty
integer

The cost per hour of using this employee. (Use Pennies/Cents). Optional

skill_ids
Array of strings

Array of skill ids

start_address
string

Employee start location address

start_postcode
string

Employee start location postcode

end_address
string

Employee end location address

end_postcode
string

Employee end location postcode

start_time
string

Employee earliest start time

end_time
string

Employee latest finish time

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "original_id": "string",
  • "code": "string",
  • "region_id": "string",
  • "team_id": "string",
  • "start_location_lat": 0,
  • "start_location_lng": 0,
  • "end_location_lat": 0,
  • "end_location_lng": 0,
  • "start_location_hub_id": "string",
  • "end_location_hub_id": "string",
  • "shift_pattern_id": "string",
  • "rolling_pattern_from": "string",
  • "rolling_pattern_to": "string",
  • "working_rules_id": "string",
  • "vehicle_id": "string",
  • "cost_per_hour_of_duty": 0,
  • "skill_ids": [
    ],
  • "start_address": "string",
  • "start_postcode": "string",
  • "end_address": "string",
  • "end_postcode": "string",
  • "start_time": "string",
  • "end_time": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Delete an employee

Delete an employee

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Optimisation Jobs

Jobs responsible for optimising the assignment of employees to tasks.

Get optimisation jobs

Return a list of optimisation jobs

Authorizations:
apiKeyHeaderaccIdHeader
query Parameters
account_id
required
string
region_id
string
date
string

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": [
    ]
}

Add new optimisation job

Create optimisation job

Authorizations:
apiKeyHeaderaccIdHeader
Request Body schema: application/json

optimisation job to add

account_id
required
string
duration_secs
required
number

how long the optimisation job should run for. The longer it runs, the better the resulting schedule

region_id
required
string

ID of an existing region

planning_horizon_start_date
required
string

The first day of the planning horizon

planning_horizon_days
required
number

Number of days this job optimises. Min is 1.

planning_horizon_unit_type
any
Default: "DAYS"
Enum: "DAYS" "WEEKS"

Whether the job should should run in day mode or week mode. Week mode will include Mon-Sun of target date.

job_type
string
Enum: "LIVE" "SIMULATED"

Whether the job should be live or simulated.

objective_hierarchy
string
Enum: "OBJECTIVE_A" "OBJECTIVE_B" "OBJECTIVE_C" "OBJECTIVE_COST" "OBJECTIVE_PROFIT" "OBJECTIVE_MISSING_TRIPS"

Objective hierarchy (OBJECTIVE_A is default): * OBJECTIVE_A - As many tasks as possible (then minimise distance) * OBJECTIVE_B - DEPRECATED: Objective B * OBJECTIVE_C - As many tasks as possible (then workload balancing * OBJECTIVE_COST - As many tasks as possible (then minimising cost) * OBJECTIVE_PROFIT - Profit Maximisation * OBJECTIVE_MISSING_TRIPS - Profit Maximisation with all employees dispatched

trip_timing_policy
string
Enum: "AS_EARLY_AS_POSSIBLE" "EARLY_WITHOUT_WAITING_AT_FIRST_CLIENT" "AS_LATE_AS_POSSIBLE"

When to send out employees (AS_LATE_AS_POSSIBLE is default)

Responses

Request samples

Content type
application/json
{
  • "account_id": "string",
  • "duration_secs": 0,
  • "region_id": "string",
  • "planning_horizon_start_date": "string",
  • "planning_horizon_days": 1,
  • "planning_horizon_unit_type": "DAYS",
  • "job_type": "LIVE",
  • "objective_hierarchy": "OBJECTIVE_A",
  • "trip_timing_policy": "AS_EARLY_AS_POSSIBLE"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Get optimisation job

Return an optimisation job by ID

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Update the status of a job

Updates the status of a job (Can be used to cancel job)

Authorizations:
apiKeyHeaderaccIdHeader
query Parameters
job_id
required
string
Example: job_id=4faf1eac-a9e2-481f-9a8d-003fde17fc5a

The UUID of the job to change the status

Request Body schema: application/json

The status

status
string
Value: "CANCELLING"

Responses

Request samples

Content type
application/json
{
  • "status": "CANCELLING"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Teams

The team or department an employee works for.

Get teams

Return a list of teams

Authorizations:
apiKeyHeaderaccIdHeader
query Parameters
sort_by
string

The field to sort the results by

order_by
any
Enum: "asc" "desc"
Example: order_by=desc

Whether to sort results in ascending or descending order

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": [
    ]
}

Add new team

Add team

Authorizations:
apiKeyHeaderaccIdHeader
Request Body schema: application/json

team to add

name
required
string
team_type
required
string
Enum: "INHOUSE" "CONTRACTOR"

Whether the team is an INHOUSE or CONTRACTOR type

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "team_type": "INHOUSE"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Get team

Return an team by ID

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Update an team

Update an existing team

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Request Body schema: application/json

team to update

name
required
string
team_type
required
string
Enum: "INHOUSE" "CONTRACTOR"

Whether the team is an INHOUSE or CONTRACTOR type

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "team_type": "INHOUSE"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Delete an team

Delete an team

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Regions

Groupings of tasks and employees.

Get regions

Return a list of regions

Authorizations:
apiKeyHeaderaccIdHeader
query Parameters
sort_by
string

The field to sort the results by

order_by
any
Enum: "asc" "desc"
Example: order_by=desc

Whether to sort results in ascending or descending order

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": [
    ]
}

Add a region

Add a region

Authorizations:
apiKeyHeaderaccIdHeader
Request Body schema: application/json

The region to create

name
required
string

The name of the region

level
required
number

The level of the region

code
required
string

A user defined reference code for the region

parent_region_id
string

The Id of the parent region

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "level": 0,
  • "code": "string",
  • "parent_region_id": "string"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Get region

Return a region by ID

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Update a region

Update an existing region

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Request Body schema: application/json

The region to update

name
required
string

The name of the region

level
required
number

The level of the region

code
required
string

A user defined reference code for the region

parent_region_id
string

The Id of the parent region

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "level": 0,
  • "code": "string",
  • "parent_region_id": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Delete a region

Delete a region

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Skills

Skills used for matching employees and tasks.

Get skills

Return a list of skills

Authorizations:
apiKeyHeader
query Parameters
sort_by
string

The field to sort the results by

order_by
any
Enum: "asc" "desc"
Example: order_by=desc

Whether to sort results in ascending or descending order

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": [
    ]
}

Add new skill(s)

Add skills

Authorizations:
apiKeyHeaderaccIdHeader
Request Body schema: application/json

Skill to add

name
required
string
description
string
code
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Get skill

Return a skill by ID

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Update a skill

Update an existing skill

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Request Body schema: application/json

Skill to update

name
required
string
description
string
code
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Delete a skill by its ID

Delete a skill

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Shift Patterns

Shift Patterns for controlling when an employee is available to work.

Get Shift Patterns

Return a list of shift patterns

Authorizations:
apiKeyHeaderaccIdHeader
query Parameters
sort_by
string

The field to sort the results by

order_by
any
Enum: "asc" "desc"
Example: order_by=desc

Whether to sort results in ascending or descending order

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": [
    ]
}

Add new Shift Pattern

Add a Shift Pattern

Authorizations:
apiKeyHeaderaccIdHeader
Request Body schema: application/json

Shift pattern to create

name
required
string

The name of the shift pattern

code
required
string

A user defined reference code for the shift pattern

description
string

A description of the shift pattern

availability_type
required
string
Enum: "SPECIFIC" "ROLLING"

Whether shift pattern uses specific dates or a rolling template

template_num_weeks
number

Number of weeks in rolling template (if applicable)

required
Array of objects

Array of Availability objects

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "code": "string",
  • "description": "string",
  • "availability_type": "SPECIFIC",
  • "template_num_weeks": 0,
  • "availability": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Get Shift Pattern

Return a shift pattern by ID

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Update a Shift Pattern

Update an existing Shift Pattern

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Request Body schema: application/json

Shift pattern to update

name
required
string

The name of the shift pattern

code
required
string

A user defined reference code for the shift pattern

description
string

A description of the shift pattern

availability_type
required
string
Enum: "SPECIFIC" "ROLLING"

Whether shift pattern uses specific dates or a rolling template

template_num_weeks
number

Number of weeks in rolling template (if applicable)

required
Array of objects

Array of Availability objects

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "code": "string",
  • "description": "string",
  • "availability_type": "SPECIFIC",
  • "template_num_weeks": 0,
  • "availability": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Delete a Shift Pattern

Delete a shift pattern

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Add new Availability

Add a new employee availability

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Request Body schema: application/json

Availability to create

id
string

The unique id for the availability (GUID)

template_week
number

Week in rolling template if AvailabilityType != SPECIFIC

day_of_week
number

Day of week 1-7 (mon - sun) in rolling template if AvailabilityType != SPECIFIC

date
string

Date for AvailabilityType == SPECIFIC

enabled
required
boolean

Whether this availability is enabled

required
Array of objects (TimeWindow)

The time windows for the pattern or date

cost_per_hour_of_duty
integer

The cost per hour of using this employee. (Use Pennies/Cents). Optional

vehicle_id
string

The id of the vehicle the employee uses

working_rules_id
string

The id of the working rule the employee uses

start_address
string

Employee start location address

start_postcode
string

Employee start location postcode

end_address
string

Employee end location address

end_postcode
string

Employee end location postcode

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "template_week": 0,
  • "day_of_week": 0,
  • "date": "string",
  • "enabled": true,
  • "time_windows": [
    ],
  • "cost_per_hour_of_duty": 0,
  • "vehicle_id": "string",
  • "working_rules_id": "string",
  • "start_address": "string",
  • "start_postcode": "string",
  • "end_address": "string",
  • "end_postcode": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "template_week": 0,
  • "day_of_week": 0,
  • "date": "string",
  • "enabled": true,
  • "time_windows": [
    ],
  • "cost_per_hour_of_duty": 0,
  • "vehicle_id": "string",
  • "working_rules_id": "string",
  • "start_address": "string",
  • "start_postcode": "string",
  • "end_address": "string",
  • "end_postcode": "string"
}

Update a Availability

Update an existing Availability of specific Shift Pattern

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

ID
required
string

ID of the item being accessed

Request Body schema: application/json

Availability to update

id
string

The unique id for the availability (GUID)

template_week
number

Week in rolling template if AvailabilityType != SPECIFIC

day_of_week
number

Day of week 1-7 (mon - sun) in rolling template if AvailabilityType != SPECIFIC

date
string

Date for AvailabilityType == SPECIFIC

enabled
required
boolean

Whether this availability is enabled

required
Array of objects (TimeWindow)

The time windows for the pattern or date

cost_per_hour_of_duty
integer

The cost per hour of using this employee. (Use Pennies/Cents). Optional

vehicle_id
string

The id of the vehicle the employee uses

working_rules_id
string

The id of the working rule the employee uses

start_address
string

Employee start location address

start_postcode
string

Employee start location postcode

end_address
string

Employee end location address

end_postcode
string

Employee end location postcode

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "template_week": 0,
  • "day_of_week": 0,
  • "date": "string",
  • "enabled": true,
  • "time_windows": [
    ],
  • "cost_per_hour_of_duty": 0,
  • "vehicle_id": "string",
  • "working_rules_id": "string",
  • "start_address": "string",
  • "start_postcode": "string",
  • "end_address": "string",
  • "end_postcode": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Working Rules

Working rules for controlling rules around employees working.

Get Working Rules

Return a list of Working Rules

Authorizations:
apiKeyHeaderaccIdHeader
query Parameters
sort_by
string

The field to sort the results by

order_by
any
Enum: "asc" "desc"
Example: order_by=desc

Whether to sort results in ascending or descending order

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": [
    ]
}

Add new Working Rule

Add a Working Rule

Authorizations:
apiKeyHeaderaccIdHeader
Request Body schema: application/json

Shift pattern to create

name
required
string

The name of the working rule

code
required
string

A user defined reference code for the working rule

description
string

A description of the working rule

break_length_secs
required
number

The length of breaks in seconds

min_duty_time_secs
required
number

The minimum time that must completed in a shift before a break could be scheduled in seconds

max_duty_time_secs
required
number

The maximum time that is allowed in a shift without a break

max_drive_time_secs
required
number

The maximum time that is allowed travelling in one go without a break

max_drive_distance_meters
number

The maximum distance that the employee can travel across their shift in total

max_tasks
number

The maximum amount of tasks an employee can be assigned in one shift

shift_as_service_window
required
boolean

If true, travel to the first task and after the last task will fall outside the shift availability windows

max_weekly_duty_time_secs
number

The maximum amount of time an employee can work across a week (mon - sun)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "code": "string",
  • "description": "string",
  • "break_length_secs": 0,
  • "min_duty_time_secs": 0,
  • "max_duty_time_secs": 0,
  • "max_drive_time_secs": 0,
  • "max_drive_distance_meters": 0,
  • "max_tasks": 0,
  • "shift_as_service_window": true,
  • "max_weekly_duty_time_secs": 0
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Get Working Rule

Return a Working Rule by ID

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Update a Working Rule

Update an existing Shift Pattern

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Request Body schema: application/json

Working Rule to update

name
required
string

The name of the working rule

code
required
string

A user defined reference code for the working rule

description
string

A description of the working rule

break_length_secs
required
number

The length of breaks in seconds

min_duty_time_secs
required
number

The minimum time that must completed in a shift before a break could be scheduled in seconds

max_duty_time_secs
required
number

The maximum time that is allowed in a shift without a break

max_drive_time_secs
required
number

The maximum time that is allowed travelling in one go without a break

max_drive_distance_meters
number

The maximum distance that the employee can travel across their shift in total

max_tasks
number

The maximum amount of tasks an employee can be assigned in one shift

shift_as_service_window
required
boolean

If true, travel to the first task and after the last task will fall outside the shift availability windows

max_weekly_duty_time_secs
number

The maximum amount of time an employee can work across a week (mon - sun)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "code": "string",
  • "description": "string",
  • "break_length_secs": 0,
  • "min_duty_time_secs": 0,
  • "max_duty_time_secs": 0,
  • "max_drive_time_secs": 0,
  • "max_drive_distance_meters": 0,
  • "max_tasks": 0,
  • "shift_as_service_window": true,
  • "max_weekly_duty_time_secs": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Delete a Working Rule

Delete a Working Rule

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Tasks

Tasks which employees are assigned to complete.

Get Tasks

Return a list of tasks

Authorizations:
apiKeyHeaderaccIdHeader
query Parameters
sort_by
string

The field to sort the results by

order_by
string

Whether to sort results in ascending or descending order

region_id
string

Limit results by region

dates
string

Limit tasks to those with time windows falling within provided dates

enabled
boolean

Limit tasks to those which are enabled/or not

schedule_ids
string

Limit tasks to those which are scheduled in provided schedule

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": [
    ]
}

Add new Task

Add Task

Authorizations:
apiKeyHeaderaccIdHeader
Request Body schema: application/json

Task to add

enabled
required
boolean

Whether is enabled and available to be scheduled

address
string

An address for the task

postcode
string

A postcode for the task

code
string

A code or customer reference for this task

description
string

A description of the task

duration_secs
required
number

How long the task will take in seconds

latitude
required
number

The latitude of the task

longitude
required
number

The longitude of the task

num_emps_req
required
integer [ 1 .. 5 ]
Default: 1

The number of employees needed to carry out the task

priority
required
boolean

Whether the task is high priority

num_visits
number

The number of times the task needs to be carried out in the scheduling horizon

skill_ids
Array of strings

Array of skill ids

preferred_team_ids
Array of strings

A list of the preferred team(s) IDs to carry out task (optional).

region_id
required
string

The id of the region the task belongs to

task_type_id
string

The id of the task type the task is classified as (optional)

preferred_employee_ids
Array of strings

A list of the preferred employee(s) IDs to carry out the task (optional). Note if allowed_employee_ids provided then this id must be included within that list.

allowed_employee_ids
Array of strings

A list of employees that are allowed to carry out this task. If left empty then assumes any employee allowed.

required
Array of objects

An array of time window options for when the employee can arrive to carry out the task

service_gap
number

The gap required between each service in a the horizon if multi visit

max_emp_over_horizon
number

The maximum number of different employees allowed to service multi visits in a horizon

weight
number

The weight of the task (optional)

volume
number

The volume of the task (optional)

revenue_per_visit
integer

The revenue for a task (Use Pennies/Cents). Optional but must be > 0 if provided.

sla_deadline
string

The date of the SLA deadline (hard constraint, Optional) (YYYY-MM-DD)

sla_last_free_day
string

The date of the last free day (soft constraint, Optional but use with sla_penalty_per_day) (YYYY-MM-DD)

sla_penalty_per_day
integer

The cost for missing the last free day per day (Use Pennies/Cents). Optional but use with sla_last_free_day.

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "address": "string",
  • "postcode": "string",
  • "code": "string",
  • "description": "string",
  • "duration_secs": 0,
  • "latitude": 0,
  • "longitude": 0,
  • "num_emps_req": 1,
  • "priority": true,
  • "num_visits": 0,
  • "skill_ids": [
    ],
  • "preferred_team_ids": [
    ],
  • "region_id": "string",
  • "task_type_id": "string",
  • "preferred_employee_ids": [
    ],
  • "allowed_employee_ids": [
    ],
  • "time_windows": [
    ],
  • "service_gap": 0,
  • "max_emp_over_horizon": 0,
  • "weight": 0,
  • "volume": 0,
  • "revenue_per_visit": 0,
  • "sla_deadline": "string",
  • "sla_last_free_day": "string",
  • "sla_penalty_per_day": 0
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Get Task

Return a task by ID

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Update a Task

Update an existing Task

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Request Body schema: application/json

Task to update

enabled
required
boolean

Whether is enabled and available to be scheduled

address
string

An address for the task

postcode
string

A postcode for the task

code
string

A code or customer reference for this task

description
string

A description of the task

duration_secs
required
number

How long the task will take in seconds

latitude
required
number

The latitude of the task

longitude
required
number

The longitude of the task

num_emps_req
required
integer [ 1 .. 5 ]
Default: 1

The number of employees needed to carry out the task

priority
required
boolean

Whether the task is high priority

num_visits
number

The number of times the task needs to be carried out in the scheduling horizon

skill_ids
Array of strings

Array of skill ids

preferred_team_ids
Array of strings

A list of the preferred team(s) IDs to carry out task (optional).

region_id
required
string

The id of the region the task belongs to

task_type_id
string

The id of the task type the task is classified as (optional)

preferred_employee_ids
Array of strings

A list of the preferred employee(s) IDs to carry out the task (optional). Note if allowed_employee_ids provided then this id must be included within that list.

allowed_employee_ids
Array of strings

A list of employees that are allowed to carry out this task. If left empty then assumes any employee allowed.

required
Array of objects

An array of time window options for when the employee can arrive to carry out the task

service_gap
number

The gap required between each service in a the horizon if multi visit

max_emp_over_horizon
number

The maximum number of different employees allowed to service multi visits in a horizon

weight
number

The weight of the task (optional)

volume
number

The volume of the task (optional)

revenue_per_visit
integer

The revenue for a task (Use Pennies/Cents). Optional but must be > 0 if provided.

sla_deadline
string

The date of the SLA deadline (hard constraint, Optional) (YYYY-MM-DD)

sla_last_free_day
string

The date of the last free day (soft constraint, Optional but use with sla_penalty_per_day) (YYYY-MM-DD)

sla_penalty_per_day
integer

The cost for missing the last free day per day (Use Pennies/Cents). Optional but use with sla_last_free_day.

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "address": "string",
  • "postcode": "string",
  • "code": "string",
  • "description": "string",
  • "duration_secs": 0,
  • "latitude": 0,
  • "longitude": 0,
  • "num_emps_req": 1,
  • "priority": true,
  • "num_visits": 0,
  • "skill_ids": [
    ],
  • "preferred_team_ids": [
    ],
  • "region_id": "string",
  • "task_type_id": "string",
  • "preferred_employee_ids": [
    ],
  • "allowed_employee_ids": [
    ],
  • "time_windows": [
    ],
  • "service_gap": 0,
  • "max_emp_over_horizon": 0,
  • "weight": 0,
  • "volume": 0,
  • "revenue_per_visit": 0,
  • "sla_deadline": "string",
  • "sla_last_free_day": "string",
  • "sla_penalty_per_day": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Delete a Task

Delete a task

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Task Types

A classification of tasks.

Get Task Types

Return a list of task types

Authorizations:
apiKeyHeaderaccIdHeader
query Parameters
sort_by
string

The field to sort the results by

order_by
any
Enum: "asc" "desc"
Example: order_by=desc

Whether to sort results in ascending or descending order

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": [
    ]
}

Add new Task Type

Add Task Type

Authorizations:
apiKeyHeaderaccIdHeader
Request Body schema: application/json

The information needed to add the task type

name
required
string

The name of the task type

code
required
string

A user defined reference code for the task type

duration_secs
required
string

The default length of time for the task in seconds

num_employees
required
number

The default number of employees required to carry out the task

description
string

A description of the task type

skill_ids
Array of strings

Array of skill ids (UUIDs)

preferred_team_ids
Array of strings

A list of the preferred team(s) IDs to carry out task (optional).

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "code": "string",
  • "duration_secs": "string",
  • "num_employees": 0,
  • "description": "string",
  • "skill_ids": [
    ],
  • "preferred_team_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Get Task Type

Return a task type by ID

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

The task type ID

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Update a Task Type

Update an existing Task Type

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

The task type ID

Request Body schema: application/json

Task type to update

name
required
string

The name of the task type

code
required
string

A user defined reference code for the task type

duration_secs
required
string

The default length of time for the task in seconds

num_employees
required
number

The default number of employees required to carry out the task

description
string

A description of the task type

skill_ids
Array of strings

Array of skill ids (UUIDs)

preferred_team_ids
Array of strings

A list of the preferred team(s) IDs to carry out task (optional).

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "code": "string",
  • "duration_secs": "string",
  • "num_employees": 0,
  • "description": "string",
  • "skill_ids": [
    ],
  • "preferred_team_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Delete a Task Type

Delete a task type

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Schedules

An Employee's schedule for the day.

Get list of schedules

Return a list of schedules

Authorizations:
apiKeyHeaderaccIdHeader
query Parameters
sort_by
string

The field to sort the results by

order_by
string

Whether to sort results in ascending or descending order

region_id
string

Limit results by region

employee_id
string

Limit results by employee

optimiser_job_id
string

Limit results by job id

schedule_type
string
Enum: "LIVE" "SIMULATED"

Limit results by schedule type

dates
string
Example: dates=2022-03-31;2022-04-01

A list of dates (comma delimited) to limit results by

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": [
    ]
}

Get schedule

Return a schedule by ID

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Vehicles

A vehicle used by an employee

Get Vehicles

Return a list of Vehicles

Authorizations:
apiKeyHeaderaccIdHeader
query Parameters
sort_by
string

The field to sort the results by

order_by
any
Enum: "asc" "desc"
Example: order_by=desc

Whether to sort results in ascending or descending order

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": [
    ]
}

Add new Vehicle

Add a Vehicle

Authorizations:
apiKeyHeaderaccIdHeader
Request Body schema: application/json

Vehicle to create

name
required
string
max_weight
required
number
max_volume
required
number
cost_per_trip
integer

The fixed cost for utilising a vehicle in a shift.

cost_per_kilometer
integer

Cost per kilometer for using the vehicle.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "max_weight": 0,
  • "max_volume": 0,
  • "cost_per_trip": 0,
  • "cost_per_kilometer": 0
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Get Vehicle

Return a Vehicle by ID

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "data": {
    }
}

Update a Vehicle

Update an existing Vehicle

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Request Body schema: application/json

Vehicle to update

name
required
string
max_weight
required
number
max_volume
required
number
cost_per_trip
integer

The fixed cost for utilising a vehicle in a shift.

cost_per_kilometer
integer

Cost per kilometer for using the vehicle.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "max_weight": 0,
  • "max_volume": 0,
  • "cost_per_trip": 0,
  • "cost_per_kilometer": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Delete a Vehicle

Delete a Vehicle

Authorizations:
apiKeyHeaderaccIdHeader
path Parameters
ID
required
string

ID of the item being accessed

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Slots

Gets available slots for provided task

Authorizations:
apiKeyHeaderaccIdHeader
Request Body schema: application/json

The data to get slot availability

date
required
string

The date to retrieve slots for. Must be inside planning horizon.

required
object (WriteTask)
required
Array of objects

Set of slots to check for.

Responses

Request samples

Content type
application/json
{
  • "date": "string",
  • "task": {
    },
  • "slotOptions": [
    ]
}