Read and analyze Simployer Classic HRM data through OData, Excel, Power BI, or your own systems.

Analytics API is a REST API that lets you read and analyze Simployer Classic HRM data. Analytics API implements the open OData standard. You can use Analytics API with third-party tools such as Excel and Power BI or consume it directly from your own systems.

For documentation about SimplAuth API authentication, see the article about SimplAuth.

How to use Analytics API

Analytics API URLs

OData endpoint: https://analytics-api.simployer.com/

Documentation and testing page: https://analytics-api.simployer.com/swagger

See the section about Swagger UI below for more information about the documentation and testing page.

Use Analytics API with Self-Service BI tools

For a specific Self-Service BI tool, check whether the tool supports OData Feed. Alternatively, you can use Analytics API as a standard REST endpoint.

Analytics API uses pagination and limits the number of results per request. See the FAQs for details.

Authenticate with Analytics API

Analytics API supports the SimplAuth authentication protocol. See the article about SimplAuth for details.

Connect Excel or Power BI to Analytics API

The following steps show how to authenticate and connect to Analytics API using Excel. The process is similar in Power BI because both applications use Power Query.

For a more detailed guide to configuring Power Query for authentication and data retrieval, see the article "Connect to the HRConnect API through Power Query (Excel/Power BI)."

1. Go to Data → Get Data → From Other Sources → From Web
2. In the pop-up window, select Advanced and enter the required information

A new window opens with the retrieved data. You can then transform the response into a table.

Use the OData V4 standard with Analytics API

Analytics API is a REST API based on the open OData V4 protocol. The protocol supports the following functions:

• $filter limits which items are returned. The maximum number of expressions is 100.
• $orderby specifies the sort order of the returned items
• $top limits the number of items returned from a collection
• $skip omits a specified number of items from the beginning of the result set
• $count specifies whether the total number of items in a collection is returned in the result
• $expand specifies related entities to include directly in the result. The maximum depth is 2.
• $select limits which properties are returned in the result

These functions are described in the OData documentation.

Test Analytics API with Swagger UI

Analytics API includes Swagger UI, which lets you test endpoints before connecting through a Self-Service BI tool.

Swagger UI lists all available endpoints and their associated schemas. Expand a schema to see a detailed description of each property.

References to other entities, such as absences, immediateSupervisor, affiliationUnit, employees, and directReports, appear as expandable properties. Use these properties with the OData function $expand to include related entities in the result set.

Make Analytics API requests in Swagger UI

You must be authorized before you can use Swagger UI to make requests to Analytics API endpoints.

1. Select Authorize above the list of endpoints
2. Follow the instructions to authorize
3. Expand an endpoint and select Try it out to test it

For example, you can retrieve one person (sk = 1) and include details about the person's affiliationUnit. For both entities, you can limit the returned properties to a small number of columns. This can be nested within the $expand function.

FAQs about Analytics API

Why do I get an Unauthorized (401) error when connecting to the Analytics API OData endpoint?

Follow the instructions for the tool you are using:

• Browser: You cannot use a browser to access the OData endpoint. Use a specialized application such as Excel or Power BI. To explore the data model or its documentation in a browser, use Swagger UI, which is available through a separate endpoint.
• Specialized BI tool: See the Excel and Power BI section and confirm that you entered the correct connection parameters.
• Swagger UI: Confirm that you entered the correct token when you selected Authorize before calling an endpoint.

When generating a SimplAuth token, confirm that you are targeting the correct audience: https://analytics-api.simployer.com. Tokens generated for another audience, such as HRConnect, are not authorized for Analytics API.

Where can I find the Analytics API data model documentation?

The Analytics API data model documentation is available in Swagger UI. You can find it in the Schemas section below the list of endpoints.

How do I use $filter in an Analytics API request?

Use the $filter keyword in the request. See the OData tutorial for details.

For example, use the following filter to return only people with the first name Anna:

v1/Person?$filter=firstName eq 'Anna'

Other logical filter operators are also available. See the OData URL Conventions documentation for a complete list.

How do I include related entities in an Analytics API result?

Use the $expand keyword in the request. When you retrieve data for an entity with a configured relationship, such as Person, Excel can show additional columns such as affiliationUnit.

Example request:

https://analytics-api.simployer.com/v1/person?$filter=sk eq 1

Without $expand, the related field is not populated. To include the related entity, add $expand and specify the entity:

https://analytics-api.simployer.com/v1/person?$filter=sk eq 1&$expand=affiliationUnit

Why does my Analytics API request not return all data from a large dataset?

Analytics API uses the OData pagination mechanism. You can retrieve a limited number of records per request. The current limit is 100,000 rows.

OData connections, such as the connection in Power BI, should generally handle pagination automatically. If you use Analytics API manually, you have two options:

• @odata.nextLink: Use this field from the response to get the URL for the next page of records.
• $skip: Use this keyword in the request to retrieve the next page of records.

Why do I get response code 429 (Too Many Requests) from Analytics API?

Analytics API uses rate limiting to prevent misuse and maintain performance for all customers. The current limit is 30 requests per minute.