Help Centre / PALMS API and API keys

PALMS API and API keys

Create an API key, choose its permissions, and read or update contacts, conversations and messages from your own software.

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

  1. Open Integrations → PALMS API and click Create API key.
  2. Name the key after where it will be used, for example Website contact form or Zapier.
  3. 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.
  4. Choose its permissions: only what the tool needs (see permissions).
  5. 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/me

You should see the key’s name, its permissions, and your organization and workspace. If you see an error, check the errors table.

Permissions

PermissionLets 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.

RequestWhat it does
GET /meThe key, its organization and workspace.
GET /contactsContacts, newest first. Filters: q, phone, email, tag, updatedSince.
POST /contactsCreate a contact. If the phone or email already exists you get a 409 with the existing contactId.
POST /contacts/upsertCreate 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 /conversationsConversations, most recent activity first. Filters: status, contactId, assigneeId.
GET / PATCH /conversations/{id}Read; close, reopen, assign or unassign.
GET /conversations/{id}/messagesThe messages, newest first.
POST /conversations/{id}/messagesA text reply, or an internal note ("type": "note").
POST /messages/templateSend an approved WhatsApp template to a contact.
GET /templates, /channels, /members, /teams, /tagsReference 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 answers 409 with 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 see sent, delivered, read or failed.
  • Add a clientId (any UUID you generate) to make a send safe to retry: the same clientId never 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.

HTTPCodeWhat it meansWhat to do
401UNAUTHENTICATEDNo 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.
403FORBIDDENThe key doesn’t have the permission this request needs.Create a key with that permission.
404NOT_FOUNDNothing with this id in the key’s workspace.Check the id, and that the key is for the right workspace.
409CONFLICTThe request clashes with the current state (contact exists, conversation closed, 24-hour window closed).Read the message: it says what to do instead.
422VALIDATION_FAILEDA value is missing or invalid.fields lists which ones.
429RATE_LIMITEDToo 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>.

Still stuck?

Our team answers on WhatsApp, in English or French.

WhatsAppOpen Graphwafe