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"
}
}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.
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
Body
- Option 1
- Option 2
Job fields for create and update. Unknown fields are refused with 400. On update only the fields sent change.