Introduction

Welcome to the BoxLock Control API! You can use our API to access information about your organization, manage locations, locks, barcodes, access activity logs and a variety of other things.

All of our endpoint examples are written in Shell using curl, which should allow them to be easily generalizable to any programming language you're using to integrate BoxLock into your application.

BoxLock uses API keys to allow access to the API.

Authentication

BoxLock uses API Key to allow access to the API. The API Info for your account is available under Account → API in BoxLock Control. If you need additional API Keys generated or the API Key is not populated, please reach out to your BoxLock Customer Success Representative.

The BoxLock Control API expects the API Key to be included in all API requests to the server. X-API-Key as the header key and your API Key as the value.

List Filtering

You can filter most of our data objects by their field properties (ie locks, barcodes, and packages).

• Supported Operators - eq, gt, gte, lt, lte, ne, between, notBetween, in, notIn, overlap, contains, contained, like
• Paging - limit,offset
• Sorting - sort (sort=updatedAt or sort=-updatedAt)

Example Requests

GET https://apis.getboxlock.com/barcode/v2/control/barcodes/?name=eq:MyBarcode&locationId=eq:{id}&sort=updatedAt&limit=10&offset=1

GET https://apis.getboxlock.com/lock/v2/control/locks/activities/?activityType=in:18,20

GET https://apis.getboxlock.com/lock/v2/control/locks/activities/?createdAt=between:2021-03-18,2021-03-27

Webhooks

Properties

• endpointType - helps to identify the object type
• eventType - the type of event that triggered the notification
• object - data object for the event message (Package)

Webhook Payload JSON Representation

{
	"id": 1234,
	"endpointType": "string",
	"eventType": "package.delivery.secured",
	"object": {
		"id": 123,
		"userId": 456,
		"trackingNumber": "DK3I3DKC",
		"carrierName": "Carrier Name",
		"shipperName": "Shipper Name",
		"url": "string",
		"description": "Cool Package",
		"status": "delivered",
		"deliveredAt": 2020 - 03 - 19 T07: 22 Z,
		"createdAt": 2020 - 03 - 19 T07: 22 Z,
		"updatedAt": 2020 - 03 - 19 T07: 22 Z
	},
	"createdAt": 2020 - 03 - 19 T07: 22 Z,
}

API Reference

Users

A user represents a BoxLock Control organization user.

Methods

• info - returns info about a BoxLock Control User
• list - returns a list of BoxLock Control users
• insert - create a new user record
• update - update a user record
• delete - delete a user record

Properties

• id - unique identifier
• name - the users full name
• email - the users email address
• locationId - the id of the location the user is assigned to
• group - the group/role assigned to the user

GET /users/{id}

This endpoint retrieves an individual user.

Example Request

curl -X GET https://apis.getboxlock.com/user/v2/control/users{id}
-H “X-API-Key: <ApiKey>”

The above command returns JSON structured like this:

{
	"id": "int",
	"name": "string",
	"email": "string",
	"locationId": "int",
	"group": "string",
	"createdAt": "date",
	"updatedAt": "date"

}

GET /users/

This endpoint retrieves a list of users for the currently authenticated organization.

Example Request

curl -X GET https://apis.getboxlock.com/user/v2/control/users
-H “X-API-Key: <ApiKey>”

The above command returns JSON structured like this:

{
	"data": [{
		"id": "int",
		"name": "string",
		"email": "string",
		"locationId": "int",
		"group": "string",
		"createdAt": "date",
		"updatedAt": "date"
	}]
}

POST /users/

This endpoint creates a user for the currently authenticated organization.

Properties

• name - first name and last name of the user
• email - email address for the user
• locationId - the location assigned to the user. not required. (Only used for users create in the LocationAdmin group)
• group
• OrganizationAdmin - Can write, delete, update an object for assigned Org.
• OrganizationManager - Same as OrganizationAdmin but can’t create users.
• OrganizationAnalyst - Can read an object for Org.
• LocationAdmin - Can write, delete, update an object for assigned location.

Example Request

curl -X GET https://apis.getboxlock.com/user/v2/control/users
-H “X-API-Key: <ApiKey>”
-d {"name":"John Smith","email":"john.smith@getboxlock.com","locationId":3,"group":"LocationAdmin"}

