What this feature does

OData is Epowerhr's Reporting API. It exposes the data you can already see in the application as a set of feeds that external tools — Excel, Power BI, Power Query, Tableau, a custom script, … — can read directly. You point the tool at a URL, sign in once, and the data refreshes whenever you ask for it.

A few things to know up front:

• It is read-only. OData only answers GET requests. You cannot create, update or delete records through it. To change data, use the application or one of the integrations.
• It returns the same data the user behind the token can see. The Reporting API does not bypass permissions, populations or hierarchy restrictions — if a user cannot view a record in the application, they cannot pull it through OData either.
• One token = one user = one tenant. The access token you use identifies a single Epowerhr user. The data returned belongs to that user's organization (CC) and respects that user's rights. There is no separate "service account" — the token is bound to whoever created it.

Before you start

You will need:

• A user account in Epowerhr with permission to view the data you want to report on. The simplest pattern is a dedicated reporting user that belongs to a group with the read rights you need (and only those).
• An access token for that user. Tokens are created on Admin → Users → <user> → Access tokens. See Access: manage users for how to create and rotate them.
• The Reporting API host. For most customers this is https://api.epowerhr.be, but some tenants are hosted on a different shard with a different address. The Reporting API host is not the same as the URL you use to sign in to the application — if you are not sure which one applies to your tenant, ask your Epowerhr contact or support.
• A client that speaks OData. Excel for Windows, Power BI Desktop and Power Query are the easiest. Anything that can call HTTP works too.

Tip — use a dedicated reporting user: create a user called e.g. Reporting and put it in a group whose rights are narrowed to exactly what your reports need. This keeps the token's blast radius small, and rotating it does not log a real person out of the application.

The base URL

Every Reporting API call goes to your tenant's API host, with /odata appended. For most customers the host is https://api.epowerhr.be, so the base URL looks like this:

https://api.epowerhr.be/odata

Check your host first. Some customers are on a different shard and use a different address. The examples below all use api.epowerhr.be — if your tenant is on another shard, replace the host with the address your Epowerhr contact gave you. Your access token only works against your own shard, so a wrong host will return a 401 or a DNS error.

Append the name of the feed (the entity set) you want to read:

https://api.epowerhr.be/odata/Employees

A discovery document — the list of every feed and every field — is always available at:

https://api.epowerhr.be/odata/$metadata

Most reporting tools call $metadata automatically when you point them at the base URL; you rarely need to open it by hand.

Available feeds

The Reporting API exposes the entities you typically need for HR reporting. The most common ones:

This is a representative list, not the full catalog — open /odata/$metadata from your client to see every feed and every field your tenant exposes.

Query operators

OData understands a small set of query-string operators. The ones you will use most:

Combine them with &:

/odata/Employees?$select=ID,FirstName,LastName&$filter=IsActive eq true&$orderby=LastName asc&$top=500

Always filter on the URL. Pulling 50 000 rows into Excel and filtering there means a slower refresh and a bigger workbook. Add $filter and $select to the URL — Epowerhr returns only the rows and fields you asked for, so the network payload is small and Excel has less to process.

Authentication

The Reporting API accepts the access token from the user's Access tokens tab in two forms:

1. Basic authentication — the form Excel and Power BI use natively. The token goes in the password field; you can leave the username blank — the server only reads the password part.
2. Bearer token — for scripts and custom clients. Send an Authorization: Bearer <token> header on every request.

Both forms grant exactly the same access. There is no API-key parameter on the URL.

Use OData in Excel

Excel for Windows ships with a built-in OData connector under Get & Transform Data. The flow below works in Excel 2016, 2019, 2021 and Microsoft 365.

Step 1 — Get the URL and the token ready

Have these two things at hand:

