Skip to content

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_key

Errors ​

A request that fails gets an HTTP status of 400 or more, and a body of this shape.

FieldTypeRequiredDescription
errorstringyesA stable code for the error. Your code can test it.
messagestringyesA text for a developer. Do not test it in code, because one code can come with different texts.
detailsany valuenoMore 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

StatusMeaningBody
200The clubsA list of Club objects
401invalid_api_keyError
429rate_limitedError

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

NameTypeDescription
club_idstring, a UUIDThe club

Query parameters

NameTypeRequiredDescription
member_idstring, 1 to 64 charactersnoMarks this member's own compartment with mine

Replies

StatusMeaningBody
200The lockersA list of Locker objects
400validation_error or invalid_idError
401invalid_api_keyError
404club_not_foundError
429rate_limitedError

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

NameTypeRequiredDescription
member_idstring, 1 to 64 charactersnoOnly the rentals of this member
status"active", "completed"noOnly rentals in this state
club_idstring, a UUIDnoOnly rentals in this club
limitinteger, 1 to 100noAt most this many, 50 when left out
offsetinteger, 0 or morenoSkip this many

Replies

StatusMeaningBody
200The rentalsA list of Rental objects
400validation_errorError
401invalid_api_keyError
429rate_limitedError

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

FieldTypeDescription
member_idstring, 1 to 64 charactersYour 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_idstring, a UUIDThe 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

StatusMeaningBody
200The member held this compartment alreadyrental: Rental, grant: Grant
201The new rental and its first grantrental: Rental, grant: Grant
400validation_errorError
401invalid_api_keyError
404compartment_not_foundError
409compartment_unavailable, compartment_out_of_service or member_has_active_rentalError
429rate_limitedError

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

NameTypeDescription
idstring, a UUIDThe rental

Replies

StatusMeaningBody
200The rentalrental: Rental
400invalid_idError
401invalid_api_keyError
404rental_not_foundError
429rate_limitedError

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

NameTypeDescription
idstring, a UUIDThe rental

Request body

FieldTypeDescription
member_idstring, 1 to 64 charactersYour 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

StatusMeaningBody
201The grantgrant: Grant
400validation_error or invalid_idError
401invalid_api_keyError
403not_members_rentalError
404rental_not_foundError
409rental_not_activeError
429rate_limitedError

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

NameTypeDescription
idstring, a UUIDThe rental

Request body

The body has one of 2 forms.

With reason "member":

FieldTypeDescription
reason"member"The member ends the rental.
member_idstring, 1 to 64 charactersYour 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":

FieldTypeDescription
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

StatusMeaningBody
200The ended rentalrental: Rental
400validation_error or invalid_idError
401invalid_api_keyError
403not_members_rentalError
404rental_not_foundError
429rate_limitedError

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 ​

FieldTypeDescription
idstring, a UUIDThe ID of the club.
namestringThe name of the club.
timezonestringThe time zone of the club, as an IANA name.
auto_release_timestring, 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 ​

FieldTypeDescription
idstring, a UUIDThe ID of the locker.
namestringThe name of the locker.
countsobjectHow many compartments the locker has, by state.
counts.totalintegerAll compartments.
counts.availableintegerThe compartments that a member can claim now.
counts.occupiedintegerThe compartments that a member holds.
counts.out_of_serviceintegerThe compartments that are out of service.
compartmentslist of objectsEach compartment of the locker.
compartments[].idstring, a UUIDThe ID of the compartment. A claim needs it.
compartments[].positionintegerThe place of the compartment in its locker, from 1.
compartments[].labelstringThe 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[].minebooleanTrue when the member_id of the query holds this compartment.

Every field is always present.

Rental ​

FieldTypeDescription
idstring, a UUIDThe ID of the rental. The other calls for this rental need it.
member_idstring, 1 to 64 charactersYour 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_idstring, a UUIDThe club of the locker.
locker_idstring, a UUIDThe locker of the compartment.
locker_namestringThe name of that locker.
compartment_idstring, a UUIDThe compartment that the member holds.
compartment_labelstringThe label of that compartment.
status"active", "completed"active until the rental ends, then completed.
started_atstring, a date and time in ISO 8601The time of the claim.
unlocked_atstring, a date and time in ISO 8601 or nullThe time of the first opening. Null before it.
ended_atstring, a date and time in ISO 8601 or nullThe time when the rental ended. Null while it is active.
end_reason"member", "staff", "auto_release" or nullWho ended the rental: the member, your staff, or the daily auto-release. Null while it is active.

Every field is always present.

Grant ​

FieldTypeDescription
tokenstringThe 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_atstring, a date and time in ISO 8601The time when the grant stops working.

Every field is always present.