Every API request needs an OAuth2 access token in the Authorization header. Use the request below to generate one from your application credentials.

You can find your Client ID and Client Secret in your Plutio app under Settings > API.

The response contains an accessTokenExpiresAt field that tells you when the token expires. When it does, just call this endpoint again to get a new one. Keep your token safe and do not expose it in client-side or public code.

Everyone in your workspace is a person record, and the role decides what they are: a client, or one of your own team. This is usually the first call an integration makes, because invoices, proposals and projects all need someone to point at.

Two details are easy to get wrong. The name is an object with first and last inside it, not a plain firstName field. And an email address goes in contactEmails as address, not email, because a person can have several. The response includes the new _id, which you will need for the invoice example below.

If you bill a business rather than an individual, create a company and attach the people to it. The name of the company goes in title, not name.

The people field takes a list of objects, each holding the _id of a person you created earlier. A plain list of ID strings is rejected with People must be of type Object.

A project only needs a name. Plutio fills in the rest: it gives the project a default status, and it creates a first task board so the project is ready to hold tasks straight away.

Keep the _id from the response. You need it to find the task board in the next example.

Tasks live on a task board inside a project, so you need the board first. Ask for the boards that belong to your project with GET /task-boards?projectId=YOUR_PROJECT_ID and take the _id of the one you want. A new project has one board waiting, called New task board.

Then create the task with that taskBoardId. The task title goes in title. New tasks start with a status of incomplete; the other values Plutio uses are completed and overdue.

This is the one most developers assume is impossible, so it is worth being clear: you can write the full text of a contract or a proposal through the API, and it shows up in the document exactly as if you had typed it in Plutio yourself.

The document itself does not hold its words. Create the contract first with POST /contracts, keep its _id, then add a content block that points back at it. Your HTML goes in textHTML. Plutio works out the plain-text version for you, adds the block to the document, and places it in the layout, so there is nothing else to wire up.

Trying to pass the text inline when you create the contract, as "blocks": [{ "textHTML": "..." }], fails with Blocks must be of type String. That is because a contract keeps a list of block IDs, and the block has to exist first.

The same call works for proposals and invoices. Use entityType of proposal or invoice with the matching ID.

To see what a document says, ask for its blocks with GET /blocks?entityType=contract&entityId=YOUR_CONTRACT_ID. Both parts are required. Passing only entityId returns ID or entityType & entityID is required.

To change a block, call PUT /blocks and put the block _id in the body along with the new textHTML. Anything you leave out stays as it was. This is how you rewrite a clause, correct a typo, or fill in a template you copied earlier.

An invoice needs to know who it is for. The client field is an object holding the _id of a person or company, and an entityType that says which of the two it is. Writing entityId instead of _id returns client.entityId is not allowed by the schema.

If you leave out the due date, Plutio applies the default from your invoice settings. The invoice starts as a draft, which means you can still change it and the client cannot pay it yet. Line items come next.

Line items are a block too, of type items, and the items themselves sit inside that block rather than being separate records. Each one needs a title, a quantity and an amount, which is the price of a single unit.

An invoice you create through the API has no items block until you add one, because it was not built from a template. Send the block once with all your items in it. Plutio works out each line total, the subtotal and the invoice total from what you send.

If the invoice already has an items block, for example because you created it from a template, use PUT /blocks with the block _id and a new items list instead of creating a second one.

This sends the same branded email your client would get if you pressed Send in Plutio, with the PDF attached and a link to pay. The invoice moves from draft to pending on its own, and Plutio records when it was sent.

Note the field name: this endpoint wants invoiceId, not _id. The to field is an object pointing at the person or company, in the same shape as the client field on the invoice. You can also pass cc, bcc, a subject and a message to override the defaults from your email settings.

A successful send answers with 200 and an empty body. To confirm it worked, read the invoice back and check that the status is now pending.

A time entry records who did the work, on which task, and for how long. The clock fields are startedAt and stoppedAt, and time is the length in seconds, so an hour and a half is 5400.

The task and the project have to match. If you pass a projectId that is not the project the task actually belongs to, the request is refused with task_project_mismatch. The safest approach is to read the task first and use its own projectId.

There are two ways to narrow down a list, and they work together.

For a straight match, put the field in the URL: GET /people?role=client, or GET /tasks?projectId=abc123. Every field on the record can be used this way.

For anything cleverer, use q with a MongoDB-style query as JSON. This is how you do text search, ranges and lists of values. To find every client whose first name starts with Tay, send q={"name.first":{"$regex":"^Tay","$options":"i"}}. Remember to URL-encode it.

Sorting has a format of its own, and it is the one that catches everyone out. Add _asc or _desc to the field name: sort=createdAt_desc. Anything else, including the usual sort={"createdAt":-1}, comes back as Invalid sort. Most resources allow sorting on createdAt and updatedAt.

Paging uses limit and skip. Ask for 50 at a time and raise skip by 50 each round until you get fewer than you asked for. Keep an eye on the rate limit of 1,500 requests an hour while you do it.

Most resources take a bulk call, which saves you a request per record and keeps you well inside the rate limit. The IDs go in _ids, and every other field you send is applied to all of them. So marking three tasks done is one call with { "_ids": [...], "status": "completed" }.

Watch the field name here. It is _ids with an underscore, and sending ids returns ids is not allowed by the schema. Status values must be real ones too: tasks use incomplete, completed and overdue.

Archiving works the same way through POST /tasks/bulk/archive, which takes _ids and isArchived. Set isArchived to false to bring things back. The reply is a list telling you what happened to each record, so you can spot any that did not go through.

Required fields:

Required fields:

Required fields:

Required fields:

Required fields:

Required fields: