Authentication with API keys

An API key lets your own server call the Heullo API for your organization. Use one for server-to-server integrations, such as a CRM, a booking system or an order pipeline. People still sign in to the web application with their own login. A key acts for the organization, not for a person. Messages it sends, contacts it creates and credits it uses belong to the organization. A key keeps working when the member who created it leaves the organization, so revoke keys yourself when they are no longer needed.

Who can manage keys

Owners and Admins manage keys in Settings → API keys. Other roles do not see that tab. See Your account for the roles. A key cannot create, list or revoke keys. Managing keys always needs a signed-in Owner or Admin.

Create a key

Open Settings → API keys

Start a new key from the API keys tab.

Name it after the integration

Up to 60 characters, for example CRM sync. A clear name tells you which integration stops working when you revoke the key.

Choose the scopes

Tick only what the integration needs. See Scopes below.

Choose an expiry

30, 90 or 365 days, or never. Prefer an expiry: a key that expires limits the damage if it leaks unnoticed. An expired key is refused from the moment it expires.

Copy the key and store it

The key is shown once, when you create it. Copy it into your secret manager or your platform’s secret store straight away. Heullo stores only a hashed form of the key, so it cannot show it to you again. If you lose a key, create a new one and revoke the old one.

An organization can have at most 10 active keys. Revoked and expired keys do not count toward the limit. Revoke a key you no longer use before creating another. The API keys tab lists every key with its name, a hint such as hk_live_AbCd…wxyz, its scopes, who created it, when it was last used, when it expires and its status: active, expired or revoked. Revoked and expired keys stay in the list as a record.

IP allowlists

When IP allowlists are available for your organization, the create form shows an extra field for them. Enter one public IPv4 or IPv6 address or CIDR range per line, up to 20 entries, for example 203.0.113.7 or 198.51.100.0/24. A key with an allowlist answers 403 with API_KEY_IP_NOT_ALLOWED to requests from any other address. A key without an allowlist accepts requests from any address.

Key format

Production keys start with hk_live_, followed by 40 letters and digits:

hk_live_<40 letters and digits>

Keys created in the staging environment start with hk_test_. A key works only in the environment that created it, and is refused with 401 in the other. See Base URLs. The fixed prefix makes a key easy to match with a secret-scanning rule in your own repositories and logs.

Call the API with a key

Send the key as a bearer token in the Authorization header of every request:

Authorization: Bearer hk_live_…

No X-Organization-Id header is needed, because the key identifies its organization. If you send that header anyway, it must name the key’s organization, or the request is refused with 403 and ORGANIZATION_MISMATCH. The key is accepted only in the Authorization header, never in a query string or form field. The examples below call production, https://api.heullo.com, and read the key from an environment variable on your server, so it never appears in your source code. Responses use the standard response envelope. Response examples are abridged; each operation’s page lists every field.

Send a single message

Needs the sms:send scope. Operation reference.

curl https://api.heullo.com/api/v1/sms/single \
  -H "Authorization: Bearer $HEULLO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10482-shipped" \
  -d '{
    "phoneNumber": "+35799123456",
    "content": "Your order 10482 has shipped.",
    "senderId": "HEULLO"
  }'

Field	Required	Notes
`phoneNumber`	Yes	The recipient, in international format.
`content`	Yes	The message text. See Message encoding for how it is split into parts.
`senderId`	No	The name or identifier of an approved sender ID. Leave it out to use your organization’s default sender ID.
`scheduledFor`	No	An ISO 8601 time in UTC, up to one year ahead. Leave it out to send now.

{
  "data": {
    "id": "6730b2c4e8a1f20b7c4d9e10",
    "managementId": "6730b2c4e8a1f20b7c4d9e0f",
    "recipient": "+35799123456",
    "content": "Your order 10482 has shipped.",
    "senderId": "HEULLO",
    "messageType": "SMS",
    "deliveryType": "SINGLE",
    "status": "SENT",
    "messageParts": 1,
    "channel": "API",
    "apiKeyId": "6730a91fe8a1f20b7c4d9d02",
    "retryCount": 0,
    "createdAt": "2026-11-05T10:00:00.123Z"
  },
  "message": "SMS scheduled successfully",
  "status": 200,
  "success": true,
  "timestamp": "2026-11-05T10:00:00.415Z"
}

status is SENT when the mobile network accepted the message, FAILED when it was refused (the credits are returned), and SCHEDULED when you set a future scheduledFor. Keep id to read the delivery status later. A balance below the cost of the message answers 402; see Errors.

Send a bulk message

Needs the sms:send scope. Operation reference. One bulk request sends the same message to many recipients. Prefer it to a loop of single sends: it is one request against your rate limit, and it creates one campaign in SMS Management.

