Mercury API (1.0.0)
Download OpenAPI specification:
API for the Mercury platform, focusing on employee management, HR processes, and workflows.
Overview
Mercury API provides the backend services for the Mercury platform. Currently, its primary focus is to support functionalities for employee management and the handling of related HR processes and workflows. This includes managing employee data, controlling onboarding/offboarding, administering absences, and facilitating other HR operations.
Error Message Language
The language of error messages returned by the API can be controlled by the client using the Accept-Language HTTP header.
Supported languages include English (default, en), German (de), and French (fr).
If an unsupported language is requested, a key is missing for the requested language, or if the Accept-Language header is omitted, error messages will default to English.
Authentication
Most endpoints are secured using Bearer Token authentication (JWT).
A token can typically be obtained via an authentication endpoint (e.g., /auth/login).
Key Concepts (Current Focus)
- Employee: Represents an employee within the system (supersedes generic 'User' for core functions).
- Workflow: A defined HR process (e.g., leave request, performance review).
- Action/Task: A specific step within a workflow requiring interaction or completion.
Register a new user
Creates a new user account based on the provided details in the request body.
header Parameters
| Accept-Language | any Default: en Enum: "en" "de" "fr" Preferred response language (e.g., 'en', 'de', 'fr'). |
Request Body schema: application/jsonrequired
| username required | string (Username) [ 3 .. 50 ] characters The desired unique username for the new user. Must be between 3 and 50 characters. |
| email required | string <email> (Email Address) [ 5 .. 254 ] characters The desired unique email address for the new user. Must be a valid email format and max 100 characters. |
| password required | string <password> (Password) [ 8 .. 25 ] characters The desired password for the new user. Must meet complexity requirements (e.g., min 8 characters, max 25 characters, contain uppercase, lowercase, digit, special character). |
Responses
Request samples
- Payload
{- "username": "new.user",
- "password": "S3cureP@ssw0rd!"
}Response samples
- 201
- 400
- 409
{- "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
- "displayId": "USR-GHT7Y2",
- "username": "john.doe",
- "email": "[email protected]"
}Refresh access token
Generates a new access token using a valid refresh token (refresh_token grant type).
header Parameters
| Accept-Language | any Default: en Enum: "en" "de" "fr" Preferred response language (e.g., 'en', 'de', 'fr'). |
Request Body schema: application/jsonrequired
| grant_type required | string (Grant Type) Value: "refresh_token" The type of OAuth 2.0 grant being used. This must be 'refresh_token' for token renewal requests. |
| refresh_token required | string (Refresh Token) The previously issued refresh token used to obtain a new access token. |
| client_id | string (Client ID) The unique identifier of the client requesting the token renewal. This may be required depending on the server configuration. |
Responses
Request samples
- Payload
{- "grant_type": "refresh_token",
- "refresh_token": "sample-refresh-token-12345",
- "client_id": "my-api-client-id"
}Response samples
- 201
- 400
- 403
{- "access_token": "sample-access-token-abc123",
- "token_type": "Bearer",
- "expires_in": 3600,
- "refresh_token": "sample-refresh-token-xyz789"
}Login user
Authenticates a user with their credentials (password grant type) and returns access and refresh tokens.
header Parameters
| Accept-Language | any Default: en Enum: "en" "de" "fr" Preferred response language (e.g., 'en', 'de', 'fr'). |
Request Body schema: application/jsonrequired
| grant_type required | string (Grant Type) Enum: "password" "refresh_token" The type of OAuth 2.0 grant. Common values are 'password' for authentication with username and password, or 'refresh_token' for renewing an access token. |
| username | string (Username) The username of the user requesting an access token. Required if the grant type is 'password'. |
| password | string <password> (Password) The user's password. Required if the grant type is 'password'. |
| refresh_token | string (Refresh Token) The refresh token used to obtain a new access token. |
| client_id | string (Client ID) The unique identifier of the client requesting the token. May be required for certain grant types or server configurations. |
Responses
Request samples
- Payload
{- "grant_type": "password",
- "username": "john.doe",
- "password": "Str0ngP@sswOrd!",
- "refresh_token": "sample-refresh-token-xyz789",
- "client_id": "myApiClientId"
}Response samples
- 201
- 400
- 403
{- "access_token": "sample-access-token-abc123",
- "refresh_token": "sample-refresh-token-xyz789",
- "token_type": "Bearer",
- "expires_in": 3600
}Get user by ID
Retrieves a user's details based on the provided UUID. Returns the user if found.
path Parameters
| id required | string <uuid> |
header Parameters
| Accept-Language | any Default: en Enum: "en" "de" "fr" Preferred response language (e.g., 'en', 'de', 'fr'). |
Responses
Response samples
- 200
- 404
{- "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
- "displayId": "USR-GHT7Y2",
- "username": "john.doe",
- "email": "[email protected]"
}