API and Third-Party Software Integrations

LabKey is equipped with an API layer for communicating and exchanging data with external software. The API structure lets you automate processes and connect external systems securely.

The technical design is simple and robust: you can connect your own software to your installation’s API layer and manage it independently.

Foto 7

The API structure lets you carry out operations that simulate almost all the functions of the Manage panel supplied with the KIT. All calls must be activated and must originate from an authorized IP address.

Below you’ll find the complete guide to all available calls, organized by functional area. The same documentation is also available in interactive format on Postman: click here!.

NB: a hardened version of the API service is also available (API PRO), which lets you keep logs of API calls and issue remote opening commands — see the API Pro section or contact us to learn more.

For practical integration examples with booking systems, PMS, payment and reservation platforms, see Common Integrations: How-To Guide.

Authentication

All calls (except the status check) require a Bearer token, obtained via the authorize call and passed as a header in subsequent requests.

  • The token is valid for 1 hour: it must be renewed periodically by repeating the authorize call.
  • There is no limit to the number of calls you can make.
  • Possible errors on the authorize call: unauthorized IP or incorrect secret_key (invalid_access), incorrect credentials (invalid_credentials), generic error (could not create token).
  • Possible errors on other calls: expired, invalid, or missing token (invalid_token). Any specific errors are indicated in the messages field of the JSON response.

POST /api/v2/authorize — Get the Token

Returns the Bearer token to use for all subsequent calls.

  • Required parameters: email (operator’s email), password (operator’s password), secret_key (associated with the authorized IP; found on the panel under API / Setup)
  • 200 response: token
  • 401 response: invalid_credentials (incorrect email or password), invalid_credentials2 (unauthorized IP or incorrect secret_key), invalid_access1 (missing secret_key)

GET /api/v2/ — Status Check

Checks that the panel is active and working (prints Test). Requires no authentication or parameters.

Users

PUT /api/v2/adduser — Create New User

Creates a new user on the panel.

  • Required parameters: name, surname
  • Optional parameters: email, phone, prefix (URL-encoded country code, e.g. +39 → %2b39), tags (array; each comma is replaced with an underscore), status (1 = enabled, 0 = disabled), fields (array of custom fields in the format fields[field_id]=value)

PUT /api/v2/updateuser — Update User

Updates the data of an existing user.

  • Required parameters: user_id, name, surname
  • Optional parameters: email, phone, prefix, tags, status (1 = enabled, 0 = disabled), fields (array of custom fields, same format as AddUser)

DELETE /api/v2/deleteuser — Delete User

Deletes a user from the panel.

  • Required parameters: user_id
  • 200 response: user deleted successfully
  • 400 response: user not found

GET /api/v2/getusers — List Users

Returns the data of all users on the panel, or of a specific one if the optional parameter is passed.

  • Optional parameters: user_id, tags (filters users by tag), getGrantInfo (if 1, also includes details of the associated access grants)
  • 404 response: no users found

GET /api/v2/users/getStatus — User Status

Returns whether a user is enabled or disabled.

  • Parameters: user_id

POST /api/v2/users/changeStatus — Change User Status (not yet available)

If status = 1 the user is enabled for access, if status = 0 they are disabled.

  • Parameters: user_id, status (1 = enabled, 0 = disabled)

Groups

GET /api/v2/getGroup — List Groups

Returns the data of all groups on the panel, or of one or more specific ones if the optional parameter is passed.

  • Optional parameters: group_id (can be an array)
  • 404 response: no group found

POST /api/v2/grantAccessGroup — Grant Access to a Group

Grants one or more users access to one or more specified groups, creating the user-group association.

  • Required parameters: user_id (can be an array), group_id (can be an array)
  • 200 response: associations created successfully
  • 400 response: user not found, group not found, association already exists

POST /api/v2/dropAccessGroup — Revoke Access to a Group

Revokes the access permissions of a user belonging to a group, removing the user-group association.

  • Required parameters: user_id (can be an array), group_id (can be an array)
  • 200 response: associations removed successfully
  • 400 response: association does not exist, group not found, user not found

