Documentation Powered by Redocly

Open Yellowbox Integration API (1.0.0)

Download OpenAPI specification:Download

Open API for Integration between Client and Yellowbox

Create user

Request Body schema: application/json
userId
string
cardUid
string
displayName
string
email
string
groupId
string
phoneNumber
string

Responses

Request samples

Content type
application/json
{
  • "userId": "1234",
  • "cardUid": "A3653E9149FD7B",
  • "displayName": "John Doe",
  • "email": "john@email.com",
  • "groupId": "dunder-mifflin",
  • "phoneNumber": "+61423123123"
}

Get all users

Responses

Get all users (by attribute)

Get a map of userIds on record in Yellowbox, based on keys defined by the provided attribute

path Parameters
attribute
required
string

One of uid, email or phoneNumber

Responses

Get user (debug)

path Parameters
userId
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "No user found for userId 1234"
}

Get user

path Parameters
userId
required
string

Responses

Response samples

Content type
application/json
{
  • "userId": "1234",
  • "cardUid": "A3653E9149FD7B",
  • "displayName": "John Doe",
  • "email": "john@email.com",
  • "groupId": "dunder-mifflin",
  • "phoneNumber": "+61423123123"
}

Update user

userId and groupId cannot be changed. All other body parameters are optional.

path Parameters
userId
required
string
Request Body schema: application/json
cardUid
string
displayName
string
email
string
groupId
string
phoneNumber
string

Responses

Request samples

Content type
application/json
{
  • "cardUid": "A3653E9149FD7B",
  • "displayName": "John Doe",
  • "email": "john@email.com",
  • "groupId": "dunder-mifflin",
  • "phoneNumber": "+61423123123"
}

Response samples

Content type
application/json
{
  • "userId": "1234",
  • "cardUid": "A3653E9149FD7B",
  • "displayName": "John Doe",
  • "email": "john@email.com",
  • "groupId": "dunder-mifflin",
  • "phoneNumber": "+61423123123"
}

Delete user

path Parameters
userId
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "No user found for userId 1234"
}

Get Bookings or Availability

Get bookings or locker availability information by prefix and size for the given user and location. The response object will contain bookings if the user has active booking(s) at the location, otherwise it will contain availability.

query Parameters
userId
required
string
Example: userId=1234

user Id for which to check for existing bookings

locationId
required
string
Example: locationId=dunder-mifflin

Yellowbox location ID to query for existing bookings or availability at

Responses

Response samples

Content type
application/json
{
  • "bookings": [
    ],
  • "availability": [
    ]
}

Create Booking

Create a new booking for the provided user. Our backend will automatically select a locker for the user based on whether there are any matching lockers which are available and which the user was also the last user of, time spent idle, battery level etc.

Request Body schema: application/json
locationId
required
string

Yellowbox location ID

userId
required
string

user ID

prefix
string or null

Prefix for which to create a booking within. If this field is null or omitted we will select a locker with no prefix for the booking, not any prefix.

size
required
string
Enum: "small" "medium" "large"

Desired locker size to create a booking for

Responses

Request samples

Content type
application/json
{
  • "locationId": "dunder-mifflin",
  • "userId": "1234",
  • "prefix": "M",
  • "size": "small"
}

Response samples

Content type
application/json
{
  • "lockerId": "KIOEjr2sYyiwhioUyPKH",
  • "location": "6052lqGZt9Q28Sc4ferP",
  • "lockerNumber": 3,
  • "prefix": "M",
  • "prefixLong": "Mens",
  • "bookingStart": "2022-02-07T14:20:41.080Z",
  • "size": "medium"
}

End Booking

End an existing booking on the provided locker

path Parameters
lockerId
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "There is no active booking on the requested locker"
}

Set users keypad PIN

Set the external lock keypad PIN for the user. This endpoint should also be used to update the users keypad PIN.

path Parameters
userId
required
string
Request Body schema: application/json
pin
required
string

4 digit keypad pin

Responses

Request samples

Content type
application/json
{
  • "pin": "1234"
}

Response samples

Content type
application/json
{
  • "message": "Missing or invalid PIN provided. Please ensure the PIN number is a string containing a 4 digit numeric value"
}

Unlock a locker

Unlocks the requested locker by ID. The call will return when the unlock is complete or has failed.

Request Body schema: application/json
lockerId
required
string

The unique ID of the locker as returned by /locationBookingsOrAvailability

userId
required
string

user ID

Responses

Request samples

Content type
application/json
{
  • "lockerId": "NGPs0GwP4zNS4DKpwsLj",
  • "userId": "1234"
}

Response samples

Content type
application/json
{
  • "message": "Missing or invalid required body value lockerId"
}