Planado API

Planado provides a rich REST API for almost all entities. In addition to that, Planado can immediately notify your system when changes in jobs, clients, or sites occur. Notifications are reliable; if your system cannot is unreachable or responds with errors, Planado makes a few more attempts with increasing interval.

Making requests

REST API is available via HTTPS at api.planadoapp.com. All requests to the API must contain a key in the X-Planado-API-Key header. You can get a key by visiting Settings / Integrations / API. Press the refresh button 🔄 to generate a new key if the value is empty.

All requests and responses are done in the JSON format.

Add a job using curl. Here XXX is your API key.
$ curl -H "X-Planado-API-Key:XXX" \
       --data "{\"description\": \"New job posted via API\"}" \
       https://api.planadoapp.com/v2/jobs
{"job_uuid":"8070f98d-b3f6-4cc8-b7c4-54b6709cd98b"}
Get job info and pretty print results with jq
$ curl -H "X-Planado-API-Key:XXX" https://api.planadoapp.com/v2/jobs/8070f98d-b3f6-4cc8-b7c4-54b6709cd98b | jq
{
  "job": {
    "uuid": "137ea8b4-a616-6c80-40fa-6600ec2e536c",
    "external_id": null,
    "serial_no": 22468,
    "status": "posted",
    "scheduled_at": null,
    "scheduled_duration_min": null,
    ...
  }
}

Response codes

The API acts according to the HTTP standard. Response codes between 200 and 299, inclusively, mean the request succeeded.

4xx codes are client errors. In this case, the response body contains details of the error.

5xx are internal errors of the server. You may want to try the request later or contact Planado support. We closely monitor such errors and usually quickly mitigate them.

Rate limiting

To guarantee reliable service, we limit the number of API calls to 60 per minute. The limitation is done using the Leaky Bucket algorithm. Note that this scheme is not equivalent to 1 request per second, occasional spikes in the number of requests are allowed.

Requests exceeding the limit will receive 429 Too Many Requests in response.

Bidirectional integration with webhooks

If configured, Planado can notify your server about updates in real-time. For example, if a job was started or finished, Planado sends an HTTP request with the details of the event. If your server couldn’t process the request, Planado retries the delivery 17 more times with increasing interval. The last attempt is made in about a week after the first.

Optional keys and null values

The API draws a clear distinction between keys missing in requests and null values. For example, if an update request doesn’t include some optional key, then its value won’t be changed. However, if the key is present, and the value is null, the API changes the stored value to null.

All request schemas described in the documentation mention what fields can be skipped and what values can be null.

Spot a typo?

Please contact us if you found a mistake in this documentation or want to clarify something. Thank you!