To get started with our APIs you have to follow 3 mandatory steps which are described below:

Step 1: Get an account

To use our APIs, you need to have both a myHillebrand user account aswell as an API key.

  • If you do not have a myHillebrand user account yet, you can get one here: https://my.hillebrand.com/signup
    The user account is used to obtain access to the data that is relevant for you.

  • To obtain the API key for your application, sign up here: https://developer.hillebrand.com/user/register
    The API key is necessary for your application to be able to call our APIs.
    Note that we need to authorise your request first, which is a manual process.
    After receiving the confirmation email that your account has been approved, follow the instructions in this email to activate your account. After these steps you will be able to login to our dev portal.

  • This email will also contain your API key.

Step 2: Authenticate with oauth

To obtain a token that is needed later in every API call, you need to exchange your user credentials and API key for a token.

  • Do a http post to https://login.hillebrand.com/oauth2/aus2lt1zi5HuDEayF0i7/v1/token.

  • Provide your API key and secret in the basic authorisation header (separated by a colon and base64 encode it).
    Set Content-Type to application/x-www-form-urlencoded and Accept to application/json.

  • In the body provide the following: grant_type=password&username=[username]&password=[password]&scope=offline_access
     
    The response will contain your access token and a refresh token. Store them securely in private, non user accessible storage.

    Example request:

    POST https://login.hillebrand.com/oauth2/aus2lt1zi5HuDEayF0i7/v1/token
    Content-Type: application/x-www-form-urlencoded
    Accept: application/json
    Authorization: Basic YXBpa2V5OmFwaXNlY3JldA==
    grant_type=password&username=EnterUserNameHere&password=EnterPasswordHere&scope=offline_access

Step 3: Call the API (for example get all shipments)

  • Use the provided access token in every API call in the authorisation header, prefix it with 'Bearer '.

    Example request:

    GET https://api.hillebrand.com/v2/shipments 
    Accept: application/json
    Authorization: Bearer eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.eyJzYW1wbGUiOiJqd3QifQ.1m34VpI4w-rYut4F6VruoMyI95i4nOgED9iY6hDLytI

Step 4 (optional): Expired token 

The access token will expire after a certain period, if this happens you have to request a new access token, using your refresh token.

  • Do a http post to https://login.hillebrand.com/oauth2/aus2lt1zi5HuDEayF0i7/v1/token.

  • Provide your API key and secret in the basic authorisation header (separated by a colon and base64 encode it).
    Set Content-Type to application/x-www-form-urlencoded and Accept to application/json.

  • In the body provide the following: grant_type=refresh_token&refresh_token=[refresh token]&scope=offline_access
     
    The response will contain your new access token and new refresh token.
    Use these tokens for your next requests.

    Example request:

    POST https://login.hillebrand.com/oauth2/aus2lt1zi5HuDEayF0i7/v1/token
    Content-Type: application/x-www-form-urlencoded
    Accept: application/json
    Authorization: Basic YXBpa2V5OmFwaXNlY3JldA==
    grant_type=refresh_token&refresh_token=PIr11vkIjOIX0b8asESirqGvx0nV12FG&scope=offline_access

Note that you could also do step 2 instead of this step to get a new access token. Using step 4 is more secure though.