Skip to main content

Create Job

POST /locations/{location_id}/jobs

Create a new job.

Roles​

Users with the following roles may access this endoint:

Dispatcher
ThirdPartyDispatcher

Breaking Changes​

2021/11/04

Request​




Path Parameters​

location_id Integer, Required

Location identifier.

Query Parameters​

note

No query parameters.

Request Headers​

Refer to StandardRequestHeadersModel for more details.

authorization String, Required

Authorization header (bearer with access token). See the Authentication Guide to get started.

  • Matches ^bearer [a-z0-9-_=]+.[a-z0-9-_=]+.?[a-z0-9-_.+/=]*$
  • No longer than 256 characters.
  • At least 1 characters long.

Content-Type String, Optional

Default Value: application/json

One of the following MIME types:

x-api-version String, Optional

Request identifier.

  • At least 1 and no more than 64 characters.
  • Must be a valid API version string (2019/02/08, 2021/04/07, 2021/05/07, 2021/08/02, 2021/11/04, 2023/04/19).

x-tenant-id Integer, Required

Tenant identifier. Contact CRO Software for more info if you don't already have this id. See list tenant ids for info on listing the tenants you have access to.

Request Body​

Refer to CreateJobRequestBodyModel for more details.

add_to_routes String, Optional

CSV of route IDs which the dropped asset should be assigned to.

  • At least 0 and no more than 2048 characters.
  • List of 1 or more comma-separated integer identifiers. Whitespace allowed (newline, space, tab).

add_to_routes_settings Array[AddToRoutesSettingsModel], Optional

Refer to AddToRoutesSettingsModel.

address_id Integer, Required

Customer address identifier.

arrived_at_destination_on String, Optional

Job starting time.

  • Date in an ISO 8601 compatible format.

arrived_on String, Optional

Drive start time entered by driver for dispatcher and customer (arrived at job slider).

  • Date in an ISO 8601 compatible format.

asset_dropped_id Integer, Optional

DeployedBinID of the asset that was dropped by this job, only allowed to be set if the job's type is 'D' or 'E'.

asset_id Integer, Optional

Job asset identifier. Applicable to job types 'E', 'P', 'R'.

asset_quantity Integer, Optional

How many assets are being serviced within a cluster (for jobs assigned to an asset cluster). For jobs dispatched by routes, or manually dispatched route stops, this value is 0 or 1.

  • Greater than or equal to 0.

asset_type_id Integer, Optional

Selected asset for the job (job types 'D', 'L', 'E').

completed_by Integer, Optional

Dispatcher or driver id.

completed_on String, Optional

Job completion time.

  • Date occurring in the past in an ISO 8601 compatible format.

confirmed_on String, Optional

Job confirmation date.

  • Date occurring in the past in an ISO 8601 compatible format.

created_by_driver Boolean, Optional

Created by driver.

  • One of 0, 1, True, False (case insensitive).

created_with_portal Boolean, Optional

Set record active state.

  • One of 0, 1, True, False (case insensitive).

customer_id Integer, Optional

Customer identifier.

customer_notes String, Optional

Notes entered by customers to communicate with dispatchers.

  • At least 0 and no more than 2048 characters.

departed_on String, Optional

  • Date occurring in the past in an ISO 8601 compatible format.

desired_asset_desc String, Optional

Free-form text entered by dispatchers and drivers to be used as the future asset description.

  • At least 1 and no more than 2048 characters.

desired_end_time String, Optional

Future estimated time of job completion.

  • Date in an ISO 8601 compatible format.

desired_start_time String, Optional

Time customer has requested job start, set by dispatchers for dispatchers and drivers.

  • Date in an ISO 8601 compatible format.

dispatch_priority String, Optional

Entered by dispatchers to determine dispatch order.

  • One of: 'H', 'L', 'M' ('H'='High', 'L'='Low', 'M'='Medium').

dispatched_by_route Integer, Optional

Route id of dispatching route (or NULL if not dispatched by a route).

dispatched_on String, Optional

Time the job is assigned to a truck.

  • Date in an ISO 8601 compatible format.

dispatcher_notes String, Optional

Entered by dispatchers, read by drivers and dispatchers.

  • At least 0 and no more than 2048 characters.

do_confirm Boolean, Optional

Tell dispatcher that a customer should be contacted before job is dispatched.

  • One of 0, 1, True, False (case insensitive).

driver_notes String, Optional

Entered by drivers when completing or failing a job for dispatchers.

  • At least 0 and no more than 2048 characters.