Credits

GET /api/v2/getcredits — Credit Balance

Returns the available credit balance.

GET /api/v2/getprices — Price List

Returns the price list for recharging credits.

POST /api/v2/recharge — Recharge Credits

Performs a credit recharge.

  • Parameters: user_id, amount (e.g. 10.50)

Keys

GET /api/v2/getunusednfc — Unused NFC Keys

Returns the list of NFC keys not associated with any user. No parameters required.

  • 404 response: no unused NFC key found

GET /api/v2/getallnfc — List NFC Keys

Returns the data for all NFC keys on the panel, whether associated or not.

  • Optional parameters (pagination): limit, offset
  • 400 response: no key found, or offset used without limit

PUT /api/v2/addkey — Add NFC Key

Adds a new NFC key.

  • Required parameters: nfc_key_code (RFID code read with a standard reader: it will be converted according to the LabKey standard — do not use a code taken from an access log), nfc_key_name (name to associate with the key)
  • Optional parameters: force_hex (forces conversion of the code from a hexadecimal string; if omitted, the conversion happens automatically only if the code contains at least one letter)

PUT /api/v2/addkey2user — Assign NFC Key to User

Assigns an NFC key to a specific user.

  • Required parameters: user_id, nfc_key_id
  • 400 response: key already assigned
  • 404 response: key not found, user not found

DELETE /api/v2/deletekey — Delete NFC Key

Deletes an NFC key.

  • Required parameters: nfc_key_code (RFID code converted according to the LabKey standard, e.g. 1234567890 → 210215073)
  • 404 response: key does not exist
  • 400 response: missing nfc_key_code

GET /api/v2/getnfcdetails — NFC Key Details

Returns the details of an NFC key.

  • Required parameters: nfc_key_code (code converted according to the LabKey standard)
  • 404 response: no user linked to the key, NFC key not found
  • 400 response: missing parameters

POST /api/v2/editnfc — Update NFC Key

Updates the details of an NFC key.

  • Required parameters: nfc_key_code, name
  • 404 response: nfc_key_code not found or missing, missing name

POST /api/v2/edittastierino — Change Keypad Code

Changes the code of a keypad (pinpad).

  • Required parameters: old_pinpad_key_code (old code to replace), new_pinpad_key_code (new code)
  • 200 response: code updated successfully
  • 404 response: the old code does not exist
  • 400 response: the code must be numeric

POST /api/v2/updatepinpad — Update Keypad Code for User

Updates the keypad code by selecting the user.

  • Required parameters: user_id, new_pinpad_key_code
  • 404 response: user does not exist
  • 400 response: the code must be numeric, key already exists

POST /api/v2/getqrcode — Generate QR Code

Generates a QR Code for the selected user, usable starting from the “message string”.

  • Required parameters: user_id
  • Optional parameters: image (if 1, returns the QR Code image base64-encoded), with_background (requires image=1; if 1, adds a decorative background to the image)
  • 404 response: user not found

POST /api/v2/getfasturl — Generate Fast URL

Generates the Fast URL for the selected user, usable starting from the fast_url field.

  • Required parameters: user_id
  • 404 response: user not found

GET /api/v2/getallpinpad — List Keypad Codes

Returns all keypad codes and their details.

  • Optional parameters (pagination): limit, offset
  • 400 response: set both limit and offset, or leave them both empty; limit/offset must be integers

Access and Permissions

POST /api/v2/getGrantInfo — Access Details

Returns the data relating to the specified access grant.

  • Required parameters: involved_associations (one or more IDs returned by the grantaccess call)
  • 200 response: user information and, for each associated LabKey unit, the access details
  • 400 response: at least one valid involved_associations must be sent
  • 404 response: row with that involved_associations not found

POST /api/v2/automategetGrantInfo — Simplified Access Details

