WorkMax APIs

WorkMax APIs provide programmatic access to WorkMax platform data such as employees, locations, tasks, time records, assets, and forms. Built on modern REST principles, the API enables developers to integrate core Workmax functions directly into their applications and workflows.

Products

Within the developer portal, APIs are bundled within a product. Products are grouped with a focus of like functionality. Currently we have one Workmax product including all 5 of our apis.

To access the Workmax APIs, a subscription key is required. Subscription keys are scoped to limit access based on the need. The API Support team administrates these subscription keys by providing a primary and secondary key during onboarding. Separate keys will be needed to access sandboxes and production.

Your subscription key will be required as either a header or query parameter to each API request in addition to the Bearer token.

Open API Specifications (OAS v3.x)

During the Commercial Evaluation phase, someone from your organization will be given access to the Developer Portal where you can view our OpenAPI specifications. You may download the specifications from the API details page by clicking the "API definition" dropdown and clicking on the Open API version you want to download.

The document downloads automatically to your browser download folder. You can import this document into any tool that support importing Open API Specification.

Versioning

The Workmax API is versioned using Path Versioning.

There could be breaking changes to the APIs. Breaking changes will be communicated in close collaboration with our development team. Breaking changes will be released with a new version of APIs and may become available at the path level.

For example, Workmax API Employees would be accessible at the following path:

../platform/v1/employees

If the Workmax team plans a breaking change advanced communication will be provided, and that endpoint will be updated with the new version on a schedule.

Authentication

Workmax APIs require Bearer tokens for auth which are granted from our platform/v1/login endpoint.

Sample Request

curl --location --request POST \
'https://api.workmax.com/workmax/platform/v1/login' \
--header 'Content-Type: application/json' \
--header "Ocp-Apim-Subscription-Key: {your-subscription-key}" \
--data-raw "{    \"UserName\": \"{your-user-name}\",    \"Password\": \"{your-password}\"}"

Your First API Call

After you have authorized your first test user and received an auth token, you can try out our APIs by visiting the documentation on the Foundation API site.

Example: Get My Info

Let's get the information from your current user:

curl --location --request GET \
'https://api.workmax.com/workmax/platform/v1/me' \
--header 'Authorization: Bearer {your-token}' \
--header 'Ocp-Apim-Subscription-Key: {your-subscription-key}' \

You should receive the response payload with a 200 status code:

{
  "firstName": "John",
  "lastName": "Doe",
  "companyName": "ABC Construction",
  "roles": ["Admin", "TimeEntry"],
  "createdTimestamp": "2024-01-15T08:30:00Z",
  "updatedTimestamp": "2024-01-19T14:22:00Z",
  "status": 1,
  "externalId": "ext_12345",
  "updatedById": "user_67890"
}

Rate Limiting

The Workmax API uses rate limiting to optimize performance and security for integrations.

Current Rate Limit

500 requests per minute per client

Client-Based Limits

The rate limit is applied to the client, not the integration. For example, if MyIntegration has 10 mutual clients with Workmax, and the 10 clients all use the app at the same time, they each have an individual rate limit of 500 per minute.

Prevent Excessive Failures

Once a client reaches the rate limit, the API will return a 429 response.

Security Alert

Too many calls returning a 429 may be identified as a security threat, resulting in the integration being blocked and an investigation being conducted.

To prevent this, design the integration so that once the rate limit is reached, future calls are postponed until the rate limit resets. Consider using a circuit breaker pattern with a cached time to resume requests.

Rate Limit Headers

The following headers are returned on any API call:

Header Name	Value	Description
X-RateLimit-Limit	500	The total number of allowed requests
X-RateLimit-Remaining	0-499	The number of calls remaining until the rate limit will be reached

After the rate limit is reached, the following header is returned:

Header Name	Value	Description
X-RateLimit-Reset		The time in milliseconds at which the rate limit will reset

Need Help?

For questions during development, contact support@WorkMax.com

---

Site v5