API documentation

General intro

Users of the HIVED API can create shipments for delivery to be made in the postcodes covered by HIVED and retrieve the corresponding shipping label.

We are continuously working on providing more features and functionalities to our APIs. If you have any feedback or suggestions how we could make our APIs more useful for you, please don’t hesitate to let us know at tech@hived.space.

Technical intro

The API closely follows REST semantics, uses JSON to encode objects, and relies on standard HTTP codes to signal operation outcomes.
(An older version of the API is available here)

1. Authentication

In order to access our label generation API you will need to generate a JSON Web Token (JWT) for authentication. Send a GET request using Basic Auth with the credentials provided to you to the endpoint /user/login. In response, you will receive your unique JWT that will expire after 60 days. Use this token in the headers for your request to the label generation endpoint.

2. Create shipment

In order to create a new shipment, issue a POST request to the /shipment endpoint. Your request body should include a JSON object (= shipment) with a number of mandatory fields that contain the desired shipment properties (e.g. recipient name, recipient address). The request returns the generated label as an application/pdf and generates a shipment in the HIVED database.

The API also checks whether the postcode sent is within the HIVED coverage area (see also our Service Overview). If all mandatory fields are provided and the postcode is valid, the request will reply with code 200 as well as the shipping label PDF. If the postcode sent is in invalid format or outside of our coverage area, a validation error and code 401 will be returned.

The shipment endpoint is limited to 5 requests per second. If that limit is met, code 429 is returned.