Convenience call to simplify the use of getGrantInfo.

  • Optional parameters: user_id (can be an array), unique_name (can be an array — name of the selected LabKey unit)

GET /api/v2/getuservarcodetails — User Gate Details

Returns all the details on the gates associated with the selected user.

  • Required parameters: user_id

POST /api/v2/grantaccess — Grant Access

Grants access to a user. To configure a combination of multiple technologies (NFC, keypad, barcode), you can call this API multiple times, changing the key_id each time.

  • Required parameters: user_id, key_id (ID of the access key associated with the user: use nfc_key_id for NFC/Pocket, pinpad_key_id for keypad/barcode), data (JSON string with the parameters for each gate: date range datei/datef, time range houri/hourf, days of the week mo,tu,we,th,fr,sa,su, public holidays tv, command_device_id, id_rele, technology)
  • Optional parameters: check_overalapping, force_same_idrele_commanddeviceid

POST /api/v2/editaccess — Update Access

Convenience call that runs dropaccess and grantaccess in sequence, returning a new involved_associations for the user. This is not an atomic operation: if dropaccess completes successfully but grantaccess fails, the associations are removed regardless.

  • Required parameters: involved_associations (can be an array), user_id, key_id, data (JSON string, same format as GrantAccess)

DELETE /api/v2/dropaccess — Revoke Access

Revokes access permissions.

  • Required parameters: involved_associations (code obtained from the grantaccess response)

POST /api/v2/isAccessible — Check Gate Accessibility

Checks whether a gate is accessible within a given time range.

  • Required parameters: unique_name, from_date (timestamp), to_date (timestamp), id_rele

Counter Management (Anti-Passback)

GET /api/v2/antipassback/ — Counter Details

Returns the counter management details for the specified user and gate. The response is an array with the details for each relay.

  • Parameters: user_id, unique_name
  • Response fields: is_active (1/0, whether the counter is active), has_total/number_total (total access limit), has_day/number_day (daily limit), has_week/number_week (weekly limit), has_month/number_month (monthly limit)

POST /api/v2/antipassback/update_or_create — Set Counter

Creates or updates the counter configuration for one or more relays.

  • Parameters: user_id, data (JSON string with, for each LabKey unit and relay, the fields is_active, has_total/number_total, has_day/number_day, has_week/number_week, has_month/number_month)
  • Note: if is_active is set, only one of has_total, has_day, has_week, or has_month can be activated — they cannot be activated at the same time.

General

GET /api/v2/getlabkeys — List LabKey Units

Returns the details of the control units/LabKey units.

  • Optional parameters: unique_name, labkey_id, key_tipe
  • 400 response: no LabKey unit found

GET /api/v2/getbuildings — List Facilities

Returns information on the facilities associated with the panel.

  • Optional parameters: structure_id, structure_name, referent

GET /api/v2/getlogs — Access Logs

Returns the access logs.

  • Optional parameters: from (start date), to (end date), unique_name (name of the LabKey unit), labkey_id, user_id, limit (pagination), offset (pagination)

POST /api/v2/sendemail — Send Email

Sends an email to a customer, for example with their access details.

  • Required parameters: user_id (recipient), operator_email (sender)
  • Optional parameters: message (custom message; if omitted, a default message is sent), cc_emails (array of CC addresses), show_sender_name, send_permissions_list, send_fast_url, send_qr_code

WebHooks

Alerts — Real-Time Notifications

Lets you receive automatic notifications to your own endpoint every time an event occurs (e.g. an access). The webhook is configured from the Manage panel, in the Alert → Alert Standard section.

  • Parameters sent as a query string to your endpoint: user_id, full_name, id_log, key_code, result_boolean (whether access was granted or not), timestamp, is_log_offline, unique_name, labkey_id, tags, event_type

Custom Fields

Management of the custom fields that can be associated with a user’s profile (see also Adding a New User).

GET /api/v2/customfields — List Fields

Returns the list of custom fields with their attributes.

  • Optional parameters (pagination): limit, offset

