Job API Object
| Property | Type | R/W | Description |
|---|---|---|---|
| id | TEXT | R | Job unique ID |
| uidSecondary | TEXT | RW | Secondary unique identifier (custom external ID) |
| type | INT | RW | Job Type: 0=Work, 1=Pickup, 2=Dropoff |
| teamId | INT | RW | Team Id 0-n (the number of the team). Defaults to 0 (no specific team). |
| destinationName | TEXT | RW | Title of this job (1-line description) |
| destinationLat | DOUBLE | RW | Latitude |
| destinationLng | DOUBLE | RW | Longitude |
| destinationText | TEXT | RW | Location Address |
| destinationUrl | TEXT | R | Location map URL |
| textDispatcher | TEXT | RW | Dispatcher additional info text (multi-line). Can also use notes field. |
| notes | TEXT | RW | Alias for textDispatcher - dispatcher notes/instructions |
| textReceiver | TEXT | RW | Worker’s reply text |
| contactName | TEXT | RW | Name of contact at job’s location |
| contactPhone | TEXT | RW | Phone number of contact at job’s location |
| contactEmail | TEXT | RW | Email of contact at job’s location |
| fileNumber | TEXT | RW | File number or reference code |
| day | INT | RW | Date for job as YYYYMMDD or 0 (e.g. 20150530) |
| priority | INT | RW | Priority min:0-max:10 |
| number | INT | RW | Sequence number for ordering |
| onSiteSeconds | INT | RW | The assumed onsite-time in seconds (e.g. 10min on site: 600) |
| windowStart | INT | RW | Format: HHMM or 0 (e.g 704 = 7:04am) |
| windowEnd | INT | RW | Format: HHMM or 0 (e.g 1724 = 5:24pm) |
| orderId | LONG | RW | Optional Order ID as a long integer number |
| dispatcherUid | TEXT | RW | UID of dispatcher account |
| dispatcherName | TEXT | R | Name of Dispatcher |
| dispatcherUrl | TEXT | R | URL for dispatcher icon image |
| placeUid | TEXT | RW | UID of place to visit or "" |
| placeName | TEXT | R | Name of place/location |
| placeUrl | TEXT | R | URL for place icon image |
| radius | INT | R | Radius for check-in/out in meter (place-radius or default-radius) |
| worker | TEXT | RW | User name of assigned worker |
| receiverUid | TEXT | RW | UID of assigned worker (alternative to worker) |
| workerName | TEXT | R | Full name of assigned worker |
| workerEmail | TEXT | R | Email address of assigned worker |
| workerPhone | TEXT | R | Phone number of assigned worker |
| assigneeName | TEXT | R | Legacy alias for workerName (deprecated, use workerName) |
| assigneeUsername | TEXT | R | Legacy alias for worker (deprecated, use worker) |
| itemsToDropoff | INT | RW | Number of items to drop off |
| itemsToPickup | INT | RW | Number of items to pick up |
| carryOver | INT | RW | Days left to carry over (use 1 for default carry-over days) |
| labels | TEXT | RW | Comma-separated labels for categorization |
| zipcode | INT | RW | Zip/postal code for the job location |
| status | TEXT | R | Set to archived if job is archived, omitted otherwise |
Job Status attributes (progress)
The job status attributes hold the timestamp when an event has occurred or0 if it does not apply.
Note: Timestamps are milliseconds, between the current time and midnight, January 1, 1970 UTC (Java timestamps)
E.g.: 1430580377000 = Sat, 02 May 2015 15:26:17 GMT
| Property | Type | R/W | Description |
|---|---|---|---|
| tsCreated | LONG | RW | Timestamp in millis for job creation |
| tsSaved | LONG | R | Timestamp in millis when job was last saved |
| tsAssigned | LONG | R | Timestamp in millis for job assigned to worker |
| tsAccepted | LONG | RW | Timestamp in millis for job accepted by worker |
| tsRejected | LONG | RW | Timestamp in millis for job rejected by worker |
| tsScheduled | LONG | RW | Timestamp in millis for job scheduled |
| tsDoneSuccess | LONG | RW | Timestamp in millis for job marked as success by worker |
| tsDoneFailed | LONG | RW | Timestamp in millis for job marked as issue by worker |
| tsCheckIn | LONG | RW | Timestamp in millis for auto check-in by worker |
| tsCheckOut | LONG | RW | Timestamp in millis for auto check-out by worker |
| tsCheckNFC1 | LONG | R | Timestamp in millis for first check with NFC |
| tsCheckNFC2 | LONG | R | Timestamp in millis for second check with NFC |
| tsTripStarted | LONG | R | Timestamp in millis when trip to job location started |
| tsSignature | LONG | RW | Timestamp in millis when signature was captured |
Scheduling & Windows:
| Property | Type | R/W | Description |
|---|---|---|---|
| scheduledStart | INT | R | Scheduled start time calculated by route optimizer |
| scheduledEnd | INT | R | Scheduled end time calculated by route optimizer |
Signature & Digital Forms:
| Property | Type | R/W | Description |
|---|---|---|---|
| signatureName | TEXT | RW | Name of person who signed |
| signatureSvg | TEXT | RW | SVG data for signature (clears signaturePdf) |
| signaturePdf | TEXT | RW | PDF data for signature (clears signatureSvg) |
| keymap | TEXT | RW | Key mapping configuration |
| manualChecks | TEXT | RW | Manual check data |
| linkedZones | TEXT | RW | Linked zone IDs |
| linkedForms | TEXT | RW | Linked form IDs |
| submittedForms | TEXT | R | Submitted form data (read-only) |
| inputFormConfig | TEXT | RW | Input form configuration |
| formConfig | TEXT | R | Complete form configuration (compact mode only) |
| confirmationEmails | TEXT | RW | Confirmation email addresses |
| comments | TEXT | RW | Job comments data |
| associatedJobId | TEXT | RW | Associated job identifier |
| requiredSkills | TEXT | RW | Required skills for this job |
| requiredEquipment | TEXT | RW | Required equipment for this job |
History & Tracking:
| Property | Type | R/W | Description |
|---|---|---|---|
| createdBy | TEXT | R | UID of user who created this job |
| createdVia | TEXT | R | Source of job creation (web, mobile, api) |
| assigneeHistory | TEXT | R | History of worker assignments |
| progressStatusHistory | TEXT | R | History of status changes |
| tripId | TEXT | R | Associated trip identifier |
Template & Sequence Metadata:
| Property | Type | R/W | Description |
|---|---|---|---|
| isTemplate | BOOLEAN | R | True if this is a job template |
| isPartOfSequence | BOOLEAN | R | True if job belongs to a sequence |
| sequenceId | TEXT | R | ID of the sequence this job belongs to |
| jobType | TEXT | R | Human-readable job type name |
Customizable Attributes:
| Property | Type | R/W | Description |
|---|---|---|---|
| custom_$ | TEXT | RW | Request shorthand for one custom field (custom_$: value) |
| customFields | ARRAY | RW | Array of { "key": "...", "val": "..." } objects |
| extra_number_$_key | TEXT | R | Worker input number field label where $ is 1-10 |
| extra_number_$_val | INT | RW | Worker input number value where $ is 1-10 |
| extra_text_$_key | TEXT | R | Worker input text field label where $ is 1-20 |
| extra_text_$_val | TEXT | RW | Worker input text value where $ is 1-20 |
| extra_number_types | TEXT | R | JSON metadata describing number field types |
| extra_text_types | TEXT | R | JSON metadata describing text field types |
| url_$ | TEXT | RW | URL field where $ is 1-n (multiple URLs supported) |
- Field labels (extra_number__key, extra_text__key) are read-only and configured via
inputFormConfig - If a field name starts with
*, it indicates a required field - Types metadata contains JSON like
{"2":"bool","4":"decimal"}to specify special input types - Supported types:
bool(checkbox),decimal,number(default),text(default)
Custom Fields Format
UsecustomFields when reading or writing custom fields:
"customFields": [
{ "key": "PO_Number", "val": "PO-2026-1234" },
{ "key": "Department", "val": "Facilities" }
]
- In
/editjobs, settingcustomFieldsclears and replaces all existing custom fields on that job. - In
/createjobs, the same replacement behavior applies when the request updates an existing job via matchinguidSecondary.
{
"assigneeName":"David Miller",
"assigneeUsername":"test.topservices",
"carryOver":1,
"contactEmail":"",
"contactName":"",
"contactPhone":"",
"confirmationEmails":"",
"customFields":[],
"day":20230813,
"destinationLat":37.785967,
"destinationLng":-122.414136,
"destinationName":"Pickup at Matteo",
"destinationText":"Matteo",
"dispatcherName":"",
"dispatcherUid":"",
"dispatcherUrl":"",
"extra_number_1_key":"This is for number",
"extra_number_1_val":0,
"extra_number_2_key":"This is for checkbox",
"extra_number_2_val":0,
"extra_number_3_key":"This is for number 2",
"extra_number_3_val":0,
"extra_number_4_key":"This is for checkbox 2",
"extra_number_4_val":0,
"extra_number_types":"{\"2\":\"bool\",\"4\":\"bool\",\"6\":\"bool\",\"7\":\"bool\"}",
"extra_text_1_key":"This is for text",
"extra_text_1_val":"",
"extra_text_2_key":"This is for decimal",
"extra_text_2_val":"",
"extra_text_3_key":"This is for text 2",
"extra_text_3_val":"",
"extra_text_4_key":"This is for decimal 2",
"extra_text_4_val":"",
"extra_text_types":"{\"2\":\"decimal\",\"4\":\"decimal\",\"6\":\"decimal\"}",
"id":"64d800e5a3d05d0db096f939",
"inputFormConfig":"",
"itemsToDropoff":0,
"itemsToPickup":0,
"labels":"",
"linkedForms":"",
"linkedZones":"",
"manualChecks":"",
"number":1,
"onSiteSeconds":720,
"orderId":0,
"placeName":"Pickup at Matteo",
"placeUid":"h4863l",
"placeUrl":"https://hellotracks.com/img/accounts/h4863l/portrait_1681311626037_thumb.jpg",
"priority":5,
"radius":100,
"receiverUid":"c0s1xv",
"scheduledEnd":0,
"scheduledStart":0,
"signatureName":"",
"signaturePdf":"",
"signatureSvg":"",
"submittedForms":"",
"teamId":0,
"textDispatcher":"",
"textReceiver":"",
"tsAccepted":0,
"tsAssigned":0,
"tsCheckIn":0,
"tsCheckNFC1":0,
"tsCheckNFC2":0,
"tsCheckOut":0,
"tsCreated":1691877605307,
"tsDoneFailed":0,
"tsDoneSuccess":0,
"tsRejected":0,
"tsSaved":1691877605307,
"tsScheduled":0,
"tsSignature":0,
"type":1,
"url_1":"https://goo.gl/forms/BdY3Cfi1yVVcvwYE3",
"url_2":"https://google.com",
"windowEnd":2400,
"windowStart":0,
"worker":"test.topservices",
"workerEmail":"mario+test.topservices@hellotracks.com",
"workerName":"David Miller",
"workerPhone":""
}