Integration notes

Recommendations for building a client that stays reliable as the platform evolves.

​

Handle status codes by class

Accept any 2xx response as success rather than matching an exact code. Successful operations return 200, with 201 and 202 used where an operation creates a resource or accepts work for later processing. Handle the full set of documented error codes on every call. See Errors.

​

Support both response shapes

Most operations wrap their payload in the standard envelope, and a small number return it directly. Write your client to accept both rather than assuming the envelope is present. See Response format. Acknowledgement payloads represent success either as a boolean or as a string, so check each operation’s schema rather than generalising from another operation.

​

Pagination

Confirm the paging convention for each operation you use, as some index from zero and others from one. For the inbound message list, the page and limit values in the response echo your request. Use total and totalPages to determine how much data is available.

​

Retry and backoff

With an API key, give every send an Idempotency-Key header and retry with the same key and body, so a retry never sends a message twice. Each key is limited to 120 requests per minute by default; on 429, wait for Retry-After before retrying. See Idempotency and Rate limits. Sending volume is governed by your credit balance, so ensure your integration handles a payment-required response as a recoverable condition — top up and retry the identical request rather than treating it as a permanent failure. See Credits.

​

Delivery confirmation

Messages settle at SENT once the mobile network has accepted them. Progression to DELIVERED depends on confirmation returned by the network. See Statuses.

​

Streaming inbound messages

The two Server-Sent Events endpoints deliver inbound messages as they arrive. Each stream emits a connected event once the connection is established, then an inbound-message event carrying a message object for each new message. Reconnect on disconnection, and treat the inbound message list as the authoritative record when reconciling after a gap in the stream.

​

Environments

Develop against staging, and note that messages sent from staging are charged in the same way as production. See Introduction for base URLs. API keys belong to one environment: staging keys start with hk_test_ and production keys with hk_live_.

​

Support

Owners and Admins create API keys themselves in Settings → API keys. See Authentication with API keys. For integration support and capacity planning, contact your Primetel account manager.