> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.hellotracks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Job API Object

> Properties of the Job API object. Here you can find detailed information on each property, its data type, read/write permissions, and a brief description.

### 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 | W | File number or reference code (not returned in responses) |
| 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 | W | Zip/postal code for the job location (not returned in responses) |
| status | TEXT | R | `archived` or `deleted`, omitted for normal jobs |

### Job Status attributes (progress)

The job status attributes hold the timestamp when an event has occurred or `0` 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 | W | Key mapping configuration (not returned) |
| 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) |

**Note on Form Fields:**

* 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

Use `customFields` when reading or writing custom fields:

```json theme={null}
"customFields": [
  { "key": "PO_Number", "val": "PO-2026-1234" },
  { "key": "Department", "val": "Facilities" }
]
```

Behavior note:

* In `/editjobs`, setting `customFields` clears and replaces all existing custom fields on that job.
* In `/createjobs`, the same replacement behavior applies when the request updates an existing job via matching `uidSecondary`.

```json Example theme={null}
{
    "assigneeName":"David Miller",
    "assigneeUsername":"david.miller",
    "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":"650000000000000000000001",
    "inputFormConfig":"",
    "itemsToDropoff":0,
    "itemsToPickup":0,
    "labels":"",
    "linkedForms":"",
    "linkedZones":"",
    "manualChecks":"",
    "number":1,
    "onSiteSeconds":720,
    "orderId":0,
    "placeName":"Pickup at Matteo",
    "placeUid":"p1q2r3",
    "placeUrl":"https://hellotracks.com/img/accounts/p1q2r3/portrait_example_thumb.jpg",
    "priority":5,
    "radius":100,
    "receiverUid":"d4e5f6",
    "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://example.com/forms/safety-check",
    "url_2":"https://google.com",
    "windowEnd":2400,
    "windowStart":0,
    "worker":"david.miller",
    "workerEmail":"david.miller@example.com",
    "workerName":"David Miller",
    "workerPhone":""
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.