curl https://api.heullo.com/api/v1/sms/bulk \
  -H "Authorization: Bearer $HEULLO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: opening-hours-2026-11" \
  -d '{
    "name": "November opening hours",
    "recipients": ["+35799123456", "+35799654321"],
    "message": "From November we open at 9:00 on Saturdays.",
    "messageType": "SMS",
    "senderId": "HEULLO"
  }'

Field	Required	Notes
`name`	No	The campaign name shown in SMS Management and Reports. Set it, so you can find the campaign later.
`recipients`	Yes	Phone numbers in international format. Spaces, dashes and brackets are removed and duplicates are dropped. One invalid number refuses the whole request with `400`, naming the invalid numbers.
`message`	Yes	At most 160 characters.
`messageType`	Yes	`SMS`.
`senderId`	No	The name or identifier of an approved sender ID, as for a single send. Leave it out to use your organization’s default sender ID.
`scheduledFor`	No	An ISO 8601 time in UTC. Leave it out, or give a time in the past, to send now.

{
  "data": {
    "managementId": "6730b2d0e8a1f20b7c4d9e21",
    "taskId": "task_3f2b8c1e9a4d",
    "batchId": "0c6f4e2a-8d1b-4f7e-9a35-2b6c0d8e1f47",
    "senderId": "HEULLO",
    "name": "November opening hours",
    "messageContent": "From November we open at 9:00 on Saturdays.",
    "recipientCount": 2,
    "originalRecipientsCount": 2,
    "uniqueRecipientsCount": 2,
    "duplicatesRemoved": 0,
    "scheduledFor": "2026-11-05T10:00:00.123456Z",
    "status": "SCHEDULING",
    "createdAt": "2026-11-05T10:00:00.130412Z"
  },
  "message": "Bulk SMS scheduled successfully",
  "status": 200,
  "success": true,
  "timestamp": "2026-11-05T10:00:00.212Z"
}

The credits for the whole campaign are checked when you send, and a balance that does not cover every recipient answers 402. The messages are then sent in the background. recipientCount and uniqueRecipientsCount are the number of recipients after duplicates were removed, originalRecipientsCount is the number you sent, and duplicatesRemoved the difference. Keep managementId to follow the campaign.

Read a message’s delivery status

Needs the sms:read scope. Operation reference.

curl https://api.heullo.com/api/v1/sms/6730b2c4e8a1f20b7c4d9e10 \
  -H "Authorization: Bearer $HEULLO_API_KEY"

The response has the same shape as the single send response. Read status; see Statuses for what each value means. An identifier that does not belong to your organization answers 404. For the recipients of a bulk campaign, list the campaign’s messages with the managementId from the bulk response. Paging starts at 1, and size is at most 500:

curl "https://api.heullo.com/api/v1/sms/management/6730b2d0e8a1f20b7c4d9e21?page=1&size=100" \
  -H "Authorization: Bearer $HEULLO_API_KEY"

See List the messages in a campaign for the filters.

List inbound messages

Needs the inbound:read scope. Operation reference.

curl "https://api.heullo.com/api/v1/inbound/messages?page=1&limit=20&isRead=false" \
  -H "Authorization: Bearer $HEULLO_API_KEY"

