> ## 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.

# Get Jobs

> This endpoint retrieves jobs.

### Request

```shell theme={null}
POST https://api.hellotracks.com/api/getjobs

{
	data: {
	    id: "<id>",
        ids: [ "<id1>", "<id2>", "<idn>" ],
		uidSecondary: "<your-id>" (optional),
		day: 20231105,
		worker: "<worker-username>",
		team: <number> (optional),
		teamIds: [<number1>,<number2>,...] (optional),
		includeUnsetTeam: true (optional),
		orderId: <number> (optional),
		orderIds: [<number1>,<number2>,...] (optional array of multiple orderIds),
		progressSuccess: 1 (optional),
		progressActive: 1 (optional),
		includeArchived: 1 (optional),
		omitSignatureSvg: true (optional),
		sort: {
			field: "<field_name>",
			ascending: true/false,
			limit: <number>,
			skip: <number>,
			from: <timestamp>,
			until: <timestamp>,
			status: <number> (optional)
		} (optional),
		query: {
			filterIds: ["updated"],
			updatedSince: <timestamp>,
			text: "<search text>",
			allDates: true
		} (optional)
	}
}
```

**id** `string`

Set this if you want to retrieve a specific job.

**ids** `array`

Use this field to retrieve multiple specific jobs.

**uidSecondary** `string`

Retrieve the job with this ID from your own system (the `uidSecondary` you set when creating it). Returns that one job, whatever its day and worker, or an empty `jobs` list.

**day** `number`

`day` is optional and defaults to today. To retrieve jobs with no date assigned, set `day:0`.
To specifically ignore the `day` field, set `day:-1`.

**worker** `string`

To retrieve jobs that are not assigned to a worker, set `worker:""`. To request jobs assigned to any worker, set `worker:"+"`. To request all jobs, assigned and unassigned, for a specific date, set `worker:"*"`. Without `worker`, only jobs assigned to the caller are returned; with an API key the caller is the company account, so this is usually empty.

**team** `number`

`team` is an optional filter to only request jobs for a specific team.

**teamIds** `array`

Only jobs of these teams. Use instead of `team` for several teams.

**includeUnsetTeam** `boolean` (default: false)

With `teamIds`, also include jobs that have no team.

**orderId** `number`

Optional filter to request a specific job.

**orderIds** `array`

Optional filter to request multiple specific jobs.

**progressSuccess** `number` (default: 0)

`progressSuccess` is an optional filter to only retrieve jobs that are marked as successfully completed. For this, set the value to `1`, else set it either to `0` or do not set the field at all.

**progressActive** `number` (default: 0)

`progressActive` is an optional filter to only retrieve jobs that are not marked as completed (neither success nor issue). For this, set the value to `1`, else set it either to `0` or do not set the field at all.

**includeArchived** `number` (default: 0)

Set to `1` to include archived jobs in the results. Defaults to `0` (exclude archived jobs). Deleted jobs are never returned.

**sort** `object`

Optional sorting and pagination configuration object with the following properties:

* `field` (string, required): Field name to sort by (e.g., "tsCreated", "priority", "number")
* `ascending` (boolean, required): Sort direction - true for ascending, false for descending
* `limit` (number, required): Maximum number of jobs to return
* `skip` (number, required): Number of jobs to skip (for pagination)
* `from` (long): Only jobs whose sort `field` is at or after this value (e.g. a timestamp in milliseconds when sorting by "tsCreated")
* `until` (long): Only jobs whose sort `field` is at or before this value
* `status` (number): `0` normal jobs only, `1` archived jobs only, `-1` (default) both

When `sort` is provided, the `day` parameter defaults to undefined (all days) unless explicitly specified, and archived jobs are included. A missing required property returns status `-1`.

**query** `object`

Optional filters, mostly used together with `sort` for paging:

* `filterIds` (array): `"updated"` keeps jobs changed at or after `updatedSince`, `"today"` jobs of today, `"nodate"` jobs without a date
* `updatedSince` (long): timestamp in milliseconds for `"updated"`. Defaults to one hour ago.
* `text` (string): jobs whose name, address or notes contain this text, ignoring case; a job id or order id also matches
* `allDates` (boolean): search all dates instead of one day

With `query` and `sort`, an empty sort `field` orders by the time the job was last saved.

**omitSignatureSvg** `boolean` (default: false)

Leave out `signatureSvg` to keep responses small.

### RESPONSE

```shell theme={null}
{
	status: 0,
	jobs : [
		{ <job_1> },
		{ <job_2> },
		   ...
		{ <job_n> }
	],
	totalCount: <number>,
	hasMore: <boolean>
}
```

`totalCount` and `hasMore` come with `sort` or `query`: `totalCount` is the number of matching jobs, and `hasMore` is `true` when more pages follow.

### Keeping jobs in sync

To copy changes into your own system, ask regularly for the jobs saved since your last run, oldest first, page by page:

```json theme={null}
{
  "data": {
    "worker": "*",
    "sort": { "field": "tsSaved", "ascending": true, "limit": 200, "skip": 0 },
    "query": { "filterIds": ["updated"], "updatedSince": 1793520000000 }
  }
}
```

Increase `skip` by `limit` while `hasMore` is `true`. Next time, use the newest `tsSaved` you received as `updatedSince`. Archived jobs are included (their `status` is `archived`); deleted jobs are not returned.

```bash Example Request theme={null}
curl -X POST https://api.hellotracks.com/api/getjobs --header 'API-Key: ...' -d '
{
    "data": {
        "worker":"*",
        "day": 20230813
    }
}
'
```

<Snippet file="jobs-response.mdx" />


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