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 Manage > Integrations > API Settings 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.
Changes made through this endpoint appear in the Work schedule change history report on the Reports page: such rows show External API in the Action site column. See the column reference in the Reports article.
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.