{
  "data": {
    "messages": [
      {
        "id": "6730b3a1e8a1f20b7c4d9e44",
        "from": "+35799123456",
        "to": "+35770001234",
        "message": "INFO opening hours",
        "receivedAt": "2026-11-05T09:58:12.481Z",
        "keyword": "INFO",
        "read": false
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
  },
  "status": 200,
  "success": true,
  "timestamp": "2026-11-05T10:00:01.002Z"
}

Paging starts at 1, and at most 100 messages are returned per page. A key with inbound:read can read messages but cannot mark them as read.

Create a contact

Needs the contacts:manage scope. Operation reference.

curl https://api.heullo.com/api/contacts \
  -H "Authorization: Bearer $HEULLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+35799123456",
    "name": "Maria Georgiou",
    "email": "maria@example.com",
    "company": "Example Ltd"
  }'

phoneNumber is required. name and email are stored as the contact’s name and email. Any other field, such as company above, is stored as a custom field and returned at the top level of the contact.

{
  "data": {
    "id": "6730b41ce8a1f20b7c4d9e58",
    "name": "Maria Georgiou",
    "phoneNumber": "+35799123456",
    "email": "maria@example.com",
    "contactListIds": [],
    "status": "active",
    "createdAt": "2026-11-05T10:00:02.318Z",
    "updatedAt": "2026-11-05T10:00:02.318Z",
    "company": "Example Ltd"
  },
  "message": "Contact created successfully",
  "status": 200,
  "success": true,
  "timestamp": "2026-11-05T10:00:02.320Z"
}

A phone number that already belongs to a contact in your organization answers 409.

Read the balance

Needs the balance:read scope. Operation reference.

curl https://api.heullo.com/api/v1/billing/credits \
  -H "Authorization: Bearer $HEULLO_API_KEY"

{
  "data": {
    "id": "6720f1a9c3b14e0b5d2a7c02",
    "organizationId": "6720f1a9c3b14e0b5d2a7c01",
    "balance": 482.5,
    "totalSpent": 1517.5,
    "totalAdded": 2000,
    "lastUpdated": "2026-11-05T10:00:00.140Z",
    "createdAt": "2026-03-02T08:15:44.901Z"
  },
  "message": "User credits retrieved successfully",
  "status": 200,
  "success": true,
  "timestamp": "2026-11-05T10:00:03.051Z"
}

See Credits for how the balance is charged.

Scopes

A key can call only the operations of the scopes it was given.

Scope	Shown as	Allows
`sms:send`	Send SMS (single and bulk)	Single and bulk sends.
`sms:read`	Read messages and delivery status	Reading a message, the SMS Management list and a campaign’s messages.
`inbound:read`	Read inbound messages	Listing and reading inbound messages.
`contacts:manage`	Contacts and lists	Reading, creating, updating and deleting contacts and contact lists, and adding contacts to lists.
`balance:read`	Read the balance	Reading the credit balance.

The operations each scope allows:

Scope	Method	Path
`sms:send`	`POST`	`/api/v1/sms/single`
`sms:send`	`POST`	`/api/v1/sms/bulk`
`sms:read`	`GET`	`/api/v1/sms/{id}`
`sms:read`	`GET`	`/api/v1/sms/management`
`sms:read`	`GET`	`/api/v1/sms/management/{managementId}`
`inbound:read`	`GET`	`/api/v1/inbound/messages`
`inbound:read`	`GET`	`/api/v1/inbound/messages/{id}`
`contacts:manage`	`GET`, `POST`	`/api/contacts`
`contacts:manage`	`GET`	`/api/contacts/search`
`contacts:manage`	`PUT`, `DELETE`	`/api/contacts/{contactId}`
`contacts:manage`	`GET`, `POST`	`/api/contacts/lists`
`contacts:manage`	`GET`	`/api/contacts/lists/search`
`contacts:manage`	`GET`, `DELETE`	`/api/contacts/lists/{listId}`
`contacts:manage`	`PUT`	`/api/contacts/lists/{id}`
`contacts:manage`	`POST`	`/api/contacts/lists/{listId}/contacts`
`balance:read`	`GET`	`/api/v1/billing/credits`

These operations show the API key scheme and the scope they need on their page in the API reference. Every other operation refuses an API key with 403 and API_KEY_FORBIDDEN, whatever scopes the key has. That includes members and invitations, billing other than reading the balance, settings, sender IDs, keywords, Email-to-SMS, reports, exports, CSV imports, campaign controls such as pause and cancel, and API key management itself. Use the web application, signed in as a member with the right role, for those.

Idempotency

Network failures leave a client unsure whether a send went through. To retry a send safely, give it an Idempotency-Key header. It is accepted on POST /api/v1/sms/single and POST /api/v1/sms/bulk with an API key.

Idempotency-Key: order-10482-shipped

The value is 1 to 255 printable ASCII characters without spaces. Use one value per intended send, for example your own order or job identifier, or a UUID you store with the job before the first attempt. Heullo keeps each idempotency key for 24 hours from the first request, per API key:

You send the same Idempotency-Key	Result
With the same request body, after the first request succeeded	The original response, with the header `Idempotent-Replayed: true`. Nothing is sent again and nothing is charged again.
With the same request body, while the first request is still running	`409` with `IDEMPOTENCY_IN_PROGRESS` and `Retry-After: 1`. Nothing is sent.
With a different request body	`422` with `IDEMPOTENCY_KEY_REUSED`. Nothing is sent.
After the first request failed with an error	The request is processed as new. A failed request does not keep its idempotency key, because nothing was sent.

“The same request body” means the same bytes. Store the body you sent and retry with it, rather than serialising the request again. Retry advice:

Retry timeouts, connection errors, 5xx responses and 409 IDEMPOTENCY_IN_PROGRESS with the same Idempotency-Key and body. Wait for Retry-After where it is given, then back off exponentially.
Do not retry 400, 402, 403 or 422 unchanged. Correct the request first. A corrected request is a new send and needs a new Idempotency-Key.
If retries keep answering 409 IDEMPOTENCY_IN_PROGRESS for several minutes, check SMS Management for the message before you send it under a new Idempotency-Key.
A request with an Idempotency-Key can be at most 1 MiB; a larger one answers 413.

Rate limits

Each key has its own limit, by default 120 requests per minute. The allowance refills evenly through the minute, so a key can make a burst of up to 120 requests and then about two per second. Over the limit, the API answers 429 with RATE_LIMITED and a Retry-After header giving the seconds to wait. Wait at least that long, then retry with exponential backoff and some random jitter, so several workers do not retry at the same moment. Retries and idempotent replays count toward the limit like any other request. To stay under the limit, send to many recipients with one bulk request rather than many single sends, and give each integration its own key. Before running sustained high-volume traffic, contact your Primetel account manager.

Errors

Errors caused by the key itself are answered before the request reaches the operation, with this body:

{
  "status": 403,
  "error": "Forbidden",
  "code": "API_KEY_FORBIDDEN",
  "message": "This API key can't call this endpoint.",
  "timestamp": "2026-11-05T10:00:04.207Z"
}

Match on status and code. The message text can change.

Status	Code	Meaning	What to do
`401`	`INVALID_API_KEY`	The key is unknown, malformed, revoked or expired, belongs to the other environment, or its organization is suspended. The response is the same in every case and carries `WWW-Authenticate: Bearer error="invalid_token"`.	Check the key in Settings → API keys. Do not retry with the same key.
`403`	`API_KEY_FORBIDDEN`	The key’s scopes do not include this operation, or no key may call it.	Create a key with the scope you need, or use the web application.
`403`	`ORGANIZATION_MISMATCH`	The `X-Organization-Id` header names another organization.	Remove the header.
`403`	`API_KEY_IP_NOT_ALLOWED`	The key has an IP allowlist, and the request came from another address.	Call from a listed address, or create a key with the right allowlist.
`429`	`RATE_LIMITED`	The key is over its rate limit.	Wait for `Retry-After`, then back off.
`400`	`INVALID_IDEMPOTENCY_KEY`	The `Idempotency-Key` value is empty, too long or has characters outside printable ASCII.	Use 1 to 255 printable ASCII characters without spaces.
`409`	`IDEMPOTENCY_IN_PROGRESS`	A request with this `Idempotency-Key` is still running.	Retry the same request after `Retry-After`.
`413`	`PAYLOAD_TOO_LARGE`	A request with an `Idempotency-Key` is larger than 1 MiB.	Split the recipients across several bulk requests.
`422`	`IDEMPOTENCY_KEY_REUSED`	This `Idempotency-Key` was already used with a different body.	Use a new `Idempotency-Key` for a different send.

Errors from the operation itself, such as a missing field (400), too few credits (402), a record that is not yours (404) or a duplicate contact (409), use the standard envelope with success: false and no code. See Errors.

Keep keys secure

One key per integration. You can then revoke one integration’s access without touching the others, and the last-used time tells you which integration is active.
Give each key the fewest scopes it needs. A key that only reads the balance cannot send messages if it leaks.
Rotate keys. Create the new key, deploy it to the integration, confirm the integration works with it, then revoke the old key. Both keys work during the change, so nothing breaks.
Revoke a leaked key at once. Revoking takes effect on the next request. Then create a replacement, and check SMS Management and the credit balance for use you do not recognise.
Keep keys on your servers. Never put a key in browser JavaScript, a mobile app or any other code that runs on your customers’ devices, where anyone can extract it. Call Heullo from your own backend instead.
Keep keys out of source code and logs. Load the key from a secret store or an environment variable, and do not log the Authorization header.

Owners and Admins of the organization are emailed when a key is created or revoked, and when a member who created keys leaves or is removed from the organization. The email names the key and never contains the key itself. If you receive one you did not expect, review Settings → API keys.

Messages sent with a key

Messages sent with an API key appear in SMS Management with the API channel, like any other message from your organization. A single send is listed as “API SMS to” followed by the recipient, and a bulk send under the name you gave it. Filter by the API channel in SMS Management or in the Outbound report to see your integrations’ traffic, and the credits it used, separately from messages your team sent.

Using the API

Endpoints

Authentication with API keys

Who can manage keys

Create a key

IP allowlists

Key format

Call the API with a key

Send a single message

Send a bulk message

Read a message’s delivery status

List inbound messages

Create a contact

Read the balance

Scopes

Idempotency

Rate limits

Errors

Keep keys secure

Messages sent with a key

​Who can manage keys

​Create a key

​IP allowlists

​Key format

​Call the API with a key

​Send a single message

​Send a bulk message

​Read a message’s delivery status

​List inbound messages

​Create a contact

​Read the balance

​Scopes

​Idempotency

​Rate limits

​Errors

​Keep keys secure

​Messages sent with a key

Who can manage keys

Create a key

IP allowlists

Key format

Call the API with a key

Send a single message

Send a bulk message

Read a message’s delivery status

List inbound messages

Create a contact

Read the balance

Scopes

Idempotency

Rate limits

Errors

Keep keys secure

Messages sent with a key