Getting Started with the Roosted API: Authentication, Endpoints, and Your First Call

Roossted's REST API gives staffing companies programmatic access to the same workforce management capabilities available in the platform UI. Workers, events, shifts, time tracking, clients, payroll groups, rate cards, and more are all available through standard HTTP requests with JSON payloads.

This guide covers everything you need to make your first successful API call: getting credentials, authenticating requests, understanding the endpoint structure, and building from there.

Prerequisites and API Access

API access is available to all Roosted customers on any plan. To get started, email support@roostedhr.com and request API credentials. The team will provision keys for both the sandbox and production environments so you can develop safely before pointing at live data.

You will receive a Bearer token for each environment. Keep these credentials secure, and do not expose them in client-side code or version control.

Authentication

Every API request requires a Bearer token in the Authorization header. No additional API key headers, OAuth flows, or session cookies are needed.

Here is what a request looks like:

If the token is missing, malformed, or expired, the API returns a 401 Unauthorized response. If you receive a 403 Forbidden, your token may lack the required permissions for that specific endpoint.

Base URLs and Environments

Roosted provides two separate environments:

Always build and test against the sandbox first. Sandbox data does not affect your production account, so you can create, update, and delete records freely during development. When your integration is stable, swap the base URL to production.

Making Your First API Call

Start with a simple GET request to retrieve your list of workers. This confirms your credentials are valid and gives you a feel for the response structure.

Request

Response

The API returns a JSON array of worker objects. Each object includes the worker's profile details, contact information, status, and related metadata. Here is an abbreviated example:

Responses follow a consistent pattern across all resources. Lists return paginated arrays with metadata, and individual records return the full object with all sub-resource references.

Creating a Resource

Once you have confirmed read access, try creating an event. This is the kind of operation that powers real integrations, where a client order in your CRM triggers an event in Roosted automatically.

A successful POST returns the newly created object with its assigned ID, which you can then use to add shifts, assign workers, and manage the event lifecycle.

Core Resource Overview

The Roosted API spans 14 resource areas with over 100 endpoints. Here is a map of what is available:

Most resources support full CRUD operations (create, read, update, delete), plus sub-resource endpoints for related data. Workers alone includes endpoints for availability windows, credential records, assigned shifts, time punches, tags, chats, documents, invites, reimbursements, and permission levels.

Common Integration Patterns

Here are four patterns that cover the majority of real-world Roosted API integrations:

Syncing workers from an HRIS. Use POST /workers to create new worker profiles when they are added to your HR system, and PATCH /workers/{id} to keep profiles in sync as employee data changes. This eliminates manual data entry when onboarding new hires into Roosted.

Pushing events from a client portal. When a client submits a staffing request through your portal or CRM, use POST /events to create the event in Roosted, then POST /events/{id}/shifts to define the roles and headcount needed. Roosted's smart shift matching can take over from there in the UI, or you can assign workers programmatically via the API.

Pulling time tracking for payroll. At the end of each pay period, use the Time Tracking endpoints to pull approved hours by worker or payroll group. Map that data to your payroll provider's import format (QuickBooks, ADP, Gusto, or your in-house system) and eliminate the manual export-and-rekey cycle. Roosted also offers a built-in QuickBooks integration for teams that want a no-code option.

Managing rate cards programmatically. Staffing companies with complex pay structures across multiple clients, regions, or skillsets can use the Rate Cards and Wage Rules endpoints to update pay rates in bulk rather than configuring each one through the UI.

Error Handling

The API uses standard HTTP status codes. Here are the ones you will encounter most often:

Error responses include a JSON body with details about what went wrong, so your integration can log and handle failures gracefully.

Next Steps

You are set up with credentials, you understand the authentication model, and you have made your first call. From here:

1. Browse the full API reference at docs.roostedhr.com for detailed endpoint documentation, request/response schemas, and parameter definitions.

2. Explore the Roosted help center for product context on how features work in the UI, which helps when deciding how to model your integration.

3. Start building in the sandbox. Test your create, read, update, and delete flows against test data before switching to production.

If you are not yet a Roosted customer and want to evaluate the platform and API for your staffing operation, explore our plans or request a demo.

Get Started