Services

About

Impact

Blog

Track my parcel

Ship with HIVED

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

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

recipient

string

recipient_address_line_1

string (max. 55 characters)

recipient_address_line_2

string (max. 55 characters)

recipient_address_Line_3

string (max. 55 characters)

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")

parcel_count

integer

parcel_index

integer

weight_kg

number with 1 decimal; e.g. “1.5”

length_cm

integer without any decimals; e.g. “20”

width_cm

integer without any decimals; e.g. “20”

height_cm

integer without any decimals; e.g. “20”

fragile

Boolean (either "true" for fragile or "false" for not fragile)> if no option is selected, the default will be "false")

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 "YYYY-MM-DD" > this is only required if the collection date is not supposed to be asap)

sender_chosen_delivery_date

date (in the format "YYYY-MM-DD" > this is only required if the collection date is not supposed to be asap)

sku

string

account_number

integer (provided by HIVED)

consignment_id

string

Parameters

Type

Required

tracking_id

string

recipient

string

recipient_address_line_1

string (max. 55 characters)

recipient_address_line_2

string (max. 55 characters)

recipient_address_Line_3

string (max. 55 characters)

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")

parcel_count

integer

parcel_index

integer

weight_kg

number with 1 decimal; e.g. “1.5”

length_cm

integer without any decimals; e.g. “20”

width_cm

integer without any decimals; e.g. “20”

height_cm

integer without any decimals; e.g. “20”

fragile

Boolean (either "true" for fragile or "false" for not fragile)> if no option is selected, the default will be "false")

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)