If you want to get started immediately with our API, we provide a Postman collection. All you need to do is import the collection through File -> Import -> Link in Postman. The collection contains most endpoints found here, including examples of retrieving and refreshing tokens.

Additionally, the collection contains a pre-request script that automatically handles retrieval and refreshing of tokens for all calls when testing through Postman, allowing you to start testing without having to setup authentication manually. In order to use the pre-request script, you need to fill out the client_id and client_secret environment variables in Postman.

HR-ON's API is secured with OAuth 2.0. Any applications that wish to utilize the API must first be authenticated and authorized to do so. We follow the Authorization Framework protocol. To authenticate using OAuth2, follow these steps:

1. Obtain Authorization Credentials

   • Make a POST request to the authorization server's token endpoint (https://auth.hr-on.com/oauth2/token).
   • Include your client ID and client secret in the request.
   • Set the grant_type to client_credentials.
   • The server will respond with an access token, a refresh token, and information related to the token.

2. Use the Access Token

   • Include the access token in the Authorization header of your API requests.
   • Example:

     GET /company
     Host: https://api.hr-on.com/v1/staff
     Authorization: Bearer your_access_token_here
     

3. Refresh the Access Token (if applicable)

   • If your access token has expired, you can use the refresh token to obtain a fresh set of credentials.
   • Make a POST request to the token endpoint with the refresh token.
   • Set the grant_type to refresh_token.
   • The server will respond with a new set of credentials.

Example credentials request:

POST /token
Host: https://auth.hr-on.com/oauth2
Content-Type: application/json

Body: {
  "grant_type": "client_credentials",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

Example credentials response:

{
  "access_token": "your_access_token_here",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "your_refresh_token_here"
}

Example refresh token request:

POST /token
Host: https://auth.hr-on.com/oauth2
Content-Type: application/json

Body: {
  "grant_type": "refresh_token",
  "refresh_token": "your_refresh_token_here"
}

If you encounter an issue with the API, please contact us at support@hr-on.com with the following information:

1. What is the problem?

   • Describe exactly what is wrong.

2. What endpoint was called?

   • Include the full endpoint path and request type (GET, POST, etc.).
   • Include any path/query parameters used.
   • Include the request body, if one was used.

3. When did you experience the error?

   • Provide the exact timestamp if possible, otherwise a rough date is fine.

4. Was the error a one-off or is it recurring?

5. What error message did you receive, if any?

Reports like "API is broken, please fix", with no additional info, will be disregarded.

Webhooks are a way for HR-ON Staff to notify your application when certain events occur. To see more information about webhooks, see our Webhook documentation.

An absence represents a period an employee is away, e.g. vacation, sick leave, or a doctor's visit.

Absence is not to be confused with time registration - a time registration tracks when an employee works, absence tracks when they don't.

The fullDay flag determines how startDate/endDate are interpreted:

• fullDay: true - the absence spans whole calendar days (e.g. vacation). startDate/endDate are treated as dates.
• fullDay: false - the absence spans part of a day (e.g. a doctor's visit). startDate/endDate are treated as timestamps.

Absence types (/v1/staff/absences/types) describe the category of an absence, e.g. "Vacation", "Sick leave". Every absence references one via typeId. Types also carry a mustBeApproved flag indicating whether absences of that type require approval.

approvedAt, deniedAt, and approvedOrDeniedBy are read-only fields on an absence. Once an absence has been approved, it can no longer be edited or deleted outright; deleting it instead creates a deletion request that follows the same approval flow.

Used for custom fields related to employees.