GET /api/v2/customfields/{id_field} — Field Detail

Returns the details of a specific custom field.

GET /api/v2/customfields/count — Field Count

Returns the number of saved custom fields.

POST /api/v2/customfields/create — Create Field

Creates a new custom field.

  • Required parameters: type_field (text or date), name_field (max 255 characters)
  • Optional parameters: order (numeric), is_required (1 = required when filled in by the user), can_disable_user (1 = yes; usable only with type_field=date — the system automatically disables the user at midnight if the entered date has passed)

POST /api/v2/customfields/{id_field}/update — Update Field

Updates an existing custom field. Same parameters as create.

User Custom Fields

GET /api/v2/customfieldsuser/{id_user}/ — List Fields for User

Returns all the custom fields with values set for a user.

  • Optional parameters (pagination): limit, offset

GET /api/v2/customfieldsuser/{id_user}/{id_field} — Field Value for User

Returns the value of a specific custom field for the specified user.

POST /api/v2/customfieldsuser/{id_user}/{id_field}/create — Set Field Value

Creates the value of a custom field for the user.

  • Required parameters: value (max 255 characters)
  • Optional parameters: can_disable_user (0 = no, 1 = yes)

POST /api/v2/customfieldsuser/{id_user}/{id_field}/update — Update Field Value

Updates the value of a custom field for the user. Same parameters as create.

Templates

Management of predefined templates for recurring access (see also Templates).

GET /api/v2/templates/count — Template Count

Returns the number of saved templates.

GET /api/v2/templates/ — List Templates

Returns the list of templates.

  • Optional parameters (pagination): limit, offset

GET /api/v2/templates/detail — Template Detail

Returns the detail of a specific template.

  • Parameters: template_id

POST /api/v2/templates/addAccessUser — Apply Template to User

Applies an access template to a user. It can be used in two ways: by specifying both timestamp_start and timestamp_end (the system sets the access start and end to these values), or by specifying only timestamp_start and letting the system automatically calculate the end based on the template’s settings.

  • Required parameters: user_id, template_id
  • Optional parameters: timestamp_start (default: now), timestamp_end

Holidays

Management of holidays (see also Holidays): during the configured periods, the selected gates open only for permitted users.

GET /api/v2/festivita — List Holidays

Returns all holidays, or a specific one if the ID is passed.

  • Optional parameters: id
  • 404 response: holiday not found

GET /api/v2/festivita/count — Holiday Count

Returns the number of configured holidays.

  • Optional parameters: id
  • 400 response: invalid or missing parameters

GET /api/v2/festivita/is_holiday — Check Holiday

Checks whether a specific date/time falls within a holiday period.

  • Required parameters: datetime (format YYYY-MM-DD HH:MM:SS)
  • Optional parameters: unique_name, labkey_id, rele (array), user_id
  • 200 response: is_holiday (boolean)
  • 400 response: invalid or missing parameters

POST /api/v2/festivita/create — Create Holiday

Creates a new holiday.

  • Required parameters: title, start_datetime (format YYYY-MM-DD HH:MM:SS), end_datetime (format YYYY-MM-DD HH:MM:SS)
  • Optional parameters: description, recurring (1 = recurring every year), notification_email, monday…sunday (1 = active on that day), varcos (JSON array of labkey_id/rele involved), user_ids (array of users involved)

POST /api/v2/festivita/update — Update Holiday

Updates an existing holiday. Same optional parameters as create.

  • Required parameters: id
  • Optional parameters: title, start_datetime, end_datetime, recurring, active (1 = enabled, 0 = disabled), notification_email, monday…sunday, varcos, user_ids

DELETE /api/v2/festivita/delete — Delete Holiday

Deletes a holiday.

  • Required parameters: id
  • 200 response: holiday deleted successfully
  • 400 response: invalid or missing parameters
  • 404 response: holiday not found
Common Integrations: How-To Guide

The most common integration patterns between LabKey’s access control and property management systems, booking platforms, and payment systems, with real examples already in production.