Developer API
The Developer API is Resool's REST API. It lets your own systems, such as your website, back office, ERP or data warehouse, read and update Resool data: create and update contacts, tag them, list conversations, send messages, and create and update tickets and tasks. You authenticate with an API key that you create in Resool, and each key can only do what the member who created it is allowed to do.
Before you begin
- Only workspace Owners and Admins can create and revoke API keys.
- A key acts as the member who created it. It never has more access than that member's role.
How to create an API key
- Go to
Settings › Appsand open the Developer tools tab. - Click Connect (or Manage) on the Developer API card. The Developer API page opens.
- In the API keys card, click New key.
- Enter a Name that says where the key is used, for example "Website" or "ERP".
- Choose the Access:
- Read: view contacts, conversations, tickets and tasks.
- Read and write: also create and update records and send messages.
- Click Create key.
Settings › Apps › Developer tools › Developer API › New key
The "New key" dialog with the Name field filled in ("Website") and the Access options Read and Read and write, with Read and write selected.
File: screenshots/developer-api-new-key.png
- In Copy your new key, click the copy button and store the key somewhere safe, such as your server's secret store. This is the only time the key is shown. Click Done.
How to manage API keys
The API keys card lists every active key with:
- Name, and who created it and when ("By … · date").
- Key: the first characters of the key, so you can recognise it.
- Access: Read or Read and write.
- Last used: when the key last made a request, or Never.
Settings › Apps › Developer tools › Developer API
The Developer API page with the API keys card: the base address under the title, the New key button, and a table with two keys (one Read, one Read and write) showing Last used dates and revoke buttons.
File: screenshots/developer-api-keys-list.png
To stop a key, click the revoke button on its row and confirm Revoke. Anything using the key stops working right away. Removing the member who created a key also stops it.
How to make your first request
The base address is shown under the API keys title. Send the key as a Bearer token in the Authorization header:
curl https://api.resool.io/v1/me \
-H "Authorization: Bearer YOUR_API_KEY"/me is the connection test. It returns the workspace, the member the key belongs to and the permissions the key has. Use the base address exactly as your API keys card shows it.
Requests and responses are JSON. Dates are ISO 8601 and IDs are UUIDs. No cookies are needed.
What you can do with the API
| Area | Requests |
|---|---|
| Account | GET /me |
| Contacts | GET /contacts (search and paginate), GET /contacts/{id}, POST /contacts, PATCH /contacts/{id} |
| Contact tags | POST /contacts/{id}/tags (by tag ID, or by name: created if missing), DELETE /contacts/{id}/tags/{tagId}, GET /tags |
| Messages | POST /contacts/{id}/messages (on the contact's latest conversation), POST /conversations/{id}/messages, GET /conversations/{id}/messages (latest 50) |
| Conversations | GET /conversations (filter by status), PATCH /conversations/{id} (status, assignee, team) |
| Tickets | GET /tickets, GET /tickets/{id}, POST /tickets, PATCH /tickets/{id} |
| Tasks | GET /projects, GET /tasks, POST /tasks, PATCH /tasks/{id} |
| Members | GET /members |
| Event subscriptions | POST /hooks, DELETE /hooks/{id}. See Webhooks. |
Every request also checks the member's permissions. For example, sending a message needs permission to reply in the inbox, and a Read key can never create, update or send. Channel rules still apply: on WhatsApp, a free-form message can only be sent within 24 hours of the customer's last message.
Notes and limitations
- Rate limit: up to 120 requests per minute. Above that you get HTTP
429; wait and try again. - Errors are JSON with a status code and an error code:
| Status | Meaning |
|---|---|
400 | The input isn't valid. |
401 | The key is missing, wrong or revoked. |
402 | The workspace's plan doesn't include the API, or the subscription isn't active. |
403 | The key is read-only, or the member doesn't have the permission. |
404 | Not found in this workspace. |
429 | Too many requests. |
- A key works for one workspace only: the one it was created in.
FAQ and troubleshooting
I get 401 even though I copied the key
What you can do:
- Send the header as
Authorization: Bearer <key>, with a space after "Bearer" and no quotes. - Check that the key wasn't revoked and that the member who created it is still in the workspace.
I get 403 when creating a contact or sending a message
The key has Read access, or the member who created it isn't allowed to do that. Create a Read and write key as a member whose role has the permission.
Can I see a lost key again?
No. Keys are shown only once. Revoke the lost key and create a new one.
Do I need the API to use Zapier, Make or n8n?
You don't need to create a key: those tools connect with a Resool sign-in. They still need the Scale plan. See Zapier, Make and n8n.
How do I get notified when something happens instead of polling?
Use Webhooks. Resool sends a signed request to your server when contacts, conversations, tickets, tasks and deals change.