Create job

Job in Planado is an assignment for a field worker.

To add a job send a POST request:

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

Request schema

All fields are optional.

Field Type JSON type Required Can be null Description

template

Template

Object

No

No

Job template

job_type

Job type

Object

No

No

Job type

external_id

String

String

No

No

External job identifier. Limited to 500 characters

external_order_id

String

String

No

No

Link to a worke order or a similar entity in another system. Can be non-unique. Limited to 500 characters

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 contain 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

List of job report fields

Grouping jobs

One job describes a piece of work done by a field worker within a single travel. Thus, one job usually takes less than one day. Jobs can be grouped together using external_order_id to reflect the case when one work order (or a CRM lead, or a similar thing) requires several visits.

Examples of passing custom field values

For custom fields value type depends on data_type.

data_type is "string"

$ curl -H "Authorization: Bearer api-key" \
       https://api.planadoapp.com/v2/jobs \
       --data @- <<EOF | jq
{
  "template": {
    "name": "Repair"
  },
  "custom_fields": [
    {"name": "Text description", "value": "String value"}
  ]
}
EOF
{
  "job_uuid": "8070f98d-b3f6-4cc8-b7c4-54b6709cd98b"
}

data_type is "attachment"

$ curl -H "Authorization: Bearer api-key" \
       https://api.planadoapp.com/v2/jobs \
       --data @- <<EOF | jq
{
  "template": {
    "name": "Diagnostic"
  },
  "custom_fields": [
    {
      "name": "Instructions",
      "value": {
        "name": "Hello.txt",
        "base64_content": "SGVsbG8gd29ybGQhCg=="
      }
    }
  ]
}
EOF
{
  "job_uuid": "8070f98d-b3f6-4cc8-b7c4-54b6709cd98b"
}

data_type is "dictionary"

Using name

$ curl -H "Authorization: Bearer api-key" \
       https://api.planadoapp.com/v2/jobs \
       --data @- <<EOF | jq
{
  "template": {
    "name": "Delivery"
  },
  "custom_fields": [
    {
      "name": "Size",
      "value": {
        "name": "XL"
      }
    }
  ]
}
EOF
{
  "job_uuid": "8070f98d-b3f6-4cc8-b7c4-54b6709cd98b"
}

Using uuid values for field and value

$ curl -H "Authorization: Bearer api-key" \
       https://api.planadoapp.com/v2/jobs \
       --data @- <<EOF | jq
{
  "template": {
    "name": "Delivery"
  },
  "custom_fields": [
    {
      "uuid": "68f7423b-3c7f-4f29-8d4e-9242492832d9",
      "value": {
        "uuid": "fdb3c3f9-df4a-4c7a-8b0a-52300120080b"
      }
    }
  ]
}
EOF
{
  "job_uuid": "8070f98d-b3f6-4cc8-b7c4-54b6709cd98b"
}