Update job

To update a job, send a PATCH request to https://api.planadoapp.com/v2/jobs/:job_id. :job_id can be an external_id or a uuid value. Fields listed in the query will be updated:

$ curl -H "Authorization: Bearer api-key" \
       -X PATCH \
       --data "{\"description\": \"Updated description\"}" \
       https://api.planadoapp.com/v2/jobs/8070f98d-b3f6-4cc8-b7c4-54b6709cd98b | jq
{
  "job_uuid": "8070f98d-b3f6-4cc8-b7c4-54b6709cd98b"
}

Request schema

All fields are optional.

Field Type JSON type Required Can be null Description

description

String

String

No

Yes

Text value describing the work to be done. Limited to 15000 characters

scheduled_at

Datetime

String

No

Yes

Planned job start time

scheduled_duration

Duration

Object

No

Yes

Planned job duration

assignee

Assignee

Object

No

Yes

Worker or team assigned to the job

assignees

[Multiple assignee]

Array

No

No

List of assignees.
If passed than assignee field is ignored. Must be exactly one assignee with edit access.

possible_resolutions

[Resolution]

Array

No

No

List of possible resolutions.
If passed, it must contain at least one successful and one unsuccessful

address

Address

Object

No

No

Address fields

contacts

[Contact]

Array

No

No

List of contacts

client

Existing client or New client

Object

No

Yes

Client

site

Existing site or New site

Object

No

Yes

Site

territory

Territory

Object

No

Yes

Territory

skills

[Skill]

Array

No

No

Skills required to complete the job

custom_fields

[Custom field]

Array

No

No

Values of custom job fields

report_fields

[Custom field]

Array

No

No

Values of job report fields

expected_version

Integer

Number

No

No

The job’s version your update is based on. If the job has changed since, the update is refused, see Conditional update

Some of the fields, such as possible_resolutions, assignees, or assignee, cannot be updated in started jobs.

Conditional update

To avoid overwriting a change made after you read the job (for example, a dispatcher’s manual edit of the duration), pass expected_version: the version returned by the job request. Planado checks the version and writes the update atomically, so a change made after your read is never overwritten.

$ curl -H "Authorization: Bearer api-key" \
       -X PATCH \
       --data "{\"scheduled_duration\": {\"minutes\": 90}, \"expected_version\": 5}" \
       https://api.planadoapp.com/v2/jobs/8070f98d-b3f6-4cc8-b7c4-54b6709cd98b | jq

If the job’s version is no longer expected_version, nothing is written and the response is 409 Conflict:

{
  "code": "stale_version",
  "retryable": false
}

Any change to the job increases its version, not only a change to the fields you send: a status change by a worker, for example. On stale_version, request the job again, decide whether the update is still needed and send it with the new version.

Without expected_version, the update is applied to the current state of the job. In both cases the response may also be 409 Conflict with "code": "version_conflict" and "retryable": true when the job is being changed concurrently: repeat the same request.

Updating and adding fields

See examples.