Using the HQ REST-API with Postman for Easy Integration Tests



The HQ API is becoming more powerful and many customers are already using it to expand the use cases of the HQ. Developing with a REST API is not for everyone, but we want to show how easy it is to try it out.

We recently launched our developer portal where you can find all the capabilities of the HQ API and contact us for help. In this post, we want to explain how to access the HQ API with Postman, a simple Chrome extension to make REST requests.

Let’s consider the following situation: you’re interested in synchronizing your HQ contacts with your favorite contacts app. You’re not a developer, but you would like to find out which data can be exported before you plan your next steps.

First, you would visit our developer portal at You will find details about authentication, which we will cover a bit later. Next, you click on REST API Documentation and search for contacts.

HQ API Documentation

By looking at the options on the left, you will see that you can retrieve all contact persons, create new ones or delete existing contacts. This is defined by the available HTTP methods GET, POST, PUT or DELETE.

HTTP Method      Description
GET Retrieve one or several entries
POST Create a new entry
PUT Update an existing entry
DELETE Delete an entry


On the right, under Server URL, you can see the URL that gives you access to the contact persons. Copy this URL now.

Let’s try it out now! To do so, install the Chrome extension Postman, which is a simple REST client that makes it very easy to access APIs like ours. And the best part: it’s free!

Postman in the Chrome App Store

Open Postman. Next, paste the URL you copied earlier into the URL bar on top. If you forgot, here is the URL again: Make sure that GET is selected.

GET Request in Postman

Before we can get data from the API, we need to authenticate. This makes sure that no one else can access your data. In Postman, select Headers in the bar below the URL. Add “Authorization” as a new key and type “Bearer ” into the value. Note the space after “Bearer”!

Bearer Token in Postman

Next, we need the API token for your HQ. To get one, log in to your HQ, go to Admin > API Clients. You’ll find the API token there. If you’re not an admin, ask one for help.

API Token in the HQ

Copy it now and paste it into Postman after “Bearer “. Now you can hit “Send”.

Nice job if this is your very first API call! Postman will show the result of the request in the lower part of the window. You will find a list of contact persons in JSON format, which is a simple data structure used in REST APIs.

At the root, you will find a property called “values”, which is a list of contact persons. Each contact person is surrounded by curly brackets like these: { }. Each contact person has a lot of properties, like a name, position and more. Scroll through the result and you will find a contact person you know. Those are the same ones you can find in your HQ!

API Result from GET request

Now, click on “Save” and fill the window so that you can easily do the same request again.

Saving requests in Postman

Well done, you have mastered the basics of using the HQ API with Postman.

Check back for more details on how to use our API, examples and extended use cases.

Get Angularity updates



Schreibe einen Kommentar!

Your email address will not be published. Required fields are marked *