Users of the HIVED API currently can:
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.
The API closely follows REST semantics, uses JSON to encode objects, and relies on standard HTTP codes to signal operation outcomes. The API is limited to 5 requests per second. If you exceed this rate, you will receive a 429 status code and will need to wait 30 seconds before subsequent requests will succeed. If you anticipate a higher read volume, we recommend using a caching proxy.
In order to create a new shipment, issue a POST request to the domain provided to you. Your request body should include an object (= shipment) with a number of mandatory and optional fields that contain the desired shipment properties such as recipient address and delivery instructions. The request returns the object (= shipment) created if the call succeeded, including the “Record_ID” which will uniquely identify the shipment in our system.
Please note that the sender address information is shown on the shipping label whereas collection address information is not. If you would like the sender address to be private, you can leave the sender address information blank and the label will only display the sender's name. Typically API users would not need to fill out the collection address information as this would not be subject to (frequent) change and would be set once during onboarding. Should you, however, require any deliveries to be collected from a different address, please specify the collection address information and this will override the collection address specified during onboarding.
The fields below show all types of shipment-related information you can provide. Mandatory fields are denoted with an asterisk and the expected data type as well as any relevant info is listed in brackets. Please note all field information is case-sensitive.
The request will return a response which includes all submitted fields as well as some additional information generated by our system (this additional information might change periodically but this is not relevant to the API user). There are only two relevant fields for the API user in the response:
In order to retrieve the shipping label for a shipment created earlier, issue a GET request to the domain provided to you, appended with the “Record_ID” of that shipment (provided as a response to the POST request for the shipment earlier).
The request will return a response which includes all fields submitted for this shipment earlier as well as some additional information generated by our system (this additional information might change periodically but this is not relevant to the API user). Now it will also include a link to the shipping label (PDF) as the value of the field “Label_Link”.
Please note that it takes up to 1 minute for the label to generate after the shipment was created - please don't try to retrieve the shipping label too quickly.
This API will verify if a postcode is within the HIVED delivery area or not, without creating a shipment. In order to check a postcode, issue a POST request to the domain provided to you. Your request body should include only the full UK postcode as the value for the field "Recipient_Postcode" (formatting can be ignored; i.e. whitespace or lowercase). The request returns the value for "Address_in_Delivery_Area" as "Valid" if the postcode is within HIVED's delivery area and "Invalid" if not.