The above command returns JSON structured like this:

{
		"id": "int",
		"name": "string",
		"email": "string",
		"locationId": "int",
		"group": "string",
		"createdAt": "date",
		"updatedAt": "date"
}

PUT /users/{id}

This endpoint updates a user for the currently authenticated organization.

Properties

• name - first name and last name of the user
• email - email address for the user
• locationId - the location assigned to the user. not required. (Only used for users create in the LocationAdmin group)
• group
• OrganizationAdmin - Can write, delete, update an object for assigned Org.
• OrganizationManager - Same as OrganizationAdmin but can’t create users.
• OrganizationAnalyst - Can read an object for Org.
• LocationAdmin - Can write, delete, update an object for assigned location.

Example Request

curl -X GET https://apis.getboxlock.com/user/v2/control/users
-H “X-API-Key: <ApiKey>”
-d {"name":"John Smith"}

The above command returns JSON structured like this:

{
		"id": "int",
		"name": "string",
		"email": "string",
		"locationId": "int",
		"group": "string",
		"createdAt": "date",
		"updatedAt": "date"
}

DELETE /users/{id}

This endpoint deletes a user for the currently authenticated organization.

Properties

• id - unique identifier

Example Request

curl -X DELETE https://apis.getboxlock.com/user/v2/control/users/{id}
-H “X-API-Key: <ApiKey>”

The above command returns JSON structured like this:

if successful, this request returns a 204 (No content)

Locks

A lock represents a BoxLock users lock.

Methods

• info - returns info about a location
• list - list of locations

Properties

• id - unique identifier
• userId - id for the lock owner
• locationId - the location the lock is assigned to
• name - default name for a lock
• niceName - user friendly name for a lock
• lockOpen - lock state 0=closed, 1=open, 2=unknown
• batteryLevel - lock battery level 0-100
• batteryCharging - the charging state of the lock
• disconnectedAt - timestamp when the lock disconnected

GET /locks/{id}

This endpoint retrieves a lock for the currently authenticated organization.

Properties

• id - unique identifier

Example Request

curl -X GET https://apis.getboxlock.com/lock/v2/control/locks/{id}
-H “X-API-Key: <ApiKey>”

The above command returns JSON structured like this:

{
		"id": "int",
		"name": "string",
		"locationId": "int",
		"niceName": "string",
		"lockOpen": "enum",
		"batteryLevel": "int",
		"batteryCharging": "int",
    "disconnectedAt": "date",
		"createdAt": "date",
		"updatedAt": "date"
}

GET /locks

This endpoint retrieves a list of locks for the currently authenticated organization.

Example Request

curl -X GET https://apis.getboxlock.com/lock/v2/control/locks
-H “X-API-Key: <ApiKey>”

The above command returns JSON structured like this:

{
	"data": [{
		"id": "int",
		"name": "string",
		"locationId": "int",
		"niceName": "string",
		"lockOpen": "enum",
		"batteryLevel": "int",
		"batteryCharging": "int",
		"disconnectedAt": "date",
		"createdAt": "date",
		"updatedAt": "date"
	}]
}

Activities

An activity represents a logging of lock events.

Methods

• info - returns info about a lock
• list - returns a list of locks

Properties

• id - unique identifier
• activityType - unique activity code
• userId - id for the lock owner
• organizationId - the organization that owns the lock
• locationId - the location associated with the activity
• barcodeId - the barcode associated with the activity
• lockId - the lock associated with the activity
• title - activity title
• details - Additional details about the activity
• modeMmc - Mobile-tomobile convergence when the activity happened
• modeLac - Mobile Network Code when the activity happened
• modeLac - Location Area Code when the activity happened
• modeCid - Base transceiver station identifier
• lat - latitude value when the activity happened
• lng - longitude value when the activity happened

GET /locks/{id}/activities/{activityId}

This endpoint retrieves a lock activity for the currently authenticated organization.

Property

• id - lock unique identifier
• activityId - lock activity unique identifier

Example Request

curl -X GET https://apis.getboxlock.com/lock/v2/control/locks/{id}/activities/{id}
-H “X-API-Key: <ApiKey>”

