How the CALADESK API works
The platform already has a door for people: you log in, see the inbox, click buttons. An API is the same door but for programs — your ERP, your CRM, your website, your spreadsheet — and instead of a password it uses a credential.
Two ways for two systems to know
Pull · API
"Let me ask whenever I want."
Your system asks: give me the open tickets. CALADESK answers. You decide when to ask.
Push · Webhooks
"Tell me the moment it happens."
You give CALADESK an address of yours, and when something happens — a ticket comes in, a customer replies — it calls you instantly.
You need both. With only webhooks, a custom dashboard has to rebuild its state from the notices it received, and if it misses one it stays out of sync forever. The API lets it re-read the truth whenever it wants. With only the API, it finds out about everything late.
The three notices you can turn on from Settings → Outgoing notifications: ticket.creado, ticket.respondido (the customer replied) and ticket.resuelto. Each delivery is signed with a secret of yours, so you can check it really comes from here and no one slips you a fake one.
What it can do today
Three things. Not one more — on purpose.
| You can ask for | What it returns | Extra permission? |
|---|---|---|
| List tickets | The paginated list, with filters for status, priority and dates | No |
| View a ticket | The case with its whole conversation | No |
| Create a ticket | The new ticket, with its number | Yes |
You cannot modify or close a ticket from the outside. That is not an oversight: everything opened outward is surface you have to defend forever, and it gets opened when there is a concrete need behind it, not off a checklist. If you are going to promise a customer something, do not include managing all of CALADESK from their system — today, you cannot.
How a customer implements it
1. Issue a credential
In Settings → API access, they give it a name ("CRM", "management dashboard") and click create. It is shown only once: it is stored encrypted, so not even we can show it again.
2. Decide what it needs: read, write, or both
It starts out read-only. If it will also open tickets, they turn on the write permission with the switch next to the credential.
3. Store the credential where you store your passwords
Never in a webpage's code: anyone who opens the browser would see it, and with it could read all of their tickets.
4. Send it on every call
In a header: Authorization: Bearer cal_.... The company comes from the credential itself, so there is no way to ask for another customer's tickets, not even by mistake.
5. If it will create tickets, also send an idempotency key
A header Idempotency-Key with something that identifies the event — the order number, their form's id. If their request gets cut off halfway and they retry, a second case does not open: they get back the one that already existed.
The limits, and why they exist
| Limit | How much | What it is for |
|---|---|---|
| Reads | 120 per minute, per credential | So an integration with a badly written loop doesn't affect everyone else |
| Creations | 30 per minute, per credential | Keeps a broken form from opening a hundred identical cases |
| Page size | 200 tickets at most | Asking for "all" with thousands of cases would be an endless download |
What people build with this
- A dashboard for management: how many cases are open, how many overdue — read only.
- Their website form opens the ticket directly, without going through an email.
- The customer's record in their CRM shows their support cases.
- Their own reports, in their own spreadsheet, with their own formulas.
- An urgent ticket that pops up in their Slack or Teams, via webhook.
Want to see it working end to end, without writing a program?
Follow the Google Sheets guide — it sets up a real sync in twenty minutes.Not using CALADESK yet?
The API is one more piece. Emails, Telegram, WhatsApp and your website chat all land in the same inbox.
Let's talk