Planado API

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

API is also formally described using the OpenAPI standard. There’s an interactive site for making API requests and a number of generated clients for various programming languages.

Making requests

REST API is available via HTTPS at api.planadoapp.com. All requests to the API must contain a key in the Authorization header. Get a key by visiting Settings / Integrations / API. Press the refresh button 🔄 to generate a new key if the value is empty.

Value of the authorization header must contain a type of authentication. Planado API uses the "Bearer" type. For example, a key value of 817cc478 must be passed as Bearer 817cc478.

All requests and responses are done in the JSON format.

Add a job using curl. Here api-key is the API key.

$ curl -H "Authorization: Bearer api-key" \
       --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 "Authorization: Bearer api-key" 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 90 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!