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`	Assignee	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 within a specific time interval

$ 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
    &scheduled_at[before]=2022-05-01T00:00:00Z" | jq
{
  "jobs": [...]
}

time interval must not be longer than 50 days

Jobs finished within a specific time interval

$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs
    ?finished_at[after]=2022-01-01T00:00:00Z
    &finished_at[before]=2022-02-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.

List jobs

Filters

See also