Click or drag to resize
POST /jobs
Print this page
Description

This service is used to create a new job or to update one or more existing jobs.

Request

For any Job object:

  • If the Id is not specified, the service creates a new job that matches the description.
  • If an Id is supplied, the service interprets the request as an update request. If no job currently exists with the specified Id, an error is returned.
  • For posted jobs, only the latitude and longitude are used from the Address object. The other fields of the Address object are ignored and replaced by values obtained by reverse geocoding.
  • If the authenticated driver creating or updating the job is assigned to a unit but the job's route does not have a unit assigned, then the driver's unit is automatically assigned to the job's route. The expected behavior is more fully described in the table below.

    A unit is assigned to the job’s route (routeId)

    A unit is not assigned to the job’s route

    The authenticated driver is assigned to a unit (unitId)

    The route’s unit assignment does not change.

    The driver’s unit is automatically assigned to the job’s route.

    The authenticated driver is not assigned to a unit

    The route’s unit assignment does not change.

    The route’s unit assignment remains unassigned.

The Request body is a JSON array of job objects describing the jobs to create or update.

Member Type Purpose
id string (read-only) Uniquely identifies the job. This is an alphanumeric identifier.
status string Indicates the current status of the job. Values: Rejected (driver rejected the job), Todo (job is on route but not yet reached), EnRoute (previous job done but not yet reached next), OnSite (driver is at job), Completed.

This field can be updated through the API. If not specified, this field defaults to Todo.
address Address The address and location of the Job site, where the driver must go in order to perform a job:
Member Type Purpose
street string The street number and name of the address.
city string The city in which the address is located.
region string The region in which the address is located (e.g., state or province).
postalCode string The postal code or zip code of the address.
lat double (required for POST) The latitude of the address in decimal degrees.
lon double (required for POST) The longitude of the address in decimal degrees.
bearingFromStreet double? The side of the road on which the address is located, indicated as an angle in decimal degrees (0 is north, 90 is east).
suburb string The suburb in which the address is located.
This field can be updated through the API. When you create or update a job, provide the markerId, which will auto-populate the address (do not include both). If you cannot provide the markerId, you must provide the address, for which TDE will create a new marker that is associated with the job.
expectedArrival string The ISO 8601 timestamp for the expected arrival at the Job. If no timezone info is supplied, this value is assumed to be UTC (Zulu). This is an absolute time, not a time interval. This field can be updated through the API. It may also be modified by the server during optimization. This field is required when creating a new job.
minutesOnSite int (optional) The estimated number of minutes that will be spent on-site to complete this job. This field can be updated through the API.
forms string[] (read-only) An array of IDs for completed forms, containing from 0..n form IDs. See Form.Job as well.
notes string (optional) An arbitrary string of notes to attach to the Job. This field can be updated through the API.
jobType string (optional) The id for the job type that this job is based on. See GET /job_types. If the job type not supplied when a new job is created, the job is given a type of "Stop".
jobName string (optional) A human-readable job name. This is the name as entered by the user in Response, or as it displays in Response if it was submitted via the API.
lastUpdateTime string (read-only) The ISO 8601 timestamp for when the Job was last updated. This field is used to filter jobs when you use the updated_since query string parameter.
statusLastUpdateTime string (read-only) The ISO 8601 timestamp for when the Job Status was last updated. This field is used to filter jobs when you use the updated_since query string parameter.
actualArrival string The ISO 8601 timestamp for the actual arrival at the Job. If no timezone info is supplied, this value is assumed to be UTC (Zulu). This field can be updated through the API, but only when setting status to OnSite or Completed.
actualDeparture string The ISO 8601 timestamp for the actual departure from the Job. If no timezone info is supplied, this value is assumed to be UTC (Zulu). This field can be updated through the API, but only when setting status to Completed.
markerId string Uniquely identifies the marker for the job's location. When you create or update a job, provide the markerId, which will auto-populate the address (do not include both). If you cannot provide the markerId, you must provide the address, for which TDE will create a new marker that is associated with the job.
code string Free-form text that can be used to categorize the job.
routeId string (optional) Uniquely identifies the route for the job, if it exists.
routeName string (read-only) The human-readable name of the route.
custom JSON object (read-only) Contains one or more key-value pairs for any custom fields and values defined for the job. The items returned for this object can vary between jobs.

Response

On success, the response body contains a JSON array of job objects. There will be one entry in the array for each entry in the request body. Only the Id field of the Jobs will be returned.

If the request fails, an Error Response is generated.