The above command returns JSON structured like this:

{

	"id": "int",
	"activityType": "int",
	"userId": "int",
	"organizationId": "int",
	"locationId": "int",
	"barcodeId": "int",
	"title": "string",
	"modeMmc": "int",
	"modeMnc": "int",
	"modeLac": "int",
	"modeCid": "int",
	"lat": "float",
	"lng": "float",
	"createdAt": "date",
	"updatedAt": "date"

}

GET /locks/{id}/activities

This endpoint retrieves a list of lock activities for the currently authenticated organization.

Properties

• id - lock unique identifier

Example Request

curl -X GET https://apis.getboxlock.com/lock/v2/control/locks/{id}/activities/{id}
-H “X-API-Key: <ApiKey>”

Lock Activity Codes & Descriptions

1. Package Delivery
2. User Barcode Scan
3. Unlock over Bluetooth
4. Master Barcode Scan
5. User Added to Account
6. Battery Issue
7. Wifi Issue
8. Lock Issue (Left open, etc)
9. Unrecognized Package/Barcode Scanned
10. Own Package Scanned When Not "Out for Delivery"
11. Own Package Scanned When Already Delivered
12. Expired Barcode Scanned
13. Unauthorized Unlock Attempt
14. Lock Closed
15. Expired Press Unlock Access
16. Successful Press Unlock
17. Status Update
18. Parsyl Update
19. Lock Already Connected
20. Lock Added

Lock Access Actions

A lockAccess represents an action that can be taken on a Lock. Currently the only action that is allowed is “Push to Unlock”.

Methods

• insert - returns info about a BoxLock Control user.

Properties

• id - unique identifier
• lockId - locks unique identifier
• accessType - always 0
• duration - access duration in seconds
• accessor - always 1

POST /lockaccess

This endpoint creates a lockAccess record for the currently authenticated organization target lock. (“Push To Open”)

Properties

• lockID - target lock to allow access
• accessType - type of access needed (0 is “Push to Unlock”)
• accessor - the type of accessor (should be 1)
• duration - how long the auction in valid for

Example Request

curl -X POST https://apis.getboxlock.com/lockaccess/v2/control/lockaccess
-H “X-API-Key: <ApiKey>”
-d {“lockId": 1111,”accessType":0,"accessor":1,"duration":30}

The above command returns JSON structured like this:

{
	"id": "int",
	"lockId": "int",
	"duration": "int",
	"accessType": "int",
	"Accessor": "int",
	"createdAt": "date",
	"updatedAt": "date"
}

Packages

A package represents a parcel belonging to a BoxLock user.

Methods

• info - returns info about a package
• insert - create one or more packages
• update - update a package
• delete - delete a package

Properties

• id - unique identifier
• userId - id for the package owner
• locationId - the location the package is assigned to
• trackingNumber - tracking identifier provided by the shipper
• carrierName - name for the carrier
• shipperName - name for the shipper
• url - the tracking url provided by the carrier
• description - a description for the package.
• status - can be “out_for_delivery”, “in_transit", or "delivered"
• deliveredAt - the stamp for a delivered package

GET /packages/{id}

This endpoint retrieves a package for the currently authenticated organization.

Request Parameters

• id - unique identifier
• trackingNumber - tracking number can be used in place of the {id}

Example Request

curl -X GET https://apis.getboxlock.com/package/v2/control/packages/1234
-H “X-API-Key: <ApiKey>”

The above command returns JSON structured like this:

{
	"id": int,
	"userId": int,
	"locationID": int,
	"trackingNumber": int,
	"carrierName": "string",
	"shipperName": "string",
	"url": "string",
	"description": "string",
	"status": "string"
	"deliveredAt": date,
	"createdAt": date,
	"updatedAt": date
}

POST /packages

This endpoint creates a package for the currently authenticated organization.

Request Parameters

• trackingNumber - tracking identifier provided by the shipper
• locationId - the assigned location for the package
• carrierName - name for the carrier
• shipperName - name for the shipper
• url - the tracking url provided by the carrier
• description - a description for the package.
• status - can be “out_for_delivery”, “in_transit", or "delivered"