• The Reporting API base URL — <your-api-host>/odata (for most customers https://api.epowerhr.be/odata; if you are on a different shard, use the host your Epowerhr contact gave you). Pointing Excel at the base URL is the easiest way in — you don't have to know the feed names up front, because Excel calls $metadata for you and lists every available feed in the Navigator. (You can also paste a specific feed URL with $filter / $select when you have one prepared — see the worked example below.)
• The access token from Admin → Users → <reporting user> → Access tokens. Copy it the moment you create it — Epowerhr never shows it again.

Step 2 — Add the OData feed

1. Open Excel, go to the Data tab.
2. Click Get Data → From Other Sources → From OData Feed.
3. Paste the URL into the URL box and click OK.

Excel will try to connect and prompt for credentials.

Step 3 — Authenticate

1. In the credentials dialog, pick Basic in the left-hand list.
2. Fill in the fields:
   • User name: leave blank.
   • Password: paste the access token.
3. Under Select which level to apply these settings to, leave the default (the full base URL) so the same credentials are reused for every feed under /odata.
4. Click Connect.

Excel remembers these credentials per data source — you will not be asked for them again unless the token expires or you change it.

Step 4 — Pick the feeds to load

The Navigator opens with every feed your token can read. Tick the ones you want and either:

• Click Load to drop each feed straight into a worksheet table, or
• Click Transform Data to open Power Query first — recommended when you want to filter, rename columns, merge feeds or change types before the data lands in the workbook.

Step 5 — Trim the query

Even after you have ticked a feed, you can — and should — shape it before loading. In Power Query:

• Use Choose Columns to drop fields you don't need (the equivalent of $select).
• Use Filter Rows on a column to filter server-side (the equivalent of $filter). Power Query "folds" simple filters back into the OData URL, so the server still does the work.
• Use Keep Top Rows for a quick limit while you're building the query.

Click Close & Load when you are happy. The result is a refreshable Excel table.

Step 6 — Refresh later

Click Data → Refresh All (or schedule a refresh in Power BI Service / Excel for the web) to pull the latest data. The token is reused; you only have to authenticate again when it expires.

Worked example — active employees report:

1. From OData Feed → URL https://api.epowerhr.be/odata/Employees?$select=ID,FirstName,LastName,Email,Department&$filter=IsActive eq true&$orderby=LastName asc.
2. Authenticate Basic with the User name left blank and the access token in Password.
3. Load.

You now have a sortable, refreshable list of every active employee, with only the columns you asked for. Re-running the report next month is one click on Refresh All.

Use OData from other tools

The same URL and the same token work everywhere. Quick pointers:

• Power BI Desktop — Get Data → OData feed, paste the base URL /odata, authenticate with Basic. Power BI's query folding behaves like Power Query in Excel.
• A script (PowerShell, Python, …) — call the URL with an Authorization: Bearer <token> header and parse the JSON response. OData returns standard JSON with the rows in a value array.
• Tableau, Qlik, Looker Studio, … — any OData v4 connector works. Use Basic authentication if the connector asks.

Token lifecycle and rotation

Access tokens have an Expiration date. Epowerhr e-mails the token's owner 30 days, 7 days and 1 day before expiration so a rotation can be planned. When the token expires:

• Every Excel workbook and Power BI report using it starts failing on refresh with an authentication error.
• The old token cannot be reactivated. Go to Admin → Users → <user> → Access tokens, click Create new access token, copy the new value, and update each report.

Tip — name your reports: keep a short list of where each reporting user's token is used (which workbooks, which Power BI datasets). When a token is rotated, you know exactly which refresh credentials to update.

Frequently asked questions

Why do I get 401 Unauthorized? The token is wrong, expired, or the user behind it has been deactivated. Check the Access tokens tab for the user — the Expiration date field tells you whether the token is still valid. If the user's Active flag on the Detail tab is unticked, even a non-expired token is rejected. Generate a new token and update the report.

Why does a feed return fewer rows than the same screen in Epowerhr? The Reporting API enforces the same permissions, populations and hierarchy restrictions as the application. A token tied to a user who only sees their own department will return only that department's data. If you need a wider scope, point your reports at a user with broader rights (typically a dedicated reporting user in a group with the right view permissions).

Can I write data through OData? No. The Reporting API is read-only. Use the application UI for occasional changes, and one of the integrations (Salar, EasyPay, Nmbrs, Microsoft Graph, …) for system-to-system data flow.

Where do I find the full list of feeds and fields? Open /odata/$metadata in your client. Every feed Excel or Power BI shows in the Navigator comes from this document, and every field's name and type is listed there.

My filter doesn't work — Status eq Active gives an error. OData filters compare against the stored value, which for enums is usually the numeric code or the technical name, not the localized label you see in the UI. Open /odata/$metadata to find the field's type, or filter on a clearly typed field like IsActive eq true instead.

My report is slow. Add $select to drop fields you don't use and $filter to drop rows you don't need. Pulling everything and slicing in Excel is the most common cause of slow refreshes. For very large feeds, page with $top and $skip rather than asking for the whole set in one call.

The token leaked — what now? Go to Admin → Users → <user> → Access tokens and click Create new access token or Remove access token. Either action invalidates the leaked token immediately. Every report still using the old token will start failing on its next refresh; update them with the new value.