dropped_number String, Optional

dump_location_id Integer, Optional

Asset or asset cluster dump location identifier (e.g. trash bin needs dumped before returning from customer).

dumped_on String, Optional

Dump request completion date.

  • Date in an ISO 8601 compatible format.

ends_at_customer Boolean, Optional

The job ends at the customer location when TRUE.

  • One of 0, 1, True, False (case insensitive).

fail_reason String, Optional

Failure description selected by a driver for use by dispatchers.

  • At least 0 and no more than 64 characters.

final_location_id Integer, Optional

Final location identifier. Used by dispatchers for prioritizing jobs. Used by drivers to know where to leave the asset on job completion.

flags String, Optional

Job notes.

  • At least 0 and no more than 64 characters.

invoice_notes String, Optional

Invoice notes from the billing system.

  • At least 0 and no more than 2048 characters.

is_acknowledged Boolean, Optional

True if the job has been acknowledged.

  • One of 0, 1, True, False (case insensitive).

is_completed Boolean, Optional

Job completion flag set by dispatchers and drivers.

  • One of 0, 1, True, False (case insensitive).

is_declined Boolean, Optional

Job completion flag set by dispatchers and drivers.

  • One of 0, 1, True, False (case insensitive).

is_deleted Boolean, Optional

Indicates whether job is still valid.

  • One of 0, 1, True, False (case insensitive).

is_failed Boolean, Optional

Set by drivers and dispatchers to indicate a failed job.

  • One of 0, 1, True, False (case insensitive).

is_paid Boolean, Optional

is_separate_from_route_list Boolean, Optional

This job should be separate from any per-route job list when TRUE.

  • One of 0, 1, True, False (case insensitive).

job_group_id Integer, Optional

Job group identifier for group jobs (vs service, exchange, etc.).

last_updated_on String, Optional

  • Date occurring in the past in an ISO 8601 compatible format.

merged_with_route_id Integer, Optional

IDs of the route which this job should be merged into.

original_schedule_date String, Optional

Original scheduling date.

  • Date in an ISO 8601 compatible format.

pickup_date String, Optional

A pickup job is scheduled for this date upon job completion. If the asset or cluster is assigned to a route stop, the route stop will be deleted. Must be in the future.

  • Date in an ISO 8601 compatible format.

pickup_item Integer, Optional

priority Integer, Optional

Assigned by dispatchers for job order completion determination for drivers.

  • Less than or equal to -1.
  • Greater than or equal to -999999.

recur_active Boolean, Optional

Set timeline recur active.

  • One of 0, 1, True, False (case insensitive).

recur_enabled Boolean, Optional

Set timeline recur enabled.

  • One of 0, 1, True, False (case insensitive).

reference_number String, Optional

Reference number (free text).

  • At least 1 and no more than 256 characters.

removed_number String, Optional

requested_by Integer, Required

Customer identifier.

requested_on String, Optional

Requested date.

  • Date occurring in the past in an ISO 8601 compatible format.

require_image Boolean, Optional

Set by dispatchers and drivers, requires drivers to upload one or more job images before completion.

  • One of 0, 1, True, False (case insensitive).

require_material Boolean, Optional

Set by dispatchers and drivers, requires drivers to set a material before completing a job.

  • One of 0, 1, True, False (case insensitive).

require_materials Boolean, Optional

The driver is required to report the weights of any additional materials related to the job when TRUE.

  • One of 0, 1, True, False (case insensitive).

require_signature Boolean, Optional

Set by dispatchers and drivers, requires drivers to get a customer signature before job completion.

  • One of 0, 1, True, False (case insensitive).

require_weights Boolean, Optional

Set by disptachers and drivers, requires drivers to set material weights before job completion.

  • One of 0, 1, True, False (case insensitive).

scale_ticket String, Optional

Scale ticket.

  • At least 0 and no more than 64 characters.

schedule_date String, Optional

Scheduled job completion date.

  • Date in an ISO 8601 compatible format.

start_location_id Integer, Optional

Pickup location for asset or asset cluster Set by dispatchers and drivers for drivers.

started_on String, Optional

Job starting time.

  • Date in an ISO 8601 compatible format.

starts_at_customer Boolean, Optional

The job begins at the customer location when TRUE.

  • One of 0, 1, True, False (case insensitive).

third_party_hauler_id String, Optional

Third party hauler identifier.

  • Valid UUID.

times_failed Integer, Optional

Number of times a job has been attempted and failed.

  • Greater than or equal to 0.

times_rolled_over Integer, Optional