Example Request

curl -X POST https://apis.getboxlock.com/package/v2/control/packages
-H “X-API-Key: <ApiKey>”
-d {"trackingNumber":"374DJNWLKEID","carrierName":"Carrier Name","shipperName":"Shipper Name","url":"https://apis.getboxlock.com/v2/control/packages","description":"My Package","status":"out_for_delivery"}

The above command returns JSON structured like this:

{
	"id": int,
	"userId": int,
	"locationID": int,
	"trackingNumber": int,
	"carrierName": "string",
	"shipperName": "string",
	"url": "string",
	"description": "string",
	"status": "string"
	"deliveredAt": date,
	"createdAt": date,
	"updatedAt": date
}

POST /import

This endpoint creates multiple packages for the currently authenticated organization.

Request Body

Parameters

• items[Package] - list of packages to create

Example Request

curl -X POST https://apis.getboxlock.com/package/v2/control/import
-H “X-API-Key: <ApiKey>”
-d [{"userId":456,"trackingNumber":"374DJNWLKEID","carrierName":"Carrier Name","shipperName":"Shipper Name","url":"https://apis.getboxlock.com/v2/control/packages/import","description":"My Package","status":"out_for_delivery"}]

The above command returns JSON structured like this:

{
	"id": int,
	"userId": int,
	"locationID": int,
	"trackingNumber": int,
	"carrierName": "string",
	"shipperName": "string",
	"url": "string",
	"description": "string",
	"status": "string"
	"deliveredAt": date,
	"createdAt": date,
	"updatedAt": date
}

PUT /packages/{id}

This endpoint updates a package for the currently authenticated organization.

Request Body

Parameters

• url - the tracking url provided by the carrier
• description - a description for the package.
• status - can be “out_for_delivery”, “in_transit", or "delivered"

Example Request

curl -X PUT https://apis.getboxlock.com/package/v2/control/packages/1234
-H “X-API-Key: <ApiKey>”
-d {"url":"http://track.getboxlock.com/barcodes/barcodeVis.php?barcode=D8DJSKKDIE","description":"My Package","status":"out_for_delivery"}

The above command returns JSON structured like this:

{
	"id": int,
	"userId": int,
	"locationID": int,
	"trackingNumber": int,
	"carrierName": "string",
	"shipperName": "string",
	"url": "string",
	"description": "string",
	"status": "string"
	"deliveredAt": date,
	"createdAt": date,
	"updatedAt": date
}

DELETE /packages/{id}

This endpoint deletes a package for the currently authenticated organization.

Request Body

Parameters

• id - unique identifier
• trackingNumber - tracking number can be used in place of the {id}

Example Request

curl -X DELETE https://apis.getboxlock.com/package/v2/control/packages/1234
-H “X-API-Key: <ApiKey>

The above command returns JSON structured like this:

If successful, this request returns a 204 (No Content)

Locations

A location represents a place within an organizations hierarchy.

Methods

• info - returns info about a location
• list - list of locations
• insert - create one or more locations
• update - update a location
• delete - delete a location

Properties

• id - unique identifier
• organizationId - identifier for the location's organization owner
• address1 - street address for the location
• address2 - additional address information (ex. Suite, Apt, Unit)
• state - the state for the location
• city - the city for the location
• zip - the zip/postal code for the location
• country - the country for the location
• contactName - the name of the primary contact for the location
• contactPhoneNumber - the name of the primary contact for the location
• status - Indicates whether the location is active

GET /locations/{id}

This endpoint retrieves a location for the currently requesting organization

Example Request

curl -X GET https://apis.getboxlock.com/location/v2/control/locations/1234
-H “X-API-Key: <ApiKey>”

Example Response

{
	"id": "int",
	"organizationId": "int",
	"address1": "string",
	"address2": "string",
	"state": "string",
	"city": "string",
	"zip": "string",
	"country": "string",
	"contactName": "string",
	"contactPhoneNumber": "string",
	"status": "int",
	"createdAt": "date",
	"updatedAt": "date"

}

GET /locations

This endpoint retrieves a locations for the currently requesting organization.

Example Request

