Message queue polling API

The polling API enables your systems to pull messages from the Haplo application. This is our recommended method, as it avoids the need for firewalls to be configured.

The queue information page will give you two URLs:

Your Name » Integrations » Integration message queues » (queue name)

The Poll URL is used to fetch the unread messages from the queue. This includes a token, which is then POSTed to the Mark URL to mark the messages as read and ensure they are not sent again.

This two step process ensures that transport errors will not result in messages being lost.

Create an API key

The requests are authenticated with an API key. Click Create API key… on the queue information page.

To authenticate the request, use HTTP Basic authentication with the username haplo and the API key as the password.

Request the unread messages

To fetch the unread message, you should make a simple authenticated GET request to the Poll URL. Here’s an example script using a curl command:

set -e


curl -X GET --user haplo:${API_KEY} https://${SERVER}/api/haplo-integration-messages/poll/QUEUE/fetch

Mark messages as read

The response to the Poll URL will include a token. This must be posted back to the server to mark the messages as read, so they will not be included the next time the application is polled.

The token is opaque and should not be interpreted by your integration code, as its format may change at any time.

Your integration should extract the token from the response, then POST to the Mark URL with the token as the token parameter. An example curl script is:

set -e


curl -X POST --data-urlencode "token=MSwy8w099=" --user haplo:${API_KEY} https://${SERVER}/api/haplo-integration-messages/poll/QUEUE/mark

Configuration for different environments

You will probably need to write your integration so that it can be used with test and live environments.

The only things which will differ between environments will be the hostname in the URLs and the API key.