Create job

Job in Planado is an assignment for a field worker.

To add a job send a POST request:

$ curl -H "X-Planado-API-Key:XXX" \
       --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

Assgnee

Object

No

Yes

Worker or team assigned to the job

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

Client

Object

No

Yes

Client

site

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

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 "X-Planado-API-Key:XXX" \
       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 "X-Planado-API-Key:XXX" \
       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 "X-Planado-API-Key:XXX" \
       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 "X-Planado-API-Key:XXX" \
       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"
}