# The Kolinea API: open folders and publish requests from your tools

> One key per workspace, rights by area, webhooks and generated documentation: what the Kolinea API allows.

A quote leaves your management software, a client record sits in your CRM, an appointment lives in your calendar. Copying that information into each folder by hand takes time and lets mistakes in. The Kolinea API lets your tools do it for you: open a folder, publish a document request, read an answer, link a contact. Here is what it covers, how its rights are set, and how your tool is told when something changes.

## What can a tool do with the Kolinea API?

Whatever a person can do in the product can be done through the API, with the same care. Four main areas are open:

- **Folders**: list them, open them, read them, change their information.
- **Publications**: the requests, answers, documents and comments of the thread. A tool can publish a document request, read the client’s answer or fetch the document that came in.
- **The contacts directory**: read, create and update your contacts’ records.
- **The workspace’s settings** for folders: the workspace works the same whether it is driven by hand or by a tool.

The Kolinea core adds accounts, members, invitations, notifications, exports, the subscription and webhooks. Calls that create something (a folder, a publication) can be safely repeated: if your tool retries a call after a cut connection, Kolinea does not create the thing twice.

## How do you tie your folders to those of another piece of software?

Your management software has its own folder numbers, your CRM its own client identifiers. A folder or a contact can now carry the reference of the tool that created it, in a field made for it (`external_ref`). From one call to the next, your tool finds the folder or record that matches its own entry, without keeping a correspondence table of its own.

For a contact’s record, this works alongside the [Kolinea contacts directory](/en/features/contacts-directory): one record per person, shared by all their folders, which your CRM can keep up to date.

## Which rights do you give a key?

Access goes through a key that belongs to your workspace. You create it in the workspace settings, under Developers, and it is shown only once. For each area, you choose None, Read or Write. Rights can be edited afterwards without changing the key: the tool follows from its next call.

A key behaves like a service account, never like a person:

1. It belongs to one workspace and sees no folder from another workspace.
2. What it publishes in a thread carries the name you gave it, marked “Integration”. Your clients know the message comes from an application.
3. It never reads a confidential publication addressed to someone else.
4. It cannot delete the workspace, change the plan or create another key.

A key can have an expiry date, and you can delete it whenever you like: the tool that used it loses access at once. It also stops working when the member who created it leaves the workspace. For the details, the [API and integrations feature page](/en/features/api-and-integrations) describes each rule.

## How is your tool told when something changes?

Rather than polling the API in a loop, your tool can receive a webhook: you give an address in the workspace settings and choose the events to receive, for example an answer to a request or the arrival of a document. The message sent stays thin: it contains only identifiers. Your tool then reads the detail back with its key, within its rights, so no folder information travels in a message you do not control.

Each delivery is signed, failed deliveries are retried, and a delivery can be replayed from the settings, useful the day your tool was down.

## Where is the documentation?

The documentation is generated from the product itself, not written on the side. For each endpoint it shows the rights required, describes every field in French and in English and gives real response examples taken from a demonstration workspace. Since it follows the code, it cannot describe an older version of the API. The OpenAPI specification can also be downloaded, to generate a client or import it into an API testing tool.

## Where should you start?

Start small. Create a Read key on folders and try listing them from a test tool. Once reading goes as expected, switch the key to Write on the one area the tool needs, for example publications, and keep the others on None. If you do not code yourself, give the documentation to the person who looks after your tools: they will find everything needed to connect your management software.

Keys are created in the workspace settings, under Developers.