API Documentation

General Intro

Users of the HIVED API currently can:

1. Create shipments for delivery to be made in the postcodes covered by HIVED.
2. Retrieve shipping labels for previously created shipments to be printed out and attached to parcels.
3. Verify if a postcode is within our delivery area (without creating a shipment).

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. 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.

‍

1. Create Shipment API

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.

Request

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.

• Tracking_ID_Manual (string; not usually required)
• Recipient* (string)
• Recipient_Address_Line_1* (string)
• Recipient_Address_Line_2 (string)
• Recipient_Address_Line_3 (string)
• Recipient_Town* (string)
• Recipient_Postcode* (string; a full valid UK postcode)
• Recipient_Email_Address (string; a valid email address)
• Recipient_Phone_Number (string; a valid phone number)
• Delivery_Instructions (string; multi-line)
• Sender* (string)
• Sender_Address_Line_1 (string)
• Sender_Address_Line_2 (string)
• Sender_Address_Line_3 (string)
• Sender_Town (string)
• Sender_Postcode (string; a full valid UK postcode)
• Order_Number (string)
• Shipping_Class (string, either of exactly: "Same-Day", "Next-Day", "2-Days")
  -> if no option is selected, the default will be "Next-Day"
• Weight_KG (number with 1 decimal; e.g. “1.5”)
• Length_CM (whole number without any decimals; e.g. “20”)
• Width_CM (whole number without any decimals; e.g. “20”)
• Height_CM (whole number without any decimals; e.g. “20”)
• Parcel_Size (string, either of exactly: "Letter", "Small", "Medium", "Large")
• Fragile (boolean, either "true" for fragile or "false" for not fragile)
  -> if no option is selected, the default will be "false"
• No_Label_Needed (boolean, either "true" when no label is needed or "false" when label is needed)
  -> the default is "false", please don't specify this field unless agreed beforehand
• Value_GBP (number with 2 decimals, e.g. "119.90")
• Age_Verification_Required (boolean, either "true" when required or "false" when not required)
  -> the default is "false", please don't specify this field unless agreed beforehand
• Collection_Contact_Name (string)
• Collection_Address_Line_1 (string)
• Collection_Address_Line_2 (string)
• Collection_Address_Line_3 (string)
• Collection_Town (string)
• Collection_Postcode (string; a valid UK postcode)
• Collection_Instructions (string; multi-line)
• Collection_Phone_Number (string; a valid phone number)
• Collection_Email (string; a valid email)
• Sender_Chosen_Collection_Date (date; in the format "MM/DD/YYYY")
  -> this is only required if the collection date is not supposed to be asap
• Sender_Chosen_Delivery_Date (date; in the format "MM/DD/YYYY")
  -> this is only required if the delivery date is not supposed to be asap

‍

Example Request (cURL)

‍Response

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:

• Address_in_Delivery_Area
  -> This field verifies if a shipment’s postcode is in the areas covered by Hived. This field’s value has to be “Valid” and not “Invalid”. If it is “Invalid”, we are not able to deliver this parcel and no label will be generated later on.
• Record_ID
  -> This field uniquely identifies the just created shipment and will be required to access the shipping label later on.

Example Response (cURL)

‍‍

2. Retrieve Shipping Label API

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.‍

Example Request (cURL)

Example Response (cURL)

‍

3. Verify Postcode API

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.

Example Request (cURL)

‍

Example Response (cURL)

‍