Create jobs
curl --request POST \
--url https://api.hellotracks.com/v1/jobs \
--header 'API-Key: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"jobs": [
{
"externalId": "ORDER-1001",
"title": "Install water heater",
"address": "500 Market St, San Francisco, CA 94105",
"assigneeId": "a1b2c3",
"date": "2026-11-02",
"timeWindow": {
"start": "09:00",
"end": "12:00"
},
"onSiteDurationSeconds": 3600,
"priority": 2,
"notes": "Ring at the side door.",
"contact": {
"name": "Sam Lee",
"phone": "+14155550102",
"email": "sam@example.com"
},
"customFields": {
"PO": "4711"
}
}
]
}
'import requests
url = "https://api.hellotracks.com/v1/jobs"
payload = { "jobs": [
{
"externalId": "ORDER-1001",
"title": "Install water heater",
"address": "500 Market St, San Francisco, CA 94105",
"assigneeId": "a1b2c3",
"date": "2026-11-02",
"timeWindow": {
"start": "09:00",
"end": "12:00"
},
"onSiteDurationSeconds": 3600,
"priority": 2,
"notes": "Ring at the side door.",
"contact": {
"name": "Sam Lee",
"phone": "+14155550102",
"email": "sam@example.com"
},
"customFields": { "PO": "4711" }
}
] }
headers = {
"API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
jobs: [
{
externalId: 'ORDER-1001',
title: 'Install water heater',
address: '500 Market St, San Francisco, CA 94105',
assigneeId: 'a1b2c3',
date: '2026-11-02',
timeWindow: {start: '09:00', end: '12:00'},
onSiteDurationSeconds: 3600,
priority: 2,
notes: 'Ring at the side door.',
contact: {name: 'Sam Lee', phone: '+14155550102', email: 'sam@example.com'},
customFields: {PO: '4711'}
}
]
})
};
fetch('https://api.hellotracks.com/v1/jobs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hellotracks.com/v1/jobs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'jobs' => [
[
'externalId' => 'ORDER-1001',
'title' => 'Install water heater',
'address' => '500 Market St, San Francisco, CA 94105',
'assigneeId' => 'a1b2c3',
'date' => '2026-11-02',
'timeWindow' => [
'start' => '09:00',
'end' => '12:00'
],
'onSiteDurationSeconds' => 3600,
'priority' => 2,
'notes' => 'Ring at the side door.',
'contact' => [
'name' => 'Sam Lee',
'phone' => '+14155550102',
'email' => 'sam@example.com'
],
'customFields' => [
'PO' => '4711'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"API-Key: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.hellotracks.com/v1/jobs"
payload := strings.NewReader("{\n \"jobs\": [\n {\n \"externalId\": \"ORDER-1001\",\n \"title\": \"Install water heater\",\n \"address\": \"500 Market St, San Francisco, CA 94105\",\n \"assigneeId\": \"a1b2c3\",\n \"date\": \"2026-11-02\",\n \"timeWindow\": {\n \"start\": \"09:00\",\n \"end\": \"12:00\"\n },\n \"onSiteDurationSeconds\": 3600,\n \"priority\": 2,\n \"notes\": \"Ring at the side door.\",\n \"contact\": {\n \"name\": \"Sam Lee\",\n \"phone\": \"+14155550102\",\n \"email\": \"sam@example.com\"\n },\n \"customFields\": {\n \"PO\": \"4711\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.hellotracks.com/v1/jobs")
.header("API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"jobs\": [\n {\n \"externalId\": \"ORDER-1001\",\n \"title\": \"Install water heater\",\n \"address\": \"500 Market St, San Francisco, CA 94105\",\n \"assigneeId\": \"a1b2c3\",\n \"date\": \"2026-11-02\",\n \"timeWindow\": {\n \"start\": \"09:00\",\n \"end\": \"12:00\"\n },\n \"onSiteDurationSeconds\": 3600,\n \"priority\": 2,\n \"notes\": \"Ring at the side door.\",\n \"contact\": {\n \"name\": \"Sam Lee\",\n \"phone\": \"+14155550102\",\n \"email\": \"sam@example.com\"\n },\n \"customFields\": {\n \"PO\": \"4711\"\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hellotracks.com/v1/jobs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"jobs\": [\n {\n \"externalId\": \"ORDER-1001\",\n \"title\": \"Install water heater\",\n \"address\": \"500 Market St, San Francisco, CA 94105\",\n \"assigneeId\": \"a1b2c3\",\n \"date\": \"2026-11-02\",\n \"timeWindow\": {\n \"start\": \"09:00\",\n \"end\": \"12:00\"\n },\n \"onSiteDurationSeconds\": 3600,\n \"priority\": 2,\n \"notes\": \"Ring at the side door.\",\n \"contact\": {\n \"name\": \"Sam Lee\",\n \"phone\": \"+14155550102\",\n \"email\": \"sam@example.com\"\n },\n \"customFields\": {\n \"PO\": \"4711\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"items": [
{
"id": "650000000000000000000001",
"externalId": "ORDER-1001",
"title": "Install water heater",
"address": "500 Market St, San Francisco, CA 94105",
"notes": "Ring at the side door.",
"issueText": "",
"createdAt": 1793520000000,
"updatedAt": 1793523600000,
"scheduledAt": 0,
"assignedAt": 1793520000000,
"acceptedAt": 0,
"completedAt": 0,
"failedAt": 0,
"progress": "scheduled",
"date": "2026-11-02",
"priority": 2,
"timeWindow": {
"start": "09:00",
"end": "12:00"
},
"onSiteDurationSeconds": 3600,
"location": {
"lat": 37.7897,
"lng": -122.4
},
"assignee": {
"id": "a1b2c3",
"username": "alex@example.com",
"name": "Alex Rivera",
"email": "alex@example.com",
"phone": "+14155550101"
},
"placeId": "p1q2r3",
"contact": {
"name": "Sam Lee",
"phone": "+14155550102",
"email": "sam@example.com"
},
"customFields": {
"PO": "4711"
},
"linkedForms": [
{
"id": "f1a2b3",
"title": "Install checklist"
}
],
"etaSessionId": "eta_k7m2p9x4q8r3",
"etaUrl": "https://eta.page/K7M2-P9X4-Q8R3"
}
]
},
"error": null,
"meta": {
"path": "/v1/jobs",
"method": "POST"
}
}{
"data": null,
"error": {
"code": "invalid_request",
"message": "date must be YYYY-MM-DD"
},
"meta": {
"path": "/jobs",
"method": "GET"
}
}{
"data": null,
"error": {
"code": "invalid_api_key",
"message": "Invalid Hellotracks API key."
},
"meta": {
"path": "/jobs",
"method": "GET"
}
}{
"data": null,
"error": {
"code": "forbidden",
"message": "No permission."
},
"meta": {
"path": "/jobs",
"method": "GET"
}
}{
"data": null,
"error": {
"code": "throttled",
"message": "Too many requests."
},
"meta": {
"path": "/jobs",
"method": "GET"
}
}{
"data": null,
"error": {
"code": "internal_error",
"message": "Hellotracks API is temporarily unavailable."
},
"meta": {
"path": "/jobs",
"method": "GET"
}
}Jobs
Create jobs
Creates one job (the job object as the body) or several ({"jobs": [...]}).
A job whose externalId matches an existing job of the company is updated with the fields sent instead of creating a duplicate (upsert), and is set back to normal if it was archived. A job that was deleted in Hellotracks stays deleted: it is not changed, and the answer lists it with status: "deleted". The answer lists one job per job sent, in the same order.
Jobs without a location get the location of their place, else their address is geocoded in the background, so the response can still show location 0/0. Jobs that are assigned and dated drop the worker’s saved route for that day, workers get the updated jobs, and the company’s job webhooks fire. Unknown fields are refused with 400.
POST
/
jobs
Create jobs
curl --request POST \
--url https://api.hellotracks.com/v1/jobs \
--header 'API-Key: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"jobs": [
{
"externalId": "ORDER-1001",
"title": "Install water heater",
"address": "500 Market St, San Francisco, CA 94105",
"assigneeId": "a1b2c3",
"date": "2026-11-02",
"timeWindow": {
"start": "09:00",
"end": "12:00"
},
"onSiteDurationSeconds": 3600,
"priority": 2,
"notes": "Ring at the side door.",
"contact": {
"name": "Sam Lee",
"phone": "+14155550102",
"email": "sam@example.com"
},
"customFields": {
"PO": "4711"
}
}
]
}
'import requests
url = "https://api.hellotracks.com/v1/jobs"
payload = { "jobs": [
{
"externalId": "ORDER-1001",
"title": "Install water heater",
"address": "500 Market St, San Francisco, CA 94105",
"assigneeId": "a1b2c3",
"date": "2026-11-02",
"timeWindow": {
"start": "09:00",
"end": "12:00"
},
"onSiteDurationSeconds": 3600,
"priority": 2,
"notes": "Ring at the side door.",
"contact": {
"name": "Sam Lee",
"phone": "+14155550102",
"email": "sam@example.com"
},
"customFields": { "PO": "4711" }
}
] }
headers = {
"API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
jobs: [
{
externalId: 'ORDER-1001',
title: 'Install water heater',
address: '500 Market St, San Francisco, CA 94105',
assigneeId: 'a1b2c3',
date: '2026-11-02',
timeWindow: {start: '09:00', end: '12:00'},
onSiteDurationSeconds: 3600,
priority: 2,
notes: 'Ring at the side door.',
contact: {name: 'Sam Lee', phone: '+14155550102', email: 'sam@example.com'},
customFields: {PO: '4711'}
}
]
})
};
fetch('https://api.hellotracks.com/v1/jobs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hellotracks.com/v1/jobs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'jobs' => [
[
'externalId' => 'ORDER-1001',
'title' => 'Install water heater',
'address' => '500 Market St, San Francisco, CA 94105',
'assigneeId' => 'a1b2c3',
'date' => '2026-11-02',
'timeWindow' => [
'start' => '09:00',
'end' => '12:00'
],
'onSiteDurationSeconds' => 3600,
'priority' => 2,
'notes' => 'Ring at the side door.',
'contact' => [
'name' => 'Sam Lee',
'phone' => '+14155550102',
'email' => 'sam@example.com'
],
'customFields' => [
'PO' => '4711'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"API-Key: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.hellotracks.com/v1/jobs"
payload := strings.NewReader("{\n \"jobs\": [\n {\n \"externalId\": \"ORDER-1001\",\n \"title\": \"Install water heater\",\n \"address\": \"500 Market St, San Francisco, CA 94105\",\n \"assigneeId\": \"a1b2c3\",\n \"date\": \"2026-11-02\",\n \"timeWindow\": {\n \"start\": \"09:00\",\n \"end\": \"12:00\"\n },\n \"onSiteDurationSeconds\": 3600,\n \"priority\": 2,\n \"notes\": \"Ring at the side door.\",\n \"contact\": {\n \"name\": \"Sam Lee\",\n \"phone\": \"+14155550102\",\n \"email\": \"sam@example.com\"\n },\n \"customFields\": {\n \"PO\": \"4711\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.hellotracks.com/v1/jobs")
.header("API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"jobs\": [\n {\n \"externalId\": \"ORDER-1001\",\n \"title\": \"Install water heater\",\n \"address\": \"500 Market St, San Francisco, CA 94105\",\n \"assigneeId\": \"a1b2c3\",\n \"date\": \"2026-11-02\",\n \"timeWindow\": {\n \"start\": \"09:00\",\n \"end\": \"12:00\"\n },\n \"onSiteDurationSeconds\": 3600,\n \"priority\": 2,\n \"notes\": \"Ring at the side door.\",\n \"contact\": {\n \"name\": \"Sam Lee\",\n \"phone\": \"+14155550102\",\n \"email\": \"sam@example.com\"\n },\n \"customFields\": {\n \"PO\": \"4711\"\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hellotracks.com/v1/jobs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"jobs\": [\n {\n \"externalId\": \"ORDER-1001\",\n \"title\": \"Install water heater\",\n \"address\": \"500 Market St, San Francisco, CA 94105\",\n \"assigneeId\": \"a1b2c3\",\n \"date\": \"2026-11-02\",\n \"timeWindow\": {\n \"start\": \"09:00\",\n \"end\": \"12:00\"\n },\n \"onSiteDurationSeconds\": 3600,\n \"priority\": 2,\n \"notes\": \"Ring at the side door.\",\n \"contact\": {\n \"name\": \"Sam Lee\",\n \"phone\": \"+14155550102\",\n \"email\": \"sam@example.com\"\n },\n \"customFields\": {\n \"PO\": \"4711\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"items": [
{
"id": "650000000000000000000001",
"externalId": "ORDER-1001",
"title": "Install water heater",
"address": "500 Market St, San Francisco, CA 94105",
"notes": "Ring at the side door.",
"issueText": "",
"createdAt": 1793520000000,
"updatedAt": 1793523600000,
"scheduledAt": 0,
"assignedAt": 1793520000000,
"acceptedAt": 0,
"completedAt": 0,
"failedAt": 0,
"progress": "scheduled",
"date": "2026-11-02",
"priority": 2,
"timeWindow": {
"start": "09:00",
"end": "12:00"
},
"onSiteDurationSeconds": 3600,
"location": {
"lat": 37.7897,
"lng": -122.4
},
"assignee": {
"id": "a1b2c3",
"username": "alex@example.com",
"name": "Alex Rivera",
"email": "alex@example.com",
"phone": "+14155550101"
},
"placeId": "p1q2r3",
"contact": {
"name": "Sam Lee",
"phone": "+14155550102",
"email": "sam@example.com"
},
"customFields": {
"PO": "4711"
},
"linkedForms": [
{
"id": "f1a2b3",
"title": "Install checklist"
}
],
"etaSessionId": "eta_k7m2p9x4q8r3",
"etaUrl": "https://eta.page/K7M2-P9X4-Q8R3"
}
]
},
"error": null,
"meta": {
"path": "/v1/jobs",
"method": "POST"
}
}{
"data": null,
"error": {
"code": "invalid_request",
"message": "date must be YYYY-MM-DD"
},
"meta": {
"path": "/jobs",
"method": "GET"
}
}{
"data": null,
"error": {
"code": "invalid_api_key",
"message": "Invalid Hellotracks API key."
},
"meta": {
"path": "/jobs",
"method": "GET"
}
}{
"data": null,
"error": {
"code": "forbidden",
"message": "No permission."
},
"meta": {
"path": "/jobs",
"method": "GET"
}
}{
"data": null,
"error": {
"code": "throttled",
"message": "Too many requests."
},
"meta": {
"path": "/jobs",
"method": "GET"
}
}{
"data": null,
"error": {
"code": "internal_error",
"message": "Hellotracks API is temporarily unavailable."
},
"meta": {
"path": "/jobs",
"method": "GET"
}
}Authorizations
Your API key, from More → API & Integrations in the dashboard, or from ht signup / ht auth login.
Body
application/json
- Option 1
- Option 2
Job fields for create and update. Unknown fields are refused with 400. On update only the fields sent change.
Job id. Only used by PATCH /jobs (single form); ignored elsewhere.
Your own id. On POST /jobs an existing job of the company with the same externalId is updated instead of creating a new one.
Geocoded in the background when no location is given.
Show child attributes
Show child attributes
Link the job to a place. A job without location takes the place's location, a job without title the place's name.
Member id to assign. An empty string unassigns. Do not send together with assigneeUsername.
Member username to assign. An unknown username is ignored. Do not send together with assigneeId.
YYYY-MM-DD. An empty string removes the date; null leaves it as it is.
Show child attributes
Show child attributes
Non-negative integer (or digits as a string).
Required range:
x >= 00 to 10 (or digits as a string).
Required range:
0 <= x <= 10Show child attributes
Show child attributes
Replaces the job's whole set of custom fields: names left out are removed. Values are stored as text.
Show child attributes
Show child attributes