Tracks job age in days for dispatchers.

  • Greater than or equal to 0.

truck_id Integer, Optional

Truck identifier.

type String, Required

Set by dispatchers and customers. Represents physical actions to execute on job start.

  • One of: 'D', 'E', 'L', 'P', 'R'.

weighed_on String, Optional

Time of truck weight entry.

  • Date occurring in the past in an ISO 8601 compatible format.

Response​

Response Headers​

Refer to StandardResponseHeadersModel for more details.

Content-Type String, Optional

Default Value: application/json

One of the following MIME types:

x-api-version String

Request identifier.

  • At least 1 and no more than 64 characters.
  • Must be a valid API version string (2019/02/08, 2021/04/07, 2021/05/07, 2021/08/02, 2021/11/04, 2023/04/19).

x-request-id String

Request identifier.

  • Valid UUID.

Response Body​

Refer to JobModel for more details.

add_to_routes String

CSV of route IDs which the dropped asset should be assigned to.

  • At least 0 and no more than 2048 characters.
  • List of 1 or more comma-separated integer identifiers. Whitespace allowed (newline, space, tab).

add_to_routes_settings Array[AddToRoutesSettingsModel]

Refer to AddToRoutesSettingsModel.

arrived_at_destination_on String

Job starting time.

  • Date in an ISO 8601 compatible format.

arrived_on String

Drive start time entered by driver for dispatcher and customer (arrived at job slider).

  • Date in an ISO 8601 compatible format.

asset Object

JobAssetModel

asset_dropped_id Integer

DeployedBinID of the asset that was dropped by this job, only allowed to be set if the job's type is 'D' or 'E'.

asset_id Integer

Job asset identifier. Applicable to job types 'E', 'P', 'R'.

asset_quantity Integer

How many assets are being serviced within a cluster (for jobs assigned to an asset cluster). For jobs dispatched by routes, or manually dispatched route stops, this value is 0 or 1.

  • Greater than or equal to 0.

asset_type Object

JobAssetTypeModel

asset_type_id Integer

Selected asset for the job (job types 'D', 'L', 'E').

completed_by Integer

Dispatcher or driver id.

completed_on String

Job completion time.

  • Date occurring in the past in an ISO 8601 compatible format.

confirmed_on String

Job confirmation date.

  • Date occurring in the past in an ISO 8601 compatible format.

created_by Integer

Customer, dispatcher, or driver id.

created_by_driver Boolean

Created by driver.

  • One of 0, 1, True, False (case insensitive).

created_with_portal Boolean

Set record active state.

  • One of 0, 1, True, False (case insensitive).

customer Object

DispatchCustomerLocationModel

customer_id Integer

Customer identifier.

customer_notes String

Notes entered by customers to communicate with dispatchers.

  • At least 0 and no more than 2048 characters.

departed_on String

  • Date occurring in the past in an ISO 8601 compatible format.

desired_asset_desc String

Free-form text entered by dispatchers and drivers to be used as the future asset description.

  • At least 1 and no more than 2048 characters.

desired_end_time String

Future estimated time of job completion.

  • Date in an ISO 8601 compatible format.

desired_start_time String

Time customer has requested job start, set by dispatchers for dispatchers and drivers.

  • Date in an ISO 8601 compatible format.

dispatch_priority String

Entered by dispatchers to determine dispatch order.

  • One of: 'H', 'L', 'M' ('H'='High', 'L'='Low', 'M'='Medium').

dispatched_by_route Integer

Route id of dispatching route (or NULL if not dispatched by a route).

dispatched_on String

Time the job is assigned to a truck.

  • Date in an ISO 8601 compatible format.

dispatcher_notes String

Entered by dispatchers, read by drivers and dispatchers.

  • At least 0 and no more than 2048 characters.

do_confirm Boolean

Tell dispatcher that a customer should be contacted before job is dispatched.

  • One of 0, 1, True, False (case insensitive).

driver_notes String

Entered by drivers when completing or failing a job for dispatchers.

  • At least 0 and no more than 2048 characters.

dropped_asset Object

JobAssetModel

dropped_number String

dump_location Object

DumpDestinationModel

dump_location_id Integer

Asset or asset cluster dump location identifier (e.g. trash bin needs dumped before returning from customer).

dumped_on String

Dump request completion date.

  • Date in an ISO 8601 compatible format.

ends_at_customer Boolean

The job ends at the customer location when TRUE.

  • One of 0, 1, True, False (case insensitive).

fail_reason String

