List jobs

Jobs are listed from newest to oldest.

$ curl -H "Authorization: Bearer api-key" https://api.planadoapp.com/v2/jobs | jq
{
  "jobs": [
    {
      "uuid": "137eafeb-15d1-6480-022b-0ec4617ba21a",
      "external_id": "job",
      "external_order_id": "crm-deal-678190454834217",
      "serial_no": 22469,
      "status": "scheduled",
      "scheduled_at": "2019-11-20T06:25:00",
      "scheduled_duration": {
        "minutes": 60
      },
      "template_uuid": "e6fb6e46-21a7-4d1e-abec-19e5e7dcdb43",
      "client_uuid": "298b4eca-757a-5296-9078-a9991942704f",
      "site_uuid": "eb5140ea-d635-45a3-ad77-6750a995c126",
      "type_uuid": "9898b1d8-a04b-4073-a08e-b470f029fdb2",
      "assignee": {
        "worker_uuid": "4132ed05-3b6d-456c-b3ef-ee1cc6af1e90"
      },
      "skill_uuids": ["a1620b1d-257d-49a9-9adf-6e958603c571"],
      "territory_uuid": "70f19e99-d3e3-4366-8bd9-2f1c8c8c784a",
      "initial_job_uuid": "89b5ab82-5637-4bde-91bc-7dd844ccbaef",
      "completion_of_uuid": null,
      "version": 5,
      "created_at": "2016-05-29T17:31:01.419601Z",
      "updated_at": "2016-06-07T10:57:19.529209Z"
    },
    ...
  ]
}
Table 1. Fields of jobs elements
Field Type JSON type Can be null Description

uuid

UUID

String

No

Unique identifier

external_id

String

String

Yes

Unique identifier in an external system.
Use it for linking sites with data from another source

external_order_id

String

String

Yes

Order identifier in an external system.
This value is not unique, you can link multiple jobs to a single order, lead or similar thing in another system

serial_no

Integer

Number

No

Sequential job number

status

String

String

No

Current job status

scheduled_at

Datetime

String

Yes

Planned job start time

scheduled_duration

Duration

String

Yes

Planned job duration

description

String

String

Yes

Large text with job decription. Limited to 15000 characters

assignee

Asssignee

Object

Yes

Either a user or a team

type_uuid

UUID

String

No

Job type identifier

template_uuid

UUID

String

Yes

Template identifier

client_uuid

UUID

String

Yes

Client identifier

site_uuid

UUID

String

Yes

Site identifier

contacts

[Contact]

Array

No

List of job contacts

territory_uuid

UUID

String

Yes

Territory identifier

skill_uuids

[UUID]

Array

No

List of skill identifiers required to complete the job

initial_job_uuid

UUID

String

Yes

Reference to initial job

completion_of_uuid

UUID

String

Yes

Reference to the first job that current job completes

version

Integer

Number

No

Version

created_at

Timestamp

String

No

Timestamp of creation

updated_at

Timestamp

String

No

Timestamp of last update

Filters

Planado provides jobs filtering by values of several fields. Supported fields and examples are shown below.

Table 2. Fields and types
Field Type Description

updated_at

Timestamp

Corresponding timestamp. Use before and after to specify the interval

scheduled_at

Timestamp

assignee

Assignee UUID

Reference to assignee

external_order_id

String

External order ID

client

Client

Reference to client

site_uuid

UUID

UUID of site

initial_job_uuid

UUID

UUID of the first job among linked jobs

completion_of_uuid

UUID

UUID of the first job with same template among linked jobs

status

[String]

Values can be posted, scheduled, published, canceled, en_route, started, suspended or finished

resolution

[Resolution UUID]

Either finished or canceled with UUID

These filters can be combined with each other to use in more specific and complex cases. Here are some examples.

