Theme
Integration API
For a partner's server. The API key is a secret and must never sit in an app. A test key sees only test clubs, and a live key sees only live clubs. No reply holds a lock ID, a Bluetooth address or a PIN. One key can send 600 requests a minute. Above that, a call fails with rate_limited, and the header Retry-After has the seconds to wait.
Every address starts with https://api.clevibox.ro/integration/v1. Requests and replies are JSON.
Authentication
Send your API key as a bearer token with each request. A key starts with cbx_test_ or cbx_live_.
http
Authorization: Bearer cbx_test_your_keyErrors
A request that fails gets an HTTP status of 400 or more, and a body of this shape.
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes | A stable code for the error. Your code can test it. |
message | string | yes | A text for a developer. Do not test it in code, because one code can come with different texts. |
details | any value | no | More data, for some errors. For validation_error, details.field names the wrong field. |
json
{
"error": "rental_not_active",
"message": "This rental has ended."
}Clubs
List the clubs of this key
GET/clubs
Replies
| Status | Meaning | Body |
|---|---|---|
200 | The clubs | A list of Club objects |
401 | invalid_api_key | Error |
429 | rate_limited | Error |
Example of a 200 reply:
json
[
{
"id": "cc2585df-74ec-4b8b-83e3-d9f1f793ee9c",
"name": "Club North",
"timezone": "Europe/Bucharest",
"auto_release_time": "23:30"
}
]List the lockers of a club, with their compartments
GET/clubs/{club_id}/lockers
Path parameters
| Name | Type | Description |
|---|---|---|
club_id | string, a UUID | The club |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
member_id | string, 1 to 64 characters | no | Marks this member's own compartment with mine |
Replies
| Status | Meaning | Body |
|---|---|---|
200 | The lockers | A list of Locker objects |
400 | validation_error or invalid_id | Error |
401 | invalid_api_key | Error |
404 | club_not_found | Error |
429 | rate_limited | Error |
Example of a 200 reply:
json
[
{
"id": "8bca6dad-a231-40fd-80bf-5ff9ff16aa79",
"name": "Locker room A",
"counts": {
"total": 40,
"available": 31,
"occupied": 8,
"out_of_service": 1
},
"compartments": [
{
"id": "d955ef4d-f6a0-4f22-a875-91028b69339c",
"position": 17,
"label": "17",
"size": "M",
"status": "available",
"mine": false
}
]
}
]Rentals
List rentals, newest first
GET/rentals
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
member_id | string, 1 to 64 characters | no | Only the rentals of this member |
status | "active", "completed" | no | Only rentals in this state |
club_id | string, a UUID | no | Only rentals in this club |
limit | integer, 1 to 100 | no | At most this many, 50 when left out |
offset | integer, 0 or more | no | Skip this many |
Replies
| Status | Meaning | Body |
|---|---|---|
200 | The rentals | A list of Rental objects |
400 | validation_error | Error |
401 | invalid_api_key | Error |
429 | rate_limited | Error |
Example of a 200 reply:
json
[
{
"id": "e0c146e3-d964-4bd1-8bf0-ea6b5590d92b",
"member_id": "m-48213",
"club_id": "cc2585df-74ec-4b8b-83e3-d9f1f793ee9c",
"locker_id": "8bca6dad-a231-40fd-80bf-5ff9ff16aa79",
"locker_name": "Locker room A",
"compartment_id": "d955ef4d-f6a0-4f22-a875-91028b69339c",
"compartment_label": "17",
"status": "active",
"started_at": "2026-03-14T09:26:53.000Z",
"unlocked_at": null,
"ended_at": null,
"end_reason": null
}
]Claim: one member takes one free compartment
POST/rentals
The first claim of a member ID creates the member. A repeat by the same member for the same compartment returns 200 with the same rental and a new grant. With member_has_active_rental, details has the rental_id and the compartment_id of the rental that the member holds.
Request body
| Field | Type | Description |
|---|---|---|
member_id | string, 1 to 64 characters | Your own ID for the member. It must stay the same for a member. It must not be a name, a phone number or an email address. |
compartment_id | string, a UUID | The compartment that the member takes. The list of the lockers has its ID. |
Every field is required.
json
{
"member_id": "m-48213",
"compartment_id": "d955ef4d-f6a0-4f22-a875-91028b69339c"
}Replies
| Status | Meaning | Body |
|---|---|---|
200 | The member held this compartment already | rental: Rental, grant: Grant |
201 | The new rental and its first grant | rental: Rental, grant: Grant |
400 | validation_error | Error |
401 | invalid_api_key | Error |
404 | compartment_not_found | Error |
409 | compartment_unavailable, compartment_out_of_service or member_has_active_rental | Error |
429 | rate_limited | Error |
Example of a 200 or 201 reply:
json
{
"rental": {
"id": "e0c146e3-d964-4bd1-8bf0-ea6b5590d92b",
"member_id": "m-48213",
"club_id": "cc2585df-74ec-4b8b-83e3-d9f1f793ee9c",
"locker_id": "8bca6dad-a231-40fd-80bf-5ff9ff16aa79",
"locker_name": "Locker room A",
"compartment_id": "d955ef4d-f6a0-4f22-a875-91028b69339c",
"compartment_label": "17",
"status": "active",
"started_at": "2026-03-14T09:26:53.000Z",
"unlocked_at": null,
"ended_at": null,
"end_reason": null
},
"grant": {
"token": "cbxg_example",
"expires_at": "2026-03-14T09:28:53.000Z"
}
}Read one rental
GET/rentals/{id}
Path parameters
| Name | Type | Description |
|---|---|---|
id | string, a UUID | The rental |
Replies
| Status | Meaning | Body |
|---|---|---|
200 | The rental | rental: Rental |
400 | invalid_id | Error |
401 | invalid_api_key | Error |
404 | rental_not_found | Error |
429 | rate_limited | Error |
Example of a 200 reply:
json
{
"rental": {
"id": "e0c146e3-d964-4bd1-8bf0-ea6b5590d92b",
"member_id": "m-48213",
"club_id": "cc2585df-74ec-4b8b-83e3-d9f1f793ee9c",
"locker_id": "8bca6dad-a231-40fd-80bf-5ff9ff16aa79",
"locker_name": "Locker room A",
"compartment_id": "d955ef4d-f6a0-4f22-a875-91028b69339c",
"compartment_label": "17",
"status": "active",
"started_at": "2026-03-14T09:26:53.000Z",
"unlocked_at": null,
"ended_at": null,
"end_reason": null
}
}A new grant for the member who holds the rental
POST/rentals/{id}/grants
Call it each time the member taps Open. Take the member ID from your own sign-in session, not from the body of the app's request.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string, a UUID | The rental |
Request body
| Field | Type | Description |
|---|---|---|
member_id | string, 1 to 64 characters | Your own ID for the member. It must stay the same for a member. It must not be a name, a phone number or an email address. |
Every field is required.
json
{
"member_id": "m-48213"
}Replies
| Status | Meaning | Body |
|---|---|---|
201 | The grant | grant: Grant |
400 | validation_error or invalid_id | Error |
401 | invalid_api_key | Error |
403 | not_members_rental | Error |
404 | rental_not_found | Error |
409 | rental_not_active | Error |
429 | rate_limited | Error |
Example of a 201 reply:
json
{
"grant": {
"token": "cbxg_example",
"expires_at": "2026-03-14T09:28:53.000Z"
}
}End the rental and free the compartment
POST/rentals/{id}/release
It does not move the latch. A release of an ended rental returns 200 and changes nothing.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string, a UUID | The rental |
Request body
The body has one of 2 forms.
With reason "member":
| Field | Type | Description |
|---|---|---|
reason | "member" | The member ends the rental. |
member_id | string, 1 to 64 characters | Your own ID for the member. It must stay the same for a member. It must not be a name, a phone number or an email address. |
Every field is required.
json
{
"reason": "member",
"member_id": "m-48213"
}With reason "staff":
| Field | Type | Description |
|---|---|---|
reason | "staff" | Your staff end the rental, for example when the member checks out of the club. |
Every field is required.
json
{
"reason": "staff"
}Replies
| Status | Meaning | Body |
|---|---|---|
200 | The ended rental | rental: Rental |
400 | validation_error or invalid_id | Error |
401 | invalid_api_key | Error |
403 | not_members_rental | Error |
404 | rental_not_found | Error |
429 | rate_limited | Error |
Example of a 200 reply:
json
{
"rental": {
"id": "e0c146e3-d964-4bd1-8bf0-ea6b5590d92b",
"member_id": "m-48213",
"club_id": "cc2585df-74ec-4b8b-83e3-d9f1f793ee9c",
"locker_id": "8bca6dad-a231-40fd-80bf-5ff9ff16aa79",
"locker_name": "Locker room A",
"compartment_id": "d955ef4d-f6a0-4f22-a875-91028b69339c",
"compartment_label": "17",
"status": "completed",
"started_at": "2026-03-14T09:26:53.000Z",
"unlocked_at": "2026-03-14T09:27:08.000Z",
"ended_at": "2026-03-14T11:02:41.000Z",
"end_reason": "member"
}
}Objects
Club
| Field | Type | Description |
|---|---|---|
id | string, a UUID | The ID of the club. |
name | string | The name of the club. |
timezone | string | The time zone of the club, as an IANA name. |
auto_release_time | string, pattern ^\d\d:\d\d$ | The local time of the daily auto-release, as HH:MM. At that time, each active rental of the club ends. |
Every field is always present.
Locker
| Field | Type | Description |
|---|---|---|
id | string, a UUID | The ID of the locker. |
name | string | The name of the locker. |
counts | object | How many compartments the locker has, by state. |
counts.total | integer | All compartments. |
counts.available | integer | The compartments that a member can claim now. |
counts.occupied | integer | The compartments that a member holds. |
counts.out_of_service | integer | The compartments that are out of service. |
compartments | list of objects | Each compartment of the locker. |
compartments[].id | string, a UUID | The ID of the compartment. A claim needs it. |
compartments[].position | integer | The place of the compartment in its locker, from 1. |
compartments[].label | string | The label of the compartment, for example the number on its door. |
compartments[].size | "S", "M", "L" | The size of the compartment: small, medium or large. |
compartments[].status | "available", "occupied", "out_of_service" | A member can claim only an available compartment. |
compartments[].mine | boolean | True when the member_id of the query holds this compartment. |
Every field is always present.
Rental
| Field | Type | Description |
|---|---|---|
id | string, a UUID | The ID of the rental. The other calls for this rental need it. |
member_id | string, 1 to 64 characters | Your own ID for the member. It must stay the same for a member. It must not be a name, a phone number or an email address. |
club_id | string, a UUID | The club of the locker. |
locker_id | string, a UUID | The locker of the compartment. |
locker_name | string | The name of that locker. |
compartment_id | string, a UUID | The compartment that the member holds. |
compartment_label | string | The label of that compartment. |
status | "active", "completed" | active until the rental ends, then completed. |
started_at | string, a date and time in ISO 8601 | The time of the claim. |
unlocked_at | string, a date and time in ISO 8601 or null | The time of the first opening. Null before it. |
ended_at | string, a date and time in ISO 8601 or null | The time when the rental ended. Null while it is active. |
end_reason | "member", "staff", "auto_release" or null | Who ended the rental: the member, your staff, or the daily auto-release. Null while it is active. |
Every field is always present.
Grant
| Field | Type | Description |
|---|---|---|
token | string | The grant. Return it to your app, and hand it to the SDK there. It works once, and it lives 2 minutes. Do not store it, and do not log it. |
expires_at | string, a date and time in ISO 8601 | The time when the grant stops working. |
Every field is always present.