Failure description selected by a driver for use by dispatchers.

  • At least 0 and no more than 64 characters.

final_location Object

DumpDestinationModel

final_location_id Integer

Final location identifier. Used by dispatchers for prioritizing jobs. Used by drivers to know where to leave the asset on job completion.

flags String

Job notes.

  • At least 0 and no more than 64 characters.

id Integer

Job identifier.

images Array[JobImageModel]

Refer to JobImageModel.

invoice_notes String

Invoice notes from the billing system.

  • At least 0 and no more than 2048 characters.

is_acknowledged Boolean

True if the job has been acknowledged.

  • One of 0, 1, True, False (case insensitive).

is_completed Boolean

Job completion flag set by dispatchers and drivers.

  • One of 0, 1, True, False (case insensitive).

is_declined Boolean

Job completion flag set by dispatchers and drivers.

  • One of 0, 1, True, False (case insensitive).

is_deleted Boolean

Indicates whether job is still valid.

  • One of 0, 1, True, False (case insensitive).

is_failed Boolean

Set by drivers and dispatchers to indicate a failed job.

  • One of 0, 1, True, False (case insensitive).

is_paid Boolean

is_separate_from_route_list Boolean

This job should be separate from any per-route job list when TRUE.

  • One of 0, 1, True, False (case insensitive).

job_group_id Integer

Job group identifier for group jobs (vs service, exchange, etc.).

last_updated_on String

  • Date occurring in the past in an ISO 8601 compatible format.

location_id Integer

Location identifier.

materials Array[JobMaterialModel]

Refer to JobMaterialModel.

merged_with_route_id Integer

IDs of the route which this job should be merged into.

original_schedule_date String

Original scheduling date.

  • Date in an ISO 8601 compatible format.

pickup_date String

A pickup job is scheduled for this date upon job completion. If the asset or cluster is assigned to a route stop, the route stop will be deleted. Must be in the future.

  • Date in an ISO 8601 compatible format.

pickup_item Integer

priority Integer

Assigned by dispatchers for job order completion determination for drivers.

  • Less than or equal to -1.
  • Greater than or equal to -999999.

recur_active Boolean

Set timeline recur active.

  • One of 0, 1, True, False (case insensitive).

recur_enabled Boolean

Set timeline recur enabled.

  • One of 0, 1, True, False (case insensitive).

reference_number String

Reference number (free text).

  • At least 1 and no more than 256 characters.

removed_number String

requested_by Integer

Customer identifier.

requested_on String

Requested date.

  • Date occurring in the past in an ISO 8601 compatible format.

require_image Boolean

Set by dispatchers and drivers, requires drivers to upload one or more job images before completion.

  • One of 0, 1, True, False (case insensitive).

require_material Boolean

Set by dispatchers and drivers, requires drivers to set a material before completing a job.

  • One of 0, 1, True, False (case insensitive).

require_materials Boolean

The driver is required to report the weights of any additional materials related to the job when TRUE.

  • One of 0, 1, True, False (case insensitive).

require_signature Boolean

Set by dispatchers and drivers, requires drivers to get a customer signature before job completion.

  • One of 0, 1, True, False (case insensitive).

require_weights Boolean

Set by disptachers and drivers, requires drivers to set material weights before job completion.

  • One of 0, 1, True, False (case insensitive).

return_full Array[JobReturnFullModel]

Refer to JobReturnFullModel.

scale_ticket String

Scale ticket.

  • At least 0 and no more than 64 characters.

schedule_date String

Scheduled job completion date.

  • Date in an ISO 8601 compatible format.

start_location Object

DumpDestinationModel

start_location_id Integer

Pickup location for asset or asset cluster Set by dispatchers and drivers for drivers.

started_on String

Job starting time.

  • Date in an ISO 8601 compatible format.

starts_at_customer Boolean

The job begins at the customer location when TRUE.

  • One of 0, 1, True, False (case insensitive).

third_party_hauler_id String

Third party hauler identifier.

  • Valid UUID.

times_failed Integer

Number of times a job has been attempted and failed.

  • Greater than or equal to 0.

times_rolled_over Integer

Tracks job age in days for dispatchers.

  • Greater than or equal to 0.

truck_id Integer

Truck identifier.

type String

Set by dispatchers and customers. Represents physical actions to execute on job start.

  • One of: 'D', 'E', 'L', 'P', 'R'.

weighed_on String

Time of truck weight entry.

  • Date occurring in the past in an ISO 8601 compatible format.

Code Samples​

Missing sample data.