Time Off API

Overview

The Time Off API allows you to programmatically manage employee time off periods in Swarmia, enabling you to sync time off data from external systems like HR platforms or leave management systems. The API provides full CRUD operations for managing time off periods.

Authentication

Authentication works based on a token which you can generate here.

Two options are currently available:

Include an HTTP header like Authorization: Bearer {TOKEN} in the request. Example request with the curl command line tool: curl https://app.swarmia.com/api/v0/time-offs -H "Authorization: Bearer {TOKEN}"
Pass the token as a value for the token query parameter. Example request: GET https://app.swarmia.com/api/v0/time-offs/{id}?token={TOKEN}
Security note: Even though Swarmia redacts secret tokens from query logs, please bear in mind that some other proxies might log query parameters before reaching Swarmia.

Create a time off period

POST /api/v0/time-offs

Creates a new time off period for a team member.

Example query

curl -H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-X POST https://app.swarmia.com/api/v0/time-offs \
-d '{
  "email": "[email protected]",
  "startDate": "2024-12-20",
  "endDate": "2024-12-27",
  "externalId": "HR-VACATION-12345"
}'

Parameters

Body parameters

email string required

Email address of the team member. Must match an existing author in your organization.

startDate string required

Start date of the time off period in yyyy-MM-dd format.

endDate string required

End date of the time off period in yyyy-MM-dd format. Must be on or after the start date.

externalId string optional

Identifier for the time off period used in your external system. This allows you to reference and update the period using your own ID system.

Maximum 128 characters
Cannot contain whitespace, slashes (/, \), or quotes (', ")
Must be unique within your organization
Cannot be changed after creation

Response

Response codes

Code

Description

201

Created

400

Validation error (invalid email format, date format, date range, or externalId format)

404

Email not found in organization

409

Duplicate time off period or externalId already exists

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "startDate": "2024-12-20",
  "endDate": "2024-12-27",
  "externalId": "HR-VACATION-12345",
  "createdAt": "2024-12-01T10:00:00.000Z",
  "updatedAt": "2024-12-01T10:00:00.000Z"
}

Get a time off period

GET /api/v0/time-offs/{id}

Retrieves a specific time off period by its Swarmia UUID or your external ID.

Example queries

By Swarmia id:

curl -H "Authorization: Bearer TOKEN" \
https://app.swarmia.com/api/v0/time-offs/550e8400-e29b-41d4-a716-446655440000

By external id:

curl -H "Authorization: Bearer TOKEN" \
https://app.swarmia.com/api/v0/time-offs/HR-VACATION-12345

Parameters

Path parameters

id string required

Either the Swarmia id or your externalId for the time off period.

Response

Response codes

Code

Description

200

404

Time off period not found

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "HR-VACATION-12345",
  "email": "[email protected]",
  "startDate": "2024-12-20",
  "endDate": "2024-12-27",
  "createdAt": "2024-12-01T10:00:00.000Z",
  "updatedAt": "2024-12-01T10:00:00.000Z"
}

Update a time off period

PUT /api/v0/time-offs/{id}

Updates an existing time off period. You can update the dates and the associated email. The externalId cannot be changed after creation.

When dates are updated, FTE calculations are automatically recalculated for both the old and new date ranges to ensure accuracy.

Example query

curl -H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-X PUT https://app.swarmia.com/api/v0/time-offs/HR-VACATION-12345 \
-d '{
  "email": "[email protected]",
  "startDate": "2024-12-20",
  "endDate": "2024-12-28"
}'

Parameters

Path parameters

id string required

Either the Swarmia UUID or your externalId for the time off period.

Body parameters

email string required

Email address of the team member. Must match an existing author in your organization.

startDate string required

Start date of the time off period in yyyy-MM-dd format.

endDate string required

End date of the time off period in yyyy-MM-dd format. Must be on or after the start date.

Note: The externalId field is immutable and cannot be changed through the update endpoint.

Response

Response codes

Code

Description

200

400

Validation error (invalid email format, date format, or date range)

404

Time off period not found or email not found in organization

409

Updated period conflicts with existing time off period

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "HR-VACATION-12345",
  "email": "[email protected]",
  "startDate": "2024-12-20",
  "endDate": "2024-12-28",
  "createdAt": "2024-12-01T10:00:00.000Z",
  "updatedAt": "2024-12-02T14:30:00.000Z"
}

Delete a time off period

DELETE /api/v0/time-offs/{id}

Permanently deletes a time off period. FTE calculations are automatically recalculated for the affected time range.

This is a permanent operation and cannot be undone.

Example query