curl -X GET https://apis.getboxlock.com/location/v2/control/locations
-H “X-API-Key: <ApiKey>”

Example Response

{
	"data": [{
		"id": "int",
	"organizationId": "int",
	"address1": "string",
	"address2": "string",
	"state": "string",
	"city": "string",
	"zip": "string",
	"country": "string",
	"contactName": "string",
	"contactPhoneNumber": "string",
	"status": "int",
	"createdAt": "date",
	"updatedAt": "date"
	}]
}

POST /locations

This endpoint creates a location for the currently requesting organization.

Request Body

Parameters

• address1 - tracking identifier provided by the shipper
• address2 - additional address information (ex. Suite, apt)
• state - the state of the location
• city - the tracking url provided by the carrier
• zip - the zip/postal code for the location
• country - the country for the location
• contactName - primary contacts name
• contactPhoneNumber - primary contact phone number (format ex. +17708515123)
• status - can be 0 (inactive) or 1 (active)

Example Request

curl -X POST https://apis.getboxlock.com/location/v2/control/locations/1234
-H “X-API-Key: <ApiKey>”
-d {“address1":"124 Fairlane Way”,"address2":"Suite 127”,”state":"GA","city":"Atlanta","zip":"30309","country":"USA", “contactName”: “John Doe”, “contactPhoneNumber”: “+17708515123”}

The above command returns JSON structured like this:

{
	"id": "int",
	"organizationId": "int",
	"address1": "string",
	"address2": "string",
	"state": "string",
	"city": "string",
	"zip": "string",
	"country": "string",
	"contactName": "string",
	"contactPhoneNumber": "string",
	"status": "int",
	"createdAt": "date",
	"updatedAt": "date"

}

PUT /locations/{id}

This endpoint updates a location for the currently requesting organization.

Request Body

Parameters

• address1 - tracking identifier provided by the shipper
• address2 - additional address information (ex. Suite, apt)
• state - the state of the location
• city - the tracking url provided by the carrier
• zip - the zip/postal code for the location
• country - the country for the location
• contactName - primary contacts name
• contactPhoneNumber - primary contact phone number (format ex. +17708515123)
• status - can be 0 (inactive) or 1 (active)

Example Request

curl -X PUT https://apis.getboxlock.com/location/v2/control/locations/1234
-H “X-API-Key: <ApiKey>”
-d {“address1":"124 Fairlane Court”}

The above command returns JSON structured like this:

{
	"id": "int",
	"organizationId": "int",
	"address1": "string",
	"address2": "string",
	"state": "string",
	"city": "string",
	"zip": "string",
	"country": "string",
	"contactName": "string",
	"contactPhoneNumber": "string",
	"status": "int",
	"createdAt": "date",
	"updatedAt": "date"

}

DELETE /locations/{id}

This endpoint deletes a package for the currently authenticated organization.

Request Body

Parameters

• id - unique identifier

Example Request

curl -X DELETE https://apis.getboxlock.com/package/v2/control/locations/1234
-H “X-API-Key: <ApiKey>

The above command returns JSON structured like this:

If successful, this request returns a 204 (No Content)

Barcodes

A barcode represents a code used for access control of a BoxLock user’s lock.

Methods

• info - returns info about a location
• list - list of locations
• insert - create a barcode for lock access
• update - update a barcode
• delete - delete a barcode

Properties

• id - unique identifier
• userID - identifier for the lock owner
• lockID - the lock to assign the barcode to (can be null)
• locationID - the location to assign the barcode to (can be null)
• barcode - barcode to be created
• accessType - set to 1=unlimited use barcode, 2=time-based barcode, 3=use-based barcode
• enabled - the active status
• enabledFrom - applicable only for access_type 2, this is the date the barcode starts to be valid (YYYY-MM-DD)
• enabledTo - applicable only for access_type 2, this is the date the barcode is no longer valid (YYYY-MM-DD)
• useLimit -
• uses - applicable only for access_type 3. This is the number of uses the barcode is valid for.

GET /barcodes/{id}

This endpoint retrieves info about a barcode the currently authenticated organization has attached to their lock.

Request Parameters

• id - unique identifier
• barcode - barcode can be used in place of the {id}

