External API: get users
This External API endpoint lets you look up employees and their current workplace status from your own systems — HR software, dashboards, or reception/security tools. It returns the employee profile, work schedule, contacts, assigned desks, and whether the person is in the office right now.
Authentication
Create an API connection of type Users in Administration > Integrations > External API and copy the token (available to the Owner and Integrations admin roles). Pass it in every request:
Authorization: Bearer <token>Requests without a valid token return 401. If you exceed the rate limit, the API returns 429 with a Retry-After header.
Get users — GET /api/external/v1/users
Returns a page of users, or finds one user by an identifier. Pass at most one of email, externalId, employeeId — combining them returns 400.
| Query parameter | Type | Description |
|---|---|---|
email | string | Exact-match search by the user’s email |
externalId | string | Search by the external ID assigned during user sync |
employeeId | string | Search by the employee (personnel) number |
limit | integer | Page size. Default 100, maximum 100. |
offset | integer | Number of records to skip. Default 0. |
Example requests
curl -H "Authorization: Bearer $TOKEN" \
"https://acme.unspot.com/api/external/v1/users?limit=100&offset=0"
curl -H "Authorization: Bearer $TOKEN" \
"https://acme.unspot.com/api/external/v1/users?email=jane.doe@example.com"
curl -H "Authorization: Bearer $TOKEN" \
"https://acme.unspot.com/api/external/v1/users?employeeId=E-1042"Example response — 200
{
"message": "OK",
"body": {
"items": [
{
"firstName": "Jane",
"lastName": "Doe",
"position": "Product Manager",
"department": "Product",
"manager": "John Smith",
"externalId": "00u1abcd2EFGH3ij4x5",
"workSchedule": {
"workingHours": "09:00-18:00",
"assignedOffice": "HQ Berlin",
"workMode": "hybrid"
},
"contacts": {
"email": "jane.doe@example.com",
"phone": "+1 555 0100",
"messenger": "Telegram: @janedoe"
},
"assignedDesks": [
{ "name": "12, HS Liana, Main Tower", "days": ["We", "Th"] }
],
"status": {
"inOfficeNow": true,
"schedule": {
"todayStatus": "in office",
"extraStatus": null,
"placeName": "Desk A-12",
"startTime": "2026-07-09T09:00:00Z",
"endTime": "2026-07-09T18:00:00Z"
}
}
}
]
}
}| Response field | Description |
|---|---|
firstName / lastName / position | Employee profile |
department | Department from the org structure |
manager | Manager’s full name |
externalId | External ID from user sync (null if not set) |
workSchedule | workingHours, assignedOffice, workMode (office / remote / hybrid) |
contacts | email, phone, messenger |
assignedDesks | Permanently assigned desks: name (desk, floor, office) and days (Mo–Fr) |
status.inOfficeNow | true if the employee is currently in the office |
status.schedule | Today’s schedule: todayStatus (in office / remote / not working / null), extraStatus, placeName, startTime, endTime |
Errors and limits
- 400 — more than one of
email/externalId/employeeIdpassed at once. - 401 — missing or invalid token.
- 429 — more than one request per 10 seconds per workspace; wait for
Retry-After.
Errors are returned as {"message": "...", "errors": []}. For booking data, see External API: get bookings; for schedule updates, see External API: update user schedule status.