curl -H "Authorization: Bearer TOKEN" \
-X DELETE https://app.swarmia.com/api/v0/time-offs/HR-VACATION-12345

Parameters

Path parameters

id string required

Either the Swarmia id or your externalId for the time off period.

Response

Response codes

Code

Description

204

No Content - Successfully deleted

404

Time off period not found

Example response

No response body is returned on successful deletion (204 status code).

Using External IDs

The Time Off API supports a dual-identifier system to make integration with external systems easier:

Swarmia UUID (id): Automatically generated by Swarmia when a time off period is created
External ID (externalId): Optional identifier from your HR or leave management system

Benefits of using External IDs

Simplified integration: Use your existing HR system's identifiers instead of storing Swarmia ids
Idempotent operations: Prevent duplicate entries by using consistent external IDs
System independence: If you migrate HR systems, you can maintain the same external IDs

External ID requirements

Maximum 128 characters
Cannot contain whitespace, slashes (/, \), or quotes (', ")
Must be unique within your organization
Cannot be changed after creation
Can be used interchangeably with Swarmia id in GET, PUT, and DELETE operations

Example workflow with External IDs

# 1. Create with external ID
curl -X POST https://app.swarmia.com/api/v0/time-offs \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "startDate": "2024-12-20",
    "endDate": "2024-12-27",
    "externalId": "HR-LEAVE-2024-001"
  }'

# 2. Update using external ID (no need to store Swarmia UUID)
curl -X PUT https://app.swarmia.com/api/v0/time-offs/HR-LEAVE-2024-001 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "startDate": "2024-12-20",
    "endDate": "2024-12-28"
  }'

# 3. Delete using external ID
curl -X DELETE https://app.swarmia.com/api/v0/time-offs/HR-LEAVE-2024-001 \
  -H "Authorization: Bearer TOKEN"

Common validation errors

Invalid email format

{
  "message": "Invalid email format"
}

Invalid date format

{
  "message": "Invalid start date format. Expected yyyy-MM-dd"
}

Invalid date range

{
  "message": "Start date must be before or equal to end date"
}

Email not found

{
  "message": "Email not found"
}

The specified email address doesn't match any team member in your organization.

External ID already exists

{
  "message": "External ID already exists"
}

Another time off period in your organization is already using this externalId.

Time off period already exists

{
  "message": "Time off period already exists"
}

A time off period for this team member with these exact dates already exists.

Invalid External ID format

{
  "message": "External ID cannot contain whitespace, slashes, or quotes"
}

Best practices

Use External IDs for easier integration

If you're integrating with an HR system, always provide externalId to:

Avoid storing and managing Swarmia ids in your system
Prevent duplicate entries when syncing
Simplify updates and deletions

Handle date changes carefully

When updating dates, keep in mind:

FTE calculations are automatically recalculated for affected time ranges
Large date changes may affect multiple months of FTE data
Consider the impact on reporting and metrics

Error handling

Always check response status codes and handle errors appropriately:

400 errors indicate validation issues - check your input data
404 errors mean the resource wasn't found - verify IDs are correct
409 errors indicate conflicts - check for duplicates
500 errors are server issues - implement retry logic

PreviousTeam Management API NextAI coding tool integrations

Last updated 6 days ago

Was this helpful?

hashtagOverview

hashtagAuthentication

hashtagCreate a time off period

hashtagExample query

hashtagParameters

hashtagResponse

hashtagGet a time off period

hashtagExample queries

hashtagParameters

hashtagResponse

hashtagUpdate a time off period

hashtagExample query

hashtagParameters

hashtagResponse

hashtagDelete a time off period

hashtagExample query

hashtagParameters

hashtagResponse

hashtagUsing External IDs

hashtagBenefits of using External IDs

hashtagExternal ID requirements

hashtagExample workflow with External IDs

hashtagCommon validation errors

hashtagInvalid email format

hashtagInvalid date format

hashtagInvalid date range

hashtagEmail not found

hashtagExternal ID already exists

hashtagTime off period already exists

hashtagInvalid External ID format

hashtagBest practices

hashtagUse External IDs for easier integration

hashtagHandle date changes carefully

hashtagError handling

Overview

Authentication

Create a time off period

Example query

Parameters

Response

Get a time off period

Example queries

Parameters

Response

Update a time off period

Example query

Parameters

Response

Delete a time off period

Example query

Parameters

Response

Using External IDs

Benefits of using External IDs

External ID requirements

Example workflow with External IDs

Common validation errors

Invalid email format

Invalid date format

Invalid date range

Email not found

External ID already exists

Time off period already exists

Invalid External ID format

Best practices

Use External IDs for easier integration

Handle date changes carefully

Error handling