Several line breaks were added to increase readability of examples. In practice the URL should be inline.
Worker’s canceled jobs with specific client
$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs
    ?assignee[worker_uuid]=138b2e36-2b6b-6c50-6f69-26c43ed9b2b0
    &client[uuid]=139b71ac-992a-6e20-d683-6a71902902ea
    &status[]=canceled" | jq
{
  "jobs": [...]
}
Team’s jobs scheduled after specific date
$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs
    ?assignee[team_uuid]=13871a50-0c21-6db0-e26c-5ad29ae5a3b0
    &scheduled_at[after]=2022-01-01T00:00:00Z" | jq
{
  "jobs": [...]
}
Job’s completion jobs which are in progress at this moment
$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs
    ?initial_job_uuid=139ed223-8001-6a90-b795-2cde48001122
    &status[]=started" | jq
{
  "jobs": [...]
}
Combined usage of statuses and resolutions
$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs
    ?status[]=en_route
    &resolution[finished][]=1395596e-d044-6ed0-5b26-7a1a1b701773
    &resolution[canceled][]=14b89ff7-992e-436f-aa74-3f4e2a0ffe08" | jq
{
  "jobs": [...]
}
By updated_at or scheduled_at value
$ curl -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?updated_at[before]=2019-10-01T10:30:10Z&updated_at[after]=2019-09-30T10:30:10Z" | jq
{
  "jobs": [...]
}
before and after filters use strict comparison. Both values are optional.
By assignee’s team_uuid
$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?assignee[team_uuid]=1003e595-8d42-4150-af7c-65471ea6ca3f" | jq
{
  "jobs": [...]
}
By assignee’s worker_uuid
$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?assignee[worker_uuid]=2d3716c1-4a5f-4619-966c-bd31eb255880" | jq
{
  "jobs": [...]
}
By external_order_id value
$ curl -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?external_order_id=order12345" | jq
{
  "jobs": [...]
}
By client’s uuid
$ curl -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?client[uuid]=139cd1f4-b6f4-6a50-d9f6-7a1c0ed35d03" | jq
{
  "jobs": [...]
}
Either client[uuid] or client_uuid can be used.
By client’s external_id
$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?client[external_id]=company1" | jq
{
  "jobs": [...]
}
By site_uuid value
$ curl -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?site_uuid=139446fc-38cf-6cf0-b199-12b7bdb9b0f2" | jq
{
  "jobs": [...]
}
By initial_job_uuid value
$ curl -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?initial_job_uuid=1395f23e-8b10-6620-01dd-06a9499c9a2c" | jq
{
  "jobs": [...]
}
By completion_of_uuid value
$ curl -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?completion_of_uuid=1395f23f-5cdb-6cc0-7bc1-66da105d8854" | jq
{
  "jobs": [...]
}
The difference between initial_job_uuid and completion_of_uuid is that the former means the oldest job among all linked jobs, and the latter refers to job’s oldest ancestor that was created using the same template.
On diagram below initial_job_uuid for all linked jobs is an unique identificator of Initial job. But as for completion_of_uuid, Linked job 1 refers to Initial job, when Linked job 2 to Linked job with different data.
 --------------------                              --------------------
|    Initial job     |        New template        |  Linked job with   |
|                    | -------------------------> |   different data   |
|     Template 1     |                            |     Template 2     |
 --------------------                              --------------------
          |                                                 |
          |  Completion job                                 |  Completion job
          |                                                 |
          V                                                 V
 --------------------                              --------------------
|    Linked job 1    |                            |    Linked job 2    |
|                    |                            |                    |
|     Template 1     |                            |     Template 2     |
 --------------------                              --------------------
By statuses
$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?status[]=finished&status[]=en_route"
{
  "jobs": [...]
}
Statuses are passed to Planado as an array of strings.
By resolutions
$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?resolution[finished][]=1395596e-d044-6ed0-5b26-7a1a1b701773&resolution[finished][]=14b89ff7-992e-436f-aa74-3f4e2a0ffe08&resolution[canceled][]=14b89ff7-992e-436f-aa74-3f4e2a0ffe08" | jq
{
  "jobs": [...]
}

Filtering by resolutions is a more complex case. Values are passed to Planado as object, schema of which is shown below.

Table 3. Fields of resolution
Field Type Required Description

finished

[UUID]

No

If provided, will additionally restrict search results to those, which use the supplied resolutions

canceled

[UUID]

No

It’s unnecessary to specify status filter if request already contains the resolution of the same type.
Only finished and canceled statuses support resolutions.

See also