The PALMS API lets your website, CRM, school system or a tool like Zapier, Make or n8n work with PALMS: create and update contacts, read conversations, assign and close them, and send messages and WhatsApp templates. Your software proves who it is with an API key.
Before you start
- You’re an Owner or an Admin of the organization.
- You know which workspace the integration is for: a key acts on the workspace that was open when you created it.
- The person who builds the integration (you, a developer, or an agency) can store a secret on a server. Never put a key in a web page or a mobile app people download: anyone could read it.
Create a key
- Open Integrations → PALMS API and click Create API key.
- Name the key after where it will be used, for example Website contact form or Zapier.
- Choose when it expires: in 30 days, 90 days, 1 year, or never. Shorter is safer; you can create a new key at any time.
- Choose its permissions: only what the tool needs (see permissions).
- Click Create key. PALMS shows the key once: copy it and store it safely (a password manager, or your server’s settings).
Test your key
Run this in a terminal (replace the key):
curl -H "Authorization: Bearer palms_xxxxxxxxxx_…" https://<api-address>/v1/api/meYou should see the key’s name, its permissions, and your organization and workspace. If you see an error, check the errors table.
Permissions
| Permission | Lets the key |
|---|---|
Read contacts (contacts:read) | List, search and read contacts, their tags and custom fields; list tags. |
Change contacts (contacts:write) | Create, update and delete contacts; add and remove tags. |
Read conversations (conversations:read) | List and read conversations. |
Manage conversations (conversations:write) | Assign, close and reopen conversations. |
Read messages (messages:read) | Read the messages of a conversation. |
Send messages (messages:write) | Send replies, internal notes and WhatsApp templates. |
Read templates (templates:read) | List your WhatsApp templates. |
Read channels (channels:read) | List your connected channels. |
Read team (team:read) | List members and teams (to assign conversations). |
A permission to change something also lets the key read it.
What you can do
All addresses start with https://<api-address>/v1/api. Replace <api-address> with the address shown in the key's Test step in PALMS. Send and receive JSON. The full reference (for Postman or code generators) is at /v1/api/openapi.json.
| Request | What it does |
|---|---|
GET /me | The key, its organization and workspace. |
GET /contacts | Contacts, newest first. Filters: q, phone, email, tag, updatedSince. |
POST /contacts | Create a contact. If the phone or email already exists you get a 409 with the existing contactId. |
POST /contacts/upsert | Create or update, matching on the phone number, then the email. Best for forms and syncs. |
GET / PATCH / DELETE /contacts/{id} | Read, update or delete one contact. |
POST /contacts/{id}/tags · DELETE /contacts/{id}/tags/{name} | Add or remove a tag. |
GET /conversations | Conversations, most recent activity first. Filters: status, contactId, assigneeId. |
GET / PATCH /conversations/{id} | Read; close, reopen, assign or unassign. |
GET /conversations/{id}/messages | The messages, newest first. |
POST /conversations/{id}/messages | A text reply, or an internal note ("type": "note"). |
POST /messages/template | Send an approved WhatsApp template to a contact. |
GET /templates, /channels, /members, /teams, /tags | Reference lists. |
Create or update a contact from a website form:
curl -X POST https://<api-address>/v1/api/contacts/upsert \
-H "Authorization: Bearer $PALMS_API_KEY" -H "Content-Type: application/json" \
-d '{"name":"Ama Mensah","phone":"+233241234567","tags":["Website"],"customFields":{"programme":"Nursing"}}'Send a WhatsApp template:
curl -X POST https://<api-address>/v1/api/messages/template \
-H "Authorization: Bearer $PALMS_API_KEY" -H "Content-Type: application/json" \
-d '{"contactId":"…","templateId":"…","values":["Ama","15 June"]}'Lists return { "data": [...], "nextCursor": "…" }. To get the next page, send cursor=<nextCursor>; nextCursor is null on the last page. limit is 25 by default, at most 100.
Phone numbers are stored in international format (+233241234567). Numbers without a country code use your organization’s country.
Custom fields use the field’s key (see Settings → Contacts → Custom fields). Send null to clear one.
Sending messages: the rules
- WhatsApp’s 24-hour window: you can send a free-form text only within 24 hours of the customer’s last message. After that, send an approved template (
POST /messages/template). The API answers409with an explanation if the window is closed. - Messages are queued and sent in the background: the answer has
"status": "queued"; read the message again later to seesent,delivered,readorfailed. - Add a
clientId(any UUID you generate) to make a send safe to retry: the sameclientIdnever sends twice. - Contacts who opted out never receive templates.
- Messages sent by the API show in the inbox as API · <key name>.
Limits
Each key may make 120 requests a minute. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the counter resets). Over the limit, you get 429 with a Retry-After header: wait that many seconds and try again. An organization can have up to 25 active keys.
Errors
Errors look like { "error": { "code": "…", "message": "…", "referenceId": "…", "fields": {…} } }. The message explains what to do. Give us the referenceId if you contact support.
| HTTP | Code | What it means | What to do |
|---|---|---|---|
| 401 | UNAUTHENTICATED | No key, a wrong key, or a revoked or expired key. | Send Authorization: Bearer <key>. Check you copied all of it. Create a new key if it was revoked or expired. |
| 403 | FORBIDDEN | The key doesn’t have the permission this request needs. | Create a key with that permission. |
| 404 | NOT_FOUND | Nothing with this id in the key’s workspace. | Check the id, and that the key is for the right workspace. |
| 409 | CONFLICT | The request clashes with the current state (contact exists, conversation closed, 24-hour window closed). | Read the message: it says what to do instead. |
| 422 | VALIDATION_FAILED | A value is missing or invalid. | fields lists which ones. |
| 429 | RATE_LIMITED | Too many requests this minute. | Wait Retry-After seconds. |
Keep keys safe
- One key per tool, with only the permissions it needs, and an expiry date.
- Store keys on a server, never in a web page, a mobile app or a shared document.
- Revoke a key as soon as you stop using it, or if it may have leaked: open Integrations → PALMS API and click Revoke. It stops working immediately.
- The keys list shows when each key was last used and how many requests it made in the last 24 hours, so you can spot keys nobody uses.
- Everything a key changes is in the audit log (Settings → Audit log) as API · <key name>.