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)

Production:
https://api.hived.space
Sandbox:
https://test.api.hived.space

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.

GET
/user/login
Example request (cURL)
Response
Code
Content-Type
Description
200
application/json
Valid request: JWT successfully generated. Returns JWT.
401
application/json
Unauthorised request: credentials invalid.
500
application/json
Internal server error
Example response

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.

Request
POST
/shipment

The fields below show all types of shipment-related information you can provide.

Parameters
Type
Required
tracking_id
string
n
recipient
string
y
recipient_address_line_1
string (max. 55 characters)
y
recipient_address_line_2
string (max. 55 characters)
y
recipient_address_Line_3
string (max. 55 characters)
y
recipient_town
string
y
recipient_postcode
string (a full valid UK postcode)
y
recipient_email_address
string (a valid email address)
n
recipient_phone_number
string (a valid phone number)
n
delivery_instructions
string (multi-line)
n
sender
string
y
sender_address_line_1
string
n
sender_address_line_2
string
n
sender_address_line_3
string
n
sender_town
string
n
sender_postcode
string (a full valid UK postcode)
n
order_number
string
n
shipping_class
string (either of exactly: "Same-Day", "Next-Day", "2-Days")> if no option is selected, the default will be "Next-Day")
n
parcel_count
integer
n
parcel_index
integer
n
weight_kg
number with 1 decimal; e.g. “1.5”
n
length_cm
integer without any decimals; e.g. “20”
n
width_cm
integer without any decimals; e.g. “20”
n
height_cm
integer without any decimals; e.g. “20”
n
fragile
Boolean (either "true" for fragile or "false" for not fragile)> if no option is selected, the default will be "false")
n
value_gbp
number with 2 decimals, e.g. "119.90"
n
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)
n
collection_contact_name
string
n
collection_address_line_1
string
n
collection_address_line_2
string
n
collection_address_line_3
string
n
collection_town
string
n
collection_postcode
string (a valid UK postcode)
n
collection_instructions
string (multi-line)
n
collection_phone_number
string (a valid phone number)
n
collection_email
string (a valid email)
n
sender_chosen_collection_date
date (in the format "YYYY-MM-DD" > this is only required if the collection date is not supposed to be asap)
n
sender_chosen_delivery_date
date (in the format "YYYY-MM-DD" > this is only required if the delivery date is not supposed to be asap)
n
sku
string
n
account_number
integer (provided by HIVED)
n
consignment_id
string
n
Example Request
Response
Code
Content-Type
Description
200
application/pdf
Valid request: postcode and shipment information accepted. Creates shipment record in HIVED database and returns HIVED shipping label.
400
application/json
One or more validation errors: postcode invalid and/ or insufficient shipment information received.
401
application/json
Unauthorised request: token missing or invalid.
500
application/json
Internal server error.
503
application/json
Server overloaded.
Example response (200, application/ pdf)
Response format (400 - 503, application/ json)
Contact our team to learn more about how HIVED can improve your business.
Get a quote
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.