API Docs
Voxbi Cockpit APIs
All endpoints

Get tablet session (grid layout format)

Returns the tablet session for a scanned badge: current status, work-time summary, layout and terminal location. Requires a PBX API-key token with the terminals ability.

HTTP: bearerAuth

User bearer token. Default authentication for customer-facing endpoints. Obtain a token by calling POST /login with your credentials, then send it on every subsequent request as Authorization: Bearer <token>. The token inherits the permissions and PBX scope of the authenticated user.

HTTP Authorization Scheme
bearer
Bearer format
Bearer <token>
mac_address path · string *
The tablet's MAC address (any format; case-insensitive).
accept header · string
example: application/json

Request body · required

Request schema
badge_identifier*string
The scanned NFC badge identifier.

Responses

Response schema
current_statusobject | null
The status the user is currently in; null when there is no ongoing timepoint.
idstring · uuid
namestring
descriptionstring | null
styleobject
Free-form object
metadataobject
availabilitystring | null
allow_multiselectboolean
substatus_selection_mandatoryboolean
location_idsarray<string>
[]string · uuid
substatus_idsarray<string>
[]string · uuid
user_infoobject
idstring · uuid
bearer_tokenstring
Freshly issued Sanctum token for the badge session.
display_namestring | null
work_timesobject
Current-day work-time summary (HH:MM:SS).
dailystring
min_dailystring
weeklystring
min_weeklystring
monthlystring
min_monthlystring
lunchstring
layoutobject | null
The assigned layout; null when no active layout is configured.
idstring · uuid
namestring
grid_sizeobject
rowsinteger
columnsinteger
statusesarray<object>
[]object
Free-form object
substatusesobject
Free-form object
locationobject | null
The terminal's location; null when it has none or no terminal matched.
idstring · uuid
namestring
descriptionstring | null
Missing required field (badge_identifier).
Response schema
errorstring
Authorization Token Missing. This error is returned when the authorization token is missing.
Response schema
errorstring
Error message
example: Authorization Token is missing
The matched terminal exists but is not active. No session is returned.
Response schema
errorstring
Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue.
Response schema
messagestring
exceptionstring
Only present in non-production environments.
filestring
Only present in non-production environments.
lineinteger
Only present in non-production environments.
post https://cockpit.voxbi.com/api/v1/terminal/{mac_address}/badge
Base URL
Request sample 
curl -X POST 'https://cockpit.voxbi.com/api/v1/terminal/{mac_address}/badge' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"badge_identifier":"BADGE-0001"}'
const response = await fetch('https://cockpit.voxbi.com/api/v1/terminal/{mac_address}/badge', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
  body: JSON.stringify({
    "badge_identifier": "BADGE-0001"
}),
});

const data = await response.json();
console.log(data);
import requests

response = requests.post('https://cockpit.voxbi.com/api/v1/terminal/{mac_address}/badge',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'},
    json={
    "badge_identifier": "BADGE-0001"
}
)
response.raise_for_status()
data = response.json()
print(data)
<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
        'content' => '{
    \"badge_identifier\": \"BADGE-0001\"
}',
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/terminal/{mac_address}/badge', false, $context);
$data = json_decode($response, true);
print_r($data);
Sample request
{ … }
"badge_identifier": "BADGE-0001"
}
{ … }
"current_status": { … },
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Working",
"description": "Regular working time",
"style": { … },
"icon_class": "la la-briefcase",
"bg_color": "#2e7d32",
"font_color": "#ffffff"
},
"metadata": { … },
"availability": "available",
"allow_multiselect": false,
"substatus_selection_mandatory": false
},
"location_ids": [],
"substatus_ids": []
},
"user_info": { … },
"id": "550e8400-e29b-41d4-a716-446655440002",
"bearer_token": "42|aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789AbCd",
"display_name": "Jane Smith"
},
"work_times": { … },
"daily": "07:30:00",
"min_daily": "08:00:00",
"weekly": "37:30:00",
"min_weekly": "40:00:00",
"monthly": "150:00:00",
"min_monthly": "160:00:00",
"lunch": "00:30:00"
},
"layout": { … },
"id": "550e8400-e29b-41d4-a716-446655440040",
"name": "Default Tempus",
"grid_size": { … },
"rows": 3,
"columns": 3
},
"statuses": [],
"substatuses": []
},
"location": { … }
"id": "550e8400-e29b-41d4-a716-446655440030",
"name": "Head Office",
"description": "Main office location"
}
}
Host string
example: cockpit.voxbi.com
Date string
example: Mon, 16 Oct 2023 14:08:48 GMT
Connection string
example: close
Cache-Control string
example: no-cache, private
Content-Type string
example: application/json
X-RateLimit-Limit integer
example: 60
X-RateLimit-Remaining integer
example: 59
Vary string
example: Origin
{ … }
"error": "Missing required field: badge_identifier"
}
{ … }
"error": "Authorization Token is missing"
}
Cache-Control string
example: private, must-revalidate
Connection string
example: keep-alive
Content-Type string
example: application/json
Vary string
example: Origin
X-RateLimit-Limit integer
Max requests allowed in the current rate-limit window.
example: 60
X-RateLimit-Remaining integer
Requests remaining in the current rate-limit window.
example: 57
{ … }
"error": "Terminal exists but is not active"
}
{ … }
"message": "Server Error"
}