Example Request

curl -X GET https://apis.getboxlock.com/barcode/v2/control/barcodes/4DKDIE8
-H “X-API-Key: <ApiKey>”

The above command returns JSON structured like this:

{
	"id": int,
	"userId": int,
	"lockId": int,
	"locationId": int,
	"barcode": "string",
	"accessType": enum,
	"enabled": boolean,
	"enabledFrom": date,
	"enabledTo": date,
	"useLimit": int,
	"uses": int,
	"createdAt": date,
	"updatedAt": date

}

GET /barcodes

This endpoint retrieves a list of barcodes the currently authenticated organization has attached to their lock.

Example Request

curl -X GET https://apis.getboxlock.com/barcode/v2/control/barcodes
-H “X-API-Key: <ApiKey>”

The above command returns JSON structured like this:

{
	"data": [{
		"id": int,
		"userId": int,
		"lockId": int,
		"locationId": int,
		"barcode": "string",
		"accessType": enum,
		"enabled": boolean,
		"enabledFrom": date,
		"enabledTo": date,
		"useLimit": int,
		"uses": int,
		"createdAt": date,
		"updatedAt": date

	}]
}

POST /barcodes

This endpoint creates a barcode for the currently authenticated organization has attached to their lock.

Request Body

Parameters

• barcode - barcode to be created
• accessType - set to 1=unlimited use barcode, 2=time-based barcode, 3=use-based barcode.
• lockId - the lock to assign the barcode to (can be null)
• locationId - the location to assign the barcode to (can be null)
• uses - applicable only for access_type 3. This is the number of uses the barcode is valid for.
• enabledFrom - applicable only for access_type 2, this is the date the barcode starts to be valid (YYYY-MM-DD)
• enabledTo - applicable only for access_type 2, this is the date the barcode is no longer valid (YYYY-MM-DD)

Example Request

curl -X POST https://apis.getboxlock.com/barcode/v2/control/barcodes/4DKDIE8
-H “X-API-Key: <ApiKey>”
-d {“barcode”: “DKEIE736”, “accessType”: 1}

The above command returns JSON structured like this:

{
	"id": int,
	"userId": int,
	"lockId": int,
	"locationId": int,
	"barcode": "string",
	"accessType": enum,
	"enabled": boolean,
	"enabledFrom": date,
	"enabledTo": date,
	"useLimit": int,
	"uses": int,
	"createdAt": date,
	"updatedAt": date

}

PUT /barcodes

This endpoint updates a barcode for the currently authenticated organization.

Request Body

Parameters

• barcode - barcode to be U
• accessType - set to 1=unlimited use barcode, 2=time-based barcode, 3=use-based barcode.
• lockId - the lock to assigned the barcode to (can be null)
• locationId - the location to assigned the barcode to (can be null)
• uses - applicable only for access_type 3. This is the number of uses the barcode is valid for.
• enabledFrom - applicable only for access_type 2, this is the date the barcode starts to be valid (YYYY-MM-DD)
• enabledTo - applicable only for access_type 2, this is the date the barcode is no longer valid (YYYY-MM-DD)

Example Request

curl -X PUT https://apis.getboxlock.com/barcode/v2/control/barcodes/4DKDIE8
-H “X-API-Key: <ApiKey>”
-d {“barcode”: “DKEIE736”, “accessType”: 1}

The above command returns JSON structured like this:

{
	"id": int,
	"userId": int,
	"lockId": int,
	"locationId": int,
	"barcode": "string",
	"accessType": enum,
	"enabled": boolean,
	"enabledFrom": date,
	"enabledTo": date,
	"useLimit": int,
	"uses": int,
	"createdAt": date,
	"updatedAt": date

}

DELETE /barcodes/{id}

This endpoint delete a barcode the currently authenticated organization has attached to their lock.

Request Body

Parameters

• id - unique identifier
• barcodes - barcode can be used in place of the {id}

Example Request

curl -X DELETE https://apis.getboxlock.com/barcode/v2/control/barcodes/4DKDIE8
-H “X-API-Key: <ApiKey>”

The above command returns JSON structured like this:

If successful, this request returns a 204 (No Content)