Planado REST API

Planado REST API allows external applications to interact with Planado using HTTP. It enables seamless integration into business processes and leads to a better user experience.

API allows you to send and retrieve data on-demand. If you need Planado to automatically send you notifications, try webhooks.

Every request MUST contain a header with your API key. Go to Setting → Integrations → API to get one. Put the value into the X-Planado-API-Token request header.

The common data format for all API request and responses is JSON, which means that all POST / PATCH requests MUST contain the Content-Type: application/json header.

GET https://api.planadoapp.com/api/v1/jobs.json?page=4
Response200404
Headers
Content-Type: application/json
Message body
{
    "jobs": [
        {
            "assignee_subject_id": 14001,
            "client_id": 427001,
            "site_id": null,
            "job_id": 5675001,
            "scheduled_at": "2015-03-15T20:15:00",
            "serial_no": 47,
            "status": "published",
            "template_id": 957001,
            "type_id": 6001
        },
        {
            "assignee_subject_id": 14001,
            "client_id": 427001,
            "site_id": 4976001,
            "job_id": 5665001,
            "scheduled_at": "2015-03-15T20:00:00",
            "serial_no": 46,
            "status": "started",
            "template_id": 1091001,
            "type_id": 35001
        },
        ...
    ],
    "view_url": "https://your-subdomain.planadoapp.com/jobs",
    "page": 1,
    "total_pages": 1
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "page": {
      "type": "number"
    },
    "total_pages": {
      "type": "number"
    },
    "view_url": {
      "type": "string"
    },
    "jobs": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

List jobs
GET/jobs.json{?page}

Get a paginated list of jobs, 20 per page.

Jobs are ordered by scheduled time. Jobs with no scheduled time come first.

URI Parameters
page
number

POST https://api.planadoapp.com/api/v1/jobs.json
RequestJob with siteCustom fieldsContactsAttachment
Headers
Content-Type: application/json
Message body
{
  "site_id": 11690603001,
  "external_id": "some_external_id"
}
Response201404
Headers
Content-Type: application/json
Message body
{
  "job_id": 25302001,
  "status": "success"
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "job_id": {
      "type": "number"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}
Headers
Content-Type: application/json
Message body
{
  "template_id": 957001,
  "client_id": 427001,
  "assignee_subject_id": 14001,
  "custom_fields": [
    {
      "name": "Your Field Name",
      "value": "Field value"
    }
  ]
}
Response201404
Headers
Content-Type: application/json
Message body
{
  "job_id": 25302001,
  "status": "success"
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "job_id": {
      "type": "number"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}
Headers
Content-Type: application/json
Message body
{
  "contacts": [
    {
      "type": "phone",
      "name": "John",
      "value": "+7-458-543-54-56"
    },
    {
      "type": "phone",
      "name": "Helga",
      "value": "655-432"
    }
  ]
}
Response201404
Headers
Content-Type: application/json
Message body
{
  "job_id": 25302001,
  "status": "success"
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "job_id": {
      "type": "number"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}
Headers
Content-Type: application/json
Message body
{
  "template_id": 123456,
  "custom_fields": [
    {
      "name": "Custom field name",
      "value": {
        "name": "file.txt",
        "base64_content": "SGVsbG8gd29ybGQhCg=="
      }
    }
  ]
}
Response201404
Headers
Content-Type: application/json
Message body
{
  "job_id": 25302001,
  "status": "success"
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "job_id": {
      "type": "number"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

Add a job
POST/jobs.json

Pass template_id to use template with the new job.

Pass site_id OR client_id to link the job to a site or a client respectively.

You can fill custom fields using API. If you want to attach a file, custom field value MUST be a JSON object with two fields:

  • name — File name

  • base64_content — Base64-encoded file content


GET https://api.planadoapp.com/api/v1/jobs/job_id.json
Response200404
Headers
Content-Type: application/json
Message body
{
    "job": {
      "job_id": 121001,
      "external_id": '303dj3',
      "serial_no": 3,
      "template_id": null,
      "type_id": 56001,
      "status": "scheduled",
      "description": "Fix AC & charge them $200",
      "client_id": null,
      "address": {
        "formatted": "Nowhere road, KS",
        "entrance_no": null,
        "apartment": null,
        "floor": null,
        "description": null,
        "geolocation": {
          "longitude": 37.216025,
          "latitude": 55.999757
        }
      },
      "scheduled_at": "2015-08-24T13:00:00",
      "scheduled_duration_min": 60,
      "assignee_subject_id": null,
      "possible_resolutions": [
        {
          "resolution_id": 58001,
          "name": "Successful",
          "successful": true,
          "comment_required": false
        },
        {
          "resolution_id": 59001,
          "name": "Unsuccessful",
          "successful": false,
          "comment_required": false
        }
      ],
      "first_activity_at": null,
      "en_route_at": null,
      "started_at": null,
      "suspended_at": null,
      "finished_at": null,
      "en_route_min": null,
      "suspension_time_min": null,
      "actual_time_min": null,
      "custom_fields": [],
      "cell_phone": null
    },
    "url": "https://your-subdomain.planadoapp.com/jobs/121001"
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "job": {
      "type": "object",
      "properties": {
        "job_id": {
          "type": "number"
        },
        "serial_no": {
          "type": "number"
        },
        "template_id": {
          "type": [
            "number",
            "null"
          ]
        },
        "type_id": {
          "type": [
            "number",
            "null"
          ]
        },
        "assignee_subject_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": "string"
        },
        "client_id": {
          "type": [
            "number",
            "null"
          ]
        },
        "site_id": {
          "type": [
            "number",
            "null"
          ]
        },
        "external_id: `my_external_id`": {
          "type": [
            "string",
            "null"
          ]
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "address": {
          "type": "object",
          "properties": {
            "description": {
              "type": [
                "string",
                "null"
              ]
            },
            "apartment": {
              "type": [
                "string",
                "null"
              ]
            },
            "entrance_no": {
              "type": [
                "string",
                "null"
              ]
            },
            "floor": {
              "type": "string"
            },
            "formatted": {
              "type": [
                "string",
                "null"
              ]
            },
            "geolocation": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "latitude": {
                  "type": "number"
                },
                "longitude": {
                  "type": "number"
                }
              },
              "required": [
                "latitude",
                "longitude"
              ]
            }
          }
        },
        "scheduled_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "scheduled_duration_min": {
          "type": "number"
        },
        "possible_resolutions": {
          "type": "array"
        },
        "first_activity_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "en_route_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "started_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "suspended_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "finished_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "en_route_min": {
          "type": "number"
        },
        "suspension_time_min": {
          "type": "number"
        },
        "actual_time_min": {
          "type": "number"
        },
        "cell_phone": {
          "type": "string"
        },
        "started_location": {
          "type": "object",
          "properties": {
            "latitude": {
              "type": "number"
            },
            "longitude": {
              "type": "number"
            }
          },
          "required": [
            "latitude",
            "longitude"
          ]
        },
        "en_route_location": {
          "type": "object",
          "properties": {
            "latitude": {
              "type": "number"
            },
            "longitude": {
              "type": "number"
            }
          },
          "required": [
            "latitude",
            "longitude"
          ]
        },
        "suspended_location": {
          "type": "object",
          "properties": {
            "latitude": {
              "type": "number"
            },
            "longitude": {
              "type": "number"
            }
          },
          "required": [
            "latitude",
            "longitude"
          ]
        },
        "finished_location": {
          "type": "object",
          "properties": {
            "latitude": {
              "type": "number"
            },
            "longitude": {
              "type": "number"
            }
          },
          "required": [
            "latitude",
            "longitude"
          ]
        },
        "custom_fields": {
          "type": "array"
        }
      }
    },
    "url": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

Get job info
GET/jobs/{job_id}.json

You can get job info using job_id or external_id.

URI Parameters
job_id
string

Job ID or External ID


PATCH https://api.planadoapp.com/api/v1/jobs/job_id.json
Request
Headers
Content-Type: application/json
Message body
{
  "custom_fields": [
    {
      "name": "Your Field Name",
      "value": "New Value"
    }
  ]
}
Response200404
Headers
Content-Type: application/json
Message body
{
  "status": "success"
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

Edit job
PATCH/jobs/{job_id}.json

If you need to update your job’s custom fields, pass a custom_fields array in the following format:

  • name — custom field name

  • value — updated value

URI Parameters
job_id
string

Job ID or External ID


DELETE https://api.planadoapp.com/api/v1/jobs/job_id.json
Response200404
Headers
Content-Type: application/json
Message body
{
  "status": "success"
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

Remove a job
DELETE/jobs/{job_id}.json

You can remove a job using the job_id or external_id.

URI Parameters
job_id
string

Job ID or External ID


GET https://api.planadoapp.com/api/v1/clients.json?page=4
Response200404
Headers
Content-Type: application/json
Message body
{
    "clients": [
        {
            "client_id": 13668001,
            "organization": false,
            "email": null,
            "external_id": null,
            "first_name": "Albert",
            "last_name": "Einstein",
            "middle_name": null,
            "name": "Albert Einstein",
            "site_address": {
                "description": null,
                "entrance_no": null,
                "apartment": null,
                "floor": null,
                "formatted": "112, Mercer Street, Princeton, Mercer County, New Jersey",
                "geolocation": {
                  "longitude": -74.666268,
                  "latitude": 40.343109
                }
            },
            "cell_phone": "79113456465",
            "work_phone": null
        },
        ...
    ],
    "view_url": "https://your-subdomain.planadoapp.com/clients",
    "page": 1,
    "total_pages": 2
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "page": {
      "type": "number"
    },
    "total_pages": {
      "type": "number"
    },
    "view_url": {
      "type": "string"
    },
    "clients": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

List clients
GET/clients.json{?page}

Get a paginated list of clients, 20 per page.

URI Parameters
page
number

POST https://api.planadoapp.com/api/v1/clients.json
RequestOrganizationIndividual
Headers
Content-Type: application/json
Message body
{
  "external_id": "0dcc5ca36e1e580f",
  "organization": true,
  "organization_name": "Reichert-Rau",
  "contact_name": "Stephen Padberg",
  "contacts": [
    {
      "type": "phone",
      "name": "Estell Morissette Sr.",
      "value": "+79443146459",
      "value_normalized": "+79443146459"
    },
    {
      "type": "phone",
      "name": "Franco O'Reilly",
      "value": "+79294136091",
      "value_normalized": "+79294136091"
    }
  ]
  "email": "mariah@romaguerafunk.name"
}
Response201404422
Headers
Content-Type: application/json
Message body
{
  "client_id": 23351001,
  "status": "success"
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}
Headers
Content-Type: application/json
Message body
{
  "status": "unprocessable_entity",
  "errors": {
    "individual_name": [
      "provide first_name"
    ]
  }
}
Headers
Content-Type: application/json
Message body
{
  "contacts": [
    {
      "type": "phone",
      "name": "Estell Morissette Sr.",
      "value": "+79443146459",
      "value_normalized": "+79443146459"
    },
    {
      "type": "phone",
      "name": "Franco O'Reilly",
      "value": "+79294136091",
      "value_normalized": "+79294136091"
    },
    {
      "type": "phone",
      "name": "Carroll Corwin",
      "value": "+79257311098",
      "value_normalized": "+79257311098"
    }
  ],
  "external_id": "f19ee7145a020479",
  "organization": false,
  "first_name": "Grayson",
  "last_name": "Wuckert",
  "email": "everardo_smitham@emmerichberge.org",
  "site_address": {
    "formatted": "Moscow, Kremlin",
    "description": "Tower next to Mausoleum",
    "entrance_no": "1",
    "apartment": "",
    "floor": "7"
  }
}
Response201404422
Headers
Content-Type: application/json
Message body
{
  "client_id": 23351001,
  "status": "success"
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}
Headers
Content-Type: application/json
Message body
{
  "status": "unprocessable_entity",
  "errors": {
    "individual_name": [
      "provide first_name"
    ]
  }
}

Add a client
POST/clients.json

To add an organization:

  • organization MUST be set to true

  • organization_name MUST be set

  • first_name, middle_name and last_name MUST be absent

To add an individual

  • organization MUST be set to false

  • first_name MUST be set

  • middle_name and last_name MIGHT be set

  • organization_name MUST be absent


GET https://api.planadoapp.com/api/v1/clients/client_id.json
Response200404
Headers
Content-Type: application/json
Message body
{
  "client": {
    "client_id": 23351001,
    "organization": false,
    "email": "albert_einstein@gmail.com",
    "external_id": "f370396",
    "first_name": "Albert",
    "last_name": "Einstein",
    "middle_name": null,
    "name": "Albert Einstein",
    "site_address": {
      "description": null,
      "entrance_no": null,
      "apartment": null,
      "floor": null,
      "formatted": "112, Mercer Street, Princeton, Mercer County, New Jersey",
      "geolocation": {
        "longitude": -74.666268,
        "latitude": 40.343109
      }
    },
    "work_phone": null,
    "cell_phone": null
  }
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "client": {
      "type": "object",
      "properties": {
        "client_id": {
          "type": "number"
        },
        "external_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "organization": {
          "type": "boolean"
        },
        "name": {
          "type": "string"
        },
        "first_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "last_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "middle_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "email": {
          "type": [
            "string",
            "null"
          ]
        },
        "site_address": {
          "type": "object",
          "properties": {
            "description": {
              "type": [
                "string",
                "null"
              ]
            },
            "apartment": {
              "type": [
                "string",
                "null"
              ]
            },
            "entrance_no": {
              "type": [
                "string",
                "null"
              ]
            },
            "floor": {
              "type": "string"
            },
            "formatted": {
              "type": [
                "string",
                "null"
              ]
            },
            "geolocation": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "latitude": {
                  "type": "number"
                },
                "longitude": {
                  "type": "number"
                }
              },
              "required": [
                "latitude",
                "longitude"
              ]
            }
          }
        },
        "cell_phone": {
          "type": [
            "string",
            "null"
          ]
        },
        "contacts": {
          "type": "array"
        }
      }
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

Get client info
GET/clients/{client_id}.json

You can get client info using client_id or external_id.

URI Parameters
client_id
string

ID or Remote ID


PATCH https://api.planadoapp.com/api/v1/clients/client_id.json
Request
Headers
Content-Type: application/json
Message body
{
  "contacts": [
    {
      "type": "phone",
      "name": "Amara Gibson Sr.",
      "value": "+79410804477",
      "value_normalized": "+79410804477"
    },
    {
      "type": "phone",
      "name": "Daisha Cummerata",
      "value": "+79182228179",
      "value_normalized": "+79182228179"
    },
    {
      "type": "phone",
      "name": "Ms. Oleta Stamm",
      "value": "+79300610821",
      "value_normalized": "+79300610821"
    }
  ],
  "email": "samara.heel@schowaltertorphy.biz"
}
Response200404422
Headers
Content-Type: application/json
Message body
{
  "client_id": 23351001,
  "status": "success"
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}
Headers
Content-Type: application/json
Message body
{
  "status": "unprocessable_entity",
  "errors": {
    "email": [
      "size cannot be greater than 200"
    ],
    "contact_name": [
      "size cannot be greater than 200"
    ],
    "site_address": {
      "formatted": [
        "size cannot be greater than 5000"
      ],
      "entrance_no": [
        "size cannot be greater than 50"
      ],
      "apartment": [
        "size cannot be greater than 50"
      ],
      "floor": [
        "size cannot be greater than 50"
      ],
      "description": [
        "size cannot be greater than 500"
      ]
    }
  }
}

Edit client
PATCH/clients/{client_id}.json

Pass a JSON object containing fields along with their new values.

URI Parameters
client_id
string

ID or Remote ID


DELETE https://api.planadoapp.com/api/v1/clients/client_id.json
Response200404
Headers
Content-Type: application/json
Message body
{
  "status": "success"
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

Remove a client
DELETE/clients/{client_id}.json

You can remove a client using their client_id or external_id.

URI Parameters
client_id
string

ID or Remote ID


GET https://api.planadoapp.com/api/v1/sites.json?page=4
Response200404
Headers
Content-Type: application/json
Message body
{
  "page": 4,
  "sites": [
    {
      "address": {
        "apartment": null,
        "description": null,
        "entrance_no": null,
        "floor": null,
        "formatted": null,
        "geolocation": null
      },
      "client_id": null,
      "contacts": [
        {
          "name": "Jane",
          "type": "phone",
          "value": ""
        },
        {
          "name": "John",
          "type": "phone",
          "value": ""
        }
      ],
      "description": null,
      "external_id": null,
      "site_id": 11690603001,
      "uuid": "1c0a74c0-a64c-4028-b43f-5543e5b50d24",
      "name": "Pole in the middle of nowhere"
    },
    {
      "address": {
        "apartment": null,
        "description": null,
        "entrance_no": null,
        "floor": null,
        "formatted": "Willy Wonka's factory",
        "geolocation": null
      },
      "client_id": null,
      "contacts": [
        {
          "name": "Jake",
          "type": "phone",
          "value": ""
        },
        {
          "name": "Ryan",
          "type": "phone",
          "value": ""
        }
      ],
      "description": null,
      "external_id": null,
      "site_id": 11690634001,
      "uuid": "b7290dd4-5d3f-46f4-998b-4f482e1d8ed8",
      "name": "Bunker #3"
    }
  ]
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "page": {
      "type": "number"
    },
    "sites": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

List sites
GET/sites.json{?page}

Get a paginated list of sites, 20 per page.

URI Parameters
page
number

POST https://api.planadoapp.com/api/v1/sites.json
RequestContactsOrganiaztion
Headers
Content-Type: application/json
Message body
{
  "name": "Wonka's plant",
  "contacts": [
    {
      "type": "phone",
      "name": "Вася",
      "value": "8-80-05-553-535"
    },
    {
      "type": "phone",
      "name": "Ваня",
      "value": "+7(909)943-43-43"
    }
  ],
  "address": {
    "formatted": "Somewhere in a town",
    "geolocation": {
      "latitude": 12.3,
      "longitude": 13.4
    }
  },
  "external_id": "my_external_id"
}
Response201404422
Headers
Content-Type: application/json
Location: /sites/2151231231
Message body
{
  "site_id": 2151231231,
  "status": "success"
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}
Headers
Content-Type: application/json
Message body
{
  "status": "unprocessable_entity",
  "errors": {
    "external_id": [
      "is used by another entity"
    ]
  }
}
Headers
Content-Type: application/json
Message body
{
  "name": "Wonka's Incorporated",
  "client_id": 11512312001
}
Response201404422
Headers
Content-Type: application/json
Location: /sites/2151231231
Message body
{
  "site_id": 2151231231,
  "status": "success"
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}
Headers
Content-Type: application/json
Message body
{
  "status": "unprocessable_entity",
  "errors": {
    "external_id": [
      "is used by another entity"
    ]
  }
}

Add a site
POST/sites.json

To assign the site to an organization, fill client_id with client ID or external ID.


GET https://api.planadoapp.com/api/v1/sites/site_id.json
Response200404
Headers
Content-Type: application/json
Message body
{
  "site": {
    "site_id": 12695554433,
    "external_id": "4482d68cdf",
    "uuid": "d70399c6-5059-4bd4-a7c0-8f5fda260d7e",
    "name": "Internal Identity Analyst",
    "client_id": 12695553433,
    "description": "Ut tempore aut quas earum et omnis nobis. Quaerat perferendis id id culpa omnis et ut. Numquam accusamus aliquam.",
    "contacts": [
      {
        "name": "Mr. Sigrid Jast",
        "value": "+79229558424",
        "type": "phone"
      },
      {
        "name": "Ms. Federico Goldner",
        "value": "+79299687539",
        "type": "phone"
      },
      {
        "name": "Myrtle Zboncak",
        "value": "+79176339173",
        "type": "phone"
      }
    ],
    "address": {
      "formatted": "Sit cum dolorem omnis rerum.",
      "entrance_no": "6",
      "apartment": "35",
      "floor": "4",
      "description": "Rusted door",
      "geolocation": {
        "longitude": 68.6096071,
        "latitude": 39.2106464
      }
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

Get site info
GET/sites/{site_id}.json

You can get site info using client_id or external_id.

URI Parameters
site_id
string

ID or external ID


PATCH https://api.planadoapp.com/api/v1/sites/site_id.json
RequestUpdated fieldsAssign to organization
Headers
Content-Type: application/json
Message body
{
  "name": "Dynamic Interactions Producer",
  "description": "Eum earum qui. Assumenda commodi tempore qui qui molestias. Quis laudantium nesciunt veniam tempore voluptates sunt vel.",
  "address_description": "Ullam adipisci iusto. Libero beatae similique id dolor soluta. Rerum omnis distinctio dolorem. Voluptas non voluptate officiis dolor et ipsum veniam. Sed assumenda nam nihil enim quia ea tempore.",
  "address": {
    "formatted": "Eum qui sint vero illo cumque.",
    "geolocation": {
      "latitude": 77.2106464,
      "longitude": 2.6096071
    }
  },
  "floor": "7",
  "apartment": "16",
  "entrance_no": "7",
  "contacts": [
    {
      "type": "phone",
      "value": "377.775.5529 x2035",
      "name": "Monserrat Pagac"
    }
  ]
}
Response200404
Headers
Content-Type: application/json
Message body
{
  "status": "success",
  "site_id": 12695444433
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}
Headers
Content-Type: application/json
Message body
{
  "client_id": "a0327b8057a4d5c7"
}
Response200404
Headers
Content-Type: application/json
Message body
{
  "status": "success",
  "site_id": 12695444433
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

Edit site
PATCH/sites/{site_id}.json

You can partially update site data. Pass a field along with new value and it will be updated.

URI Parameters
site_id
string

ID or external ID


DELETE https://api.planadoapp.com/api/v1/sites/site_id.json
Response200404
Headers
Content-Type: application/json
Message body
{
  "status": "success"
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

Remove a site
DELETE/sites/{site_id}.json

You can remove a site using the site_id or external_id.

URI Parameters
site_id
string

ID or external ID


GET https://api.planadoapp.com/api/v1/templates.json?page=4
Response200404
Headers
Content-Type: application/json
Message body
{
  "page": 1,
  "templates": [
    {
      "assignee_subject_id": null,
      "cell_phone": null,
      "client_id": null,
      "description": "An unexpected or a dangerous situation",
      "name": "Emergency",
      "scheduled_at": null,
      "scheduled_duration_min": 120,
      "template_id": 1613619701,
      "type_id": 3412474701
    },
    {
      "assignee_subject_id": null,
      "cell_phone": null,
      "client_id": null,
      "description": "Damage evaluation or equipment inspection",
      "name": "Diagnostics",
      "scheduled_at": null,
      "scheduled_duration_min": 120,
      "template_id": 1613624701,
      "type_id": 3412475701
    },
    {
      "assignee_subject_id": null,
      "cell_phone": null,
      "client_id": null,
      "description": "Fixing the previous worker’s mistakes on client's complaint",
      "name": "Tweaking",
      "scheduled_at": null,
      "scheduled_duration_min": 120,
      "template_id": 1613637701,
      "type_id": 1613498701
    }
  ],
  "total_pages": 1
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "page": {
      "type": "number"
    },
    "templates": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

List templates
GET/templates.json{?page}

Get a paginated list of templates, 20 per page.

URI Parameters
page
number

GET https://api.planadoapp.com/api/v1/templates/template_id.json
Response200404
Headers
Content-Type: application/json
Message body
{
  "template": {
    "address": null,
    "assignee_subject_id": null,
    "cell_phone": null,
    "checklist_items": [
      {
        "checked_at": null,
        "field_id": null,
        "item_id": 1613645701,
        "name": "Apologize"
      },
      {
        "checked_at": null,
        "field_id": 1613639701,
        "item_id": 3444120701,
        "name": "Take a photo of an issue"
      },
      {
        "checked_at": null,
        "field_id": 1613643701,
        "item_id": 3444121701,
        "name": "Take a photo of a fixed issue"
      },
      {
        "checked_at": null,
        "field_id": 3443988701,
        "item_id": 1613644701,
        "name": "Sign a Certificate of Satisfaction"
      }
    ],
    "client_id": null,
    "custom_fields": [
      {
        "data_type": "attachment",
        "field_id": 1613639701,
        "field_type": "image",
        "name": "Photo of the issue",
        "read_only": false,
        "required": false,
        "value": null
      },
      {
        "data_type": "attachment",
        "field_id": 1613643701,
        "field_type": "image",
        "name": "Fixed issue photo",
        "read_only": false,
        "required": false,
        "value": null
      },
      {
        "data_type": "attachment",
        "field_id": 3443988701,
        "field_type": "image",
        "name": "Certificate of Satisfaction",
        "read_only": false,
        "required": false,
        "value": null
      },
      {
        "data_type": "attachment",
        "field_id": 1613641701,
        "field_type": "image",
        "name": "Claimed issue",
        "read_only": false,
        "required": false,
        "value": null
      }
    ],
    "description": "Fixing the previous worker’s mistakes on client's complaint",
    "name": "Tweaking",
    "possible_resolutions": [
      {
        "comment_required": false,
        "name": "Completed",
        "resolution_id": 1613500701,
        "successful": true
      },
      {
        "comment_required": false,
        "name": "Not completed",
        "resolution_id": 1613601701,
        "successful": false
      }
    ],
    "scheduled_at": null,
    "scheduled_duration_min": 120,
    "template_id": 1613637701,
    "type_id": 1613498701
  }
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "template": {
      "type": "object",
      "properties": {
        "template_id": {
          "type": "number"
        },
        "name": {
          "type": "string"
        },
        "type_id": {
          "type": "number"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "scheduled_duration_min": {
          "type": "number"
        },
        "assignee_subject_id": {
          "type": [
            "number",
            "null"
          ]
        },
        "possible_resolutions": {
          "type": "array"
        },
        "custom_fields": {
          "type": "array"
        }
      }
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

Get template info
GET/templates/{template_id}.json

You can get detailed template info using its ID (template_id).

URI Parameters
template_id
string

Template ID


GET https://api.planadoapp.com/api/v1/job_types.json?page=4
Response200404
Headers
Content-Type: application/json
Message body
{
  "job_types": [
    {
      "type_id": 56001,
      "code": "default"
    },
    {
      "type_id": 124001,
      "code": "Delivery"
    }
  ],
  "page": 1,
  "total_pages": 1
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "job_types": {
      "type": "array"
    },
    "page": {
      "type": "number"
    },
    "total_pages": {
      "type": "number"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

List job types
GET/job_types.json{?page}

This action returns a paginated list, 100 elements on each page.

URI Parameters
page
number

GET https://api.planadoapp.com/api/v1/resolutions.json?page=4
Response200404
Headers
Content-Type: application/json
Message body
{
    "resolutions": [
        {
            "resolution_id": 58011,
            "name": "Finished",
            "successful": true,
            "comment_required": false
        },
        ...],
    "page": 1,
    "total_pages": 1
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "resolutions": {
      "type": "array"
    },
    "page": {
      "type": "number"
    },
    "total_pages": {
      "type": "number"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

List resolutions
GET/resolutions.json{?page}

Get a paginated list of resolutions, 100 per page.

URI Parameters
page
number

GET https://api.planadoapp.com/api/v1/locations.json?page=4
Response200404
Headers
Content-Type: application/json
Message body
{
    "locations": [
        {
            "location_id": 12532101,
            "worker_id": 427001,
            "worker_email": "foo@example.com",
            "geolocation": {
              "longitude": 37.16078166666667,
              "latitude": 55.981625
            },
            "source": "gps",
            "battery_level": 90.0,
            "actual_at": "2014-10-22T20:02:12"
        },
        ...
    ]
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "locations": {
      "type": "object",
      "properties": {
        "location_id": {
          "type": "number"
        },
        "worker_id": {
          "type": "number"
        },
        "worker_email": {
          "type": "string"
        },
        "geolocation": {
          "type": "object",
          "properties": {
            "latitude": {
              "type": "number"
            },
            "longitude": {
              "type": "number"
            }
          },
          "required": [
            "latitude",
            "longitude"
          ]
        },
        "source": {
          "type": "string",
          "enum": [
            "gps",
            "network",
            "fused"
          ]
        },
        "battery_level": {
          "type": "number"
        },
        "actual_at": {
          "type": "string"
        }
      }
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

List locations
GET/locations.json{?page}

Get a paginated list of locations, 100 per page.

URI Parameters
page
number

GET https://api.planadoapp.com/api/v1/users.json?page=4
Response200404
Headers
Content-Type: application/json
Message body
{
  "status": "success",
  "users": [
    {
      "email": "john+20@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "mobile_phone": "+18002224657",
      "owner": true,
      "permissions": {
        "mobile_complete_jobs": true,
        "mobile_login": true,
        "web_admin": true,
        "web_login": true
      },
      "user_id": 1001,
      "uses_license": true
    },
    {
      "email": "foo@example.ru",
      "first_name": "George",
      "last_name": "Walter",
      "mobile_phone": "+19043217895",
      "owner": false,
      "permissions": {
        "mobile_complete_jobs": true,
        "mobile_login": true,
        "web_admin": true,
        "web_login": true
      },
      "user_id": 10001,
      "uses_license": true
    }
  ]
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "users": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

List users
GET/users.json{?page}

Get a paginated list of users, 20 per page.

URI Parameters
page
number

POST https://api.planadoapp.com/api/v1/users.json
Request
Headers
Content-Type: application/json
Message body
{
  "first_name": "Nat",
  "last_name": "Labadie",
  "email": "guillermo@deckow.biz",
  "mobile_phone": "(115) 374-5355 x66843",
  "password": "c19a7c9b3733e21f",
  "permissions": {
    "web": {
      "jobs": [
        "write"
      ],
      "schedule": [
        "read"
      ],
      "clients": [
        "write",
        "read"
      ],
      "map": [
        "read"
      ]
    },
    "mobile": [
      "complete_jobs"
    ]
  }
}
Response201404
Headers
Content-Type: application/json
Message body
{
  "status": "success",
  "user_id": 10001
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "user_id": {
      "type": "number"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

Add a user
POST/users.json

You can customize user access via permissions key.

There are two types of permissions: web and mobile.

Web permissions are a JSON object with possible keys:

  • jobs

  • schedule

  • clients

  • map

  • teams

If you omit a key, the user will not have access to the feature.

Each feature can have a write or a read permission.

What you send What it means
"jobs": [] Read-only access to jobs
"jobs": ["read"] Read-only access to jobs
"jobs": ["read", "write"] Read and write access to jobs
"jobs": ["write"] Read and write access to jobs

Mobile permissions are simple:

What you send What it means
"mobile": [] User can log into mobile app
"mobile": ["complete_jobs"] User can log into mobile app and complete jobs

Please note that write access and ability to complete jobs are paid features that require a license.


GET https://api.planadoapp.com/api/v1/users/user_id.json
Response200404
Headers
Content-Type: application/json
Message body
{
  "email": "foo@example.ru",
  "first_name": "John",
  "last_name": "Dane",
  "mobile_phone": "+19043217895",
  "owner": false,
  "permissions": {
    "mobile_complete_jobs": true,
    "mobile_login": true,
    "web_admin": true,
    "web_login": true
  },
  "user_id": 10001,
  "uses_license": true
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "user_id": {
      "type": "number"
    },
    "first_name": {
      "type": "string"
    },
    "last_name": {
      "type": "string"
    },
    "permissions": {
      "type": "object",
      "properties": {
        "web_login": {
          "type": "boolean"
        },
        "web_admin": {
          "type": "boolean"
        },
        "mobile_login": {
          "type": "boolean"
        },
        "mobile_complete_jobs": {
          "type": "boolean"
        }
      }
    },
    "email": {
      "type": "string"
    },
    "uses_license": {
      "type": "boolean"
    },
    "owner": {
      "type": "boolean"
    },
    "mobile_phone": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

Get user info
GET/users/{user_id}.json

You can get user info via their user_id or email.

URI Parameters
user_id
string

User ID or email


GET https://api.planadoapp.com/api/v1/teams.json?page=4
Response200404
Headers
Content-Type: application/json
Message body
{
    teams: [
            "foreman": {
              "email": "john@beatles.com",
              "name": "John Lennon",
              "worker_id": 51001
            },
            "name": "The Beatles",
            "team_id": 79001,
            "workers": [
              {
                "email": "ringo@beatles.com",
                "name": "Ringo Starr",
                "worker_id": 63001
              }
              ...
            ]
        },
        {
            "foreman": null,
            "name": "Quarrymen",
            "team_id": 81001,
            "workers": []
        }
    ]
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "teams": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

List teams
GET/teams.json{?page}

Get a paginated list of teams, 20 per page.

URI Parameters
page
number

GET https://api.planadoapp.com/api/v1/teams/team_id.json
Response200404
Headers
Content-Type: application/json
Message body
{
    "foreman": {
        "email": "john@beatles.com",
        "name": "John Lennon",
        "worker_id": 51001
    },
    "name": "The Beatles",
    "team_id": 79001,
    "workers": [
        {
            "email": "ringo@beatles.com",
            "name": "Ringo Starr",
            "worker_id": 63001
        }
        ...
    ]
}
Schema
CloseOpen
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "team_id": {
      "type": "number"
    },
    "name": {
      "type": "string"
    },
    "foreman": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "worker_id": {
          "type": "number"
        },
        "name": {
          "type": "string"
        },
        "email": {
          "type": "string"
        }
      }
    },
    "workers": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json
Message body
{
  "status": "not found"
}

Get team info
GET/teams/{team_id}.json

You can get team info using its ID (team_id).

URI Parameters
team_id
string

Team ID


Generated by aglio on 27 Mar 2018