External API: update user schedule status
This External API endpoint lets your HR or workforce-management system set a user’s schedule status in UnSpot — for example, mark an employee as working remotely or absent (vacation, sick leave) for a specific day.
Authentication
Create an API connection of type User schedule in Administration > Integrations > External API and copy the token. 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.
Update a user’s status — POST /api/external/v1/user-schedule
| Body field | Type | Required | Description |
|---|---|---|---|
userEmail | string | yes | Email of the UnSpot user (archived and deactivated users are not matched) |
date | string | yes | Day the status applies to, format YYYY-MM-DD |
statusType | string | no | REMOTE_WORK or NOT_WORKING. If omitted or null, the status for that date is reset. |
statusName | string | no | Custom status label, max 128 characters (e.g. “Vacation”) |
statusCode | string | no | Short code shown in the schedule, max 6 characters (e.g. “VAC”) |
If you send statusName or statusCode, all three of statusName, statusCode and statusType must be provided together.
Example: mark remote work
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
https://acme.unspot.com/api/external/v1/user-schedule \
-d '{
"userEmail": "jane.doe@example.com",
"date": "2026-07-10",
"statusType": "REMOTE_WORK"
}'Example: set a named absence
{
"userEmail": "jane.doe@example.com",
"date": "2026-07-13",
"statusType": "NOT_WORKING",
"statusName": "Vacation",
"statusCode": "VAC"
}Example: reset the status
{ "userEmail": "jane.doe@example.com", "date": "2026-07-10" }Response: 200 with a success message; the change is immediately visible in the user’s schedule.
Errors and limits
- 400 —
Missing required field: userEmail/date;Invalid statusType value; cross-field rules for statusName/statusCode/statusType;User not found. - 401 — invalid token.
- 429 — more than 1 request per second per token. For bulk updates, throttle your requests.
