The Feel The Benefit Workforce API gives your payroll and HR systems secure, on-demand access to invoice-backed salary sacrifice nursery fee data for your company. This developer guide covers authentication, endpoints, field definitions, code samples and the complete OpenAPI 3.0 specification.
Payroll & HR API for salary sacrifice nursery fees
Bring nursery fee deductions into payroll and workplace nursery benefit details into your HR platform.
Salary sacrifice nursery fee data, straight into payroll and HR
Employers offering the Workplace Nursery Benefit through Feel The Benefit can connect their payroll and HR platforms directly to our systems. Instead of re-keying monthly deductions or passing spreadsheets between teams, your integration requests the data it needs, when it needs it.
The API is read-only, returns JSON and is described by an OpenAPI 3.0 document. Each integration authenticates with Microsoft Entra ID OAuth 2.0 client credentials and is bound to exactly one company, so a client can only ever read its own employer's data.
All data is invoice-backed. It reflects nursery fee deductions that have been invoiced, including any credits, rather than projected future deductions.
Deductions for payroll
Benefit details for HR
API at a glance
| Base URL | {apiBaseUrl}, supplied for your environment during onboarding |
|---|---|
| Authentication | Microsoft Entra ID OAuth 2.0 client credentials (application-only) |
| Token URL | https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token |
| Scope | api://{apiApplicationId}/.default |
| Roles | Payroll.Read, HR.Read, or both |
| Format | JSON over HTTPS; money as numbers to two decimal places; currency GBP |
| Errors | RFC 9457 application/problem+json with a correlationId |
| Rate limits | 15 requests per minute and 100 per hour, per client and environment |
| Versioning | Major version in the URL: /api/v1/ |
| Specification | OpenAPI 3.0.1 JSON |
Getting access. API access is set up for employer clients during onboarding by request. Contact us to start a payroll or HR integration and we will arrange your secure integration handoff.
Quick start: your first API call
1. Receive your integration handoff
During onboarding, an administrator sends these environment-specific values through an approved secure channel:
- tenant ID and token endpoint;
- client ID and a one-time client secret;
- API application ID (the token audience) and the API base URL;
- your company ID, used as
employerIdin every route; and - the application roles assigned to your client:
Payroll.Read,HR.Read, or both.
The client secret is shown once and expires after 180 days. Keep it in a server-side secret store. Never put it in browser JavaScript, source control, logs, email or support messages.
# Values from your secure onboarding handoff (local testing only).
# In production, load FTB_CLIENT_SECRET from your secret store; never commit it.
export FTB_TENANT_ID="{tenantId}"
export FTB_CLIENT_ID="{clientId}"
export FTB_CLIENT_SECRET="{clientSecret}"
export FTB_API_APPLICATION_ID="{apiApplicationId}"
export FTB_API_BASE_URL="{apiBaseUrl}"
export FTB_COMPANY_ID="{companyId}" 2. Request an access token
Request the API's /.default scope with the client credentials grant. Delegated user tokens are rejected. Cache the token and reuse it until it nears expiry rather than requesting a new token for every call.
ACCESS_TOKEN=$(curl --silent --fail --request POST \
--url "https://login.microsoftonline.com/${FTB_TENANT_ID}/oauth2/v2.0/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "client_id=${FTB_CLIENT_ID}" \
--data-urlencode "client_secret=${FTB_CLIENT_SECRET}" \
--data-urlencode "scope=api://${FTB_API_APPLICATION_ID}/.default" \
--data-urlencode "grant_type=client_credentials" | jq -r '.access_token') // dotnet add package Microsoft.Identity.Client
using Microsoft.Identity.Client;
var tenantId = Environment.GetEnvironmentVariable("FTB_TENANT_ID")!;
var clientId = Environment.GetEnvironmentVariable("FTB_CLIENT_ID")!;
var clientSecret = Environment.GetEnvironmentVariable("FTB_CLIENT_SECRET")!; // from your secret store
var apiApplicationId = Environment.GetEnvironmentVariable("FTB_API_APPLICATION_ID")!;
var confidentialClient = ConfidentialClientApplicationBuilder
.Create(clientId)
.WithClientSecret(clientSecret)
.WithAuthority($"https://login.microsoftonline.com/{tenantId}")
.Build();
// Keep one confidential client per process: MSAL caches the token and renews it near expiry.
var token = await confidentialClient
.AcquireTokenForClient(new[] { $"api://{apiApplicationId}/.default" })
.ExecuteAsync();
var accessToken = token.AccessToken; # pip install msal requests
import os
import msal
tenant_id = os.environ["FTB_TENANT_ID"]
client_id = os.environ["FTB_CLIENT_ID"]
client_secret = os.environ["FTB_CLIENT_SECRET"] # from your secret store
api_application_id = os.environ["FTB_API_APPLICATION_ID"]
confidential_client = msal.ConfidentialClientApplication(
client_id,
authority=f"https://login.microsoftonline.com/{tenant_id}",
client_credential=client_secret,
)
# Reuse one client per process: MSAL caches the token until it nears expiry.
result = confidential_client.acquire_token_for_client(
scopes=[f"api://{api_application_id}/.default"]
)
if "access_token" not in result:
raise RuntimeError(f"Token request failed: {result.get('error')}")
access_token = result["access_token"] 3. Call the API
Send the token as a bearer token. This example reads one month of salary sacrifice nursery fee deductions for payroll.
curl --silent --fail-with-body --request GET \
--url "${FTB_API_BASE_URL}/api/v1/employers/${FTB_COMPANY_ID}/salary-sacrifice?startDate=2026-10-01&endDate=2026-10-31&page=1&pageSize=50" \
--header "Authorization: Bearer ${ACCESS_TOKEN}" \
--header "Accept: application/json" using System.Net.Http.Headers;
using System.Net.Http.Json;
var apiBaseUrl = Environment.GetEnvironmentVariable("FTB_API_BASE_URL")!;
var companyId = Environment.GetEnvironmentVariable("FTB_COMPANY_ID")!;
using var http = new HttpClient { BaseAddress = new Uri(apiBaseUrl) };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
http.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
var payroll = await http.GetFromJsonAsync<WorkforcePage<PayrollDeduction>>(
$"/api/v1/employers/{companyId}/salary-sacrifice?startDate=2026-10-01&endDate=2026-10-31&page=1&pageSize=50");
foreach (var row in payroll!.Data)
{
// Match to your payroll record by payrollReference, falling back to employeeId.
Console.WriteLine($"{row.PayrollReference ?? row.EmployeeId} {row.FeeMonth} {row.DeductionAmount:0.00} {row.Currency}");
}
public sealed record WorkforcePage<T>(IReadOnlyList<T> Data, int Page, int PageSize, int Total);
public sealed record PayrollDeduction(
string EmployeeId,
string EmployeeName,
string? PayrollReference,
string AgreementReference,
string InvoiceNumber,
string InvoiceDate,
string FeeMonth,
decimal DeductionAmount,
string Currency); import os
from decimal import Decimal
import requests
api_base_url = os.environ["FTB_API_BASE_URL"].rstrip("/")
company_id = os.environ["FTB_COMPANY_ID"]
response = requests.get(
f"{api_base_url}/api/v1/employers/{company_id}/salary-sacrifice",
params={"startDate": "2026-10-01", "endDate": "2026-10-31", "page": 1, "pageSize": 50},
headers={"Authorization": f"Bearer {access_token}", "Accept": "application/json"},
timeout=30,
)
response.raise_for_status()
# Parse money as Decimal, never float.
for row in response.json(parse_float=Decimal)["data"]:
# Match to your payroll record by payrollReference, falling back to employeeId.
print(row["payrollReference"] or row["employeeId"], row["feeMonth"], row["deductionAmount"], row["currency"]) Get salary sacrifice nursery fee deductions for payroll
GET/api/v1/employers/{employerId}/salary-sacrifice
Requires the Payroll.Read role. Returns one row per invoiced salary sacrifice nursery fee deduction for your company, so your payroll system can apply the correct deduction to each employee for each nursery fee month.
Using the data in your payroll run
- Match employees by
payrollReference. It isnullwhen no payroll reference is recorded; fall back toemployeeIdand keep your own mapping. - Apply the deduction in
deductionAmountto the nursery fee month infeeMonth. It is the nursery fee balance plus the scheme management fee, net of credits. - Handle credits: a fully credited invoice keeps its row with
deductionAmountof0.00, so reconcile byinvoiceNumberandfeeMonthrather than assuming rows disappear. - Choose the window by invoice date.
startDateandendDatefilter oninvoiceDate. Rows are ordered newest invoice first.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
employerId | path | string (uuid) | Yes | Your company ID from the onboarding handoff. It must match the company bound to your client. |
startDate | query | string (date) | Yes | Inclusive start of the invoice-date window, yyyy-MM-dd. |
endDate | query | string (date) | Yes | Inclusive end of the window, yyyy-MM-dd. The window cannot span more than 12 calendar months; see date windows. |
page | query | integer | No | One-based page number. Defaults to 1. |
pageSize | query | integer | No | Rows per page, 1 to 1000. Defaults to 50. |
Response fields
| Field | Type | Description |
|---|---|---|
employeeId | string | Feel The Benefit identifier for the employee. |
employeeName | string | Employee's name as recorded with Feel The Benefit. |
payrollReference | string or null | The employee's payroll reference recorded with Feel The Benefit, or null if none is recorded. |
agreementReference | string | Workplace nursery benefit agreement reference, for example #870021. |
invoiceNumber | string | Invoice that contains the deduction. |
invoiceDate | string (date) | Invoice date, yyyy-MM-dd. |
feeMonth | string | Nursery fee month the deduction relates to, yyyy-MM. |
deductionAmount | number | Salary sacrifice deduction for the fee month, to two decimal places. 0.00 when fully credited. |
currency | string | ISO 4217 currency code. Always GBP. |
Every response wraps rows in a page object: data (array of rows), page, pageSize and total (rows across all pages).
{
"data": [
{
"employeeId": "#10042",
"employeeName": "Alex Morgan",
"payrollReference": "PAY-1042",
"agreementReference": "#870021",
"invoiceNumber": "INV-2026-0042",
"invoiceDate": "2026-09-09",
"feeMonth": "2026-10",
"deductionAmount": 905.05,
"currency": "GBP"
}
],
"page": 1,
"pageSize": 50,
"total": 1
} Get workplace nursery benefit agreements for your HR platform
GET/api/v1/employers/{employerId}/agreements
Requires the HR.Read role. Returns each employee's workplace nursery benefit agreement with its status, dates and invoiced monthly deductions, so your HR platform can show up-to-date benefit details on the employee record.
Keeping your HR platform up to date
- An agreement is included when it has at least one invoiced deduction in the requested invoice-date window. The same
startDate,endDate,pageandpageSizeparameters apply as for the payroll endpoint. monthlyDeductionslists each invoiced fee month in the window with its total deduction, oldest first. A credited month remains with an amount of0.00.- Rows are ordered by
employeeId, thenagreementReference. - Schedule a regular sync, for example daily, rather than calling on every page view; the rate limits are sized for scheduled integrations.
Agreement statuses
| Status | Meaning |
|---|---|
Active | The agreement is in force. |
Expired | The agreement was active but its scheduled end date has passed. |
Completed | The agreement has completed. |
Cancelled | The agreement was cancelled. |
Response fields
| Field | Type | Description |
|---|---|---|
employeeId | string | Feel The Benefit identifier for the employee. |
employeeName | string | Employee's name as recorded with Feel The Benefit. |
payrollReference | string or null | The employee's payroll reference recorded with Feel The Benefit, or null if none is recorded. |
agreementReference | string | Workplace nursery benefit agreement reference. |
startDate | string (date) or null | Agreement start date, yyyy-MM-dd. |
scheduledEndDate | string (date) or null | Scheduled end date at the end of the contract term, yyyy-MM-dd. |
status | string | One of Active, Expired, Completed or Cancelled. |
monthlyDeductions | array | Invoiced fee months in the window, each with feeMonth (yyyy-MM) and amount (number). |
currency | string | ISO 4217 currency code. Always GBP. |
curl --silent --fail-with-body --request GET \
--url "${FTB_API_BASE_URL}/api/v1/employers/${FTB_COMPANY_ID}/agreements?startDate=2026-04-01&endDate=2027-03-31&page=1&pageSize=50" \
--header "Authorization: Bearer ${ACCESS_TOKEN}" \
--header "Accept: application/json" var agreements = await http.GetFromJsonAsync<WorkforcePage<NurseryBenefitAgreement>>(
$"/api/v1/employers/{companyId}/agreements?startDate=2026-04-01&endDate=2027-03-31&page=1&pageSize=50");
foreach (var agreement in agreements!.Data)
{
var invoiced = agreement.MonthlyDeductions.Sum(month => month.Amount);
Console.WriteLine($"{agreement.EmployeeName}: {agreement.Status}, {agreement.StartDate} to {agreement.ScheduledEndDate}, invoiced {invoiced:0.00} {agreement.Currency}");
}
public sealed record NurseryBenefitAgreement(
string EmployeeId,
string EmployeeName,
string? PayrollReference,
string AgreementReference,
string? StartDate,
string? ScheduledEndDate,
string Status,
IReadOnlyList<MonthlyDeduction> MonthlyDeductions,
string Currency);
public sealed record MonthlyDeduction(string FeeMonth, decimal Amount); response = requests.get(
f"{api_base_url}/api/v1/employers/{company_id}/agreements",
params={"startDate": "2026-04-01", "endDate": "2027-03-31", "page": 1, "pageSize": 50},
headers={"Authorization": f"Bearer {access_token}", "Accept": "application/json"},
timeout=30,
)
response.raise_for_status()
for agreement in response.json(parse_float=Decimal)["data"]:
invoiced = sum((month["amount"] for month in agreement["monthlyDeductions"]), Decimal("0"))
print(agreement["employeeName"], agreement["status"], agreement["startDate"],
agreement["scheduledEndDate"], invoiced, agreement["currency"]) {
"data": [
{
"employeeId": "#10042",
"employeeName": "Alex Morgan",
"payrollReference": "PAY-1042",
"agreementReference": "#870021",
"startDate": "2026-01-15",
"scheduledEndDate": "2027-01-14",
"status": "Active",
"monthlyDeductions": [
{ "feeMonth": "2026-10", "amount": 905.05 }
],
"currency": "GBP"
}
],
"page": 1,
"pageSize": 50,
"total": 1
} Pagination and date windows
startDateandendDateare required, inclusive and inyyyy-MM-ddformat. A request can span at most 12 calendar months, counted by month:2026-04-01to2027-03-31is 12 months, but a UK tax year from2026-04-06to2027-04-05counts as 13 and returns400. Split longer periods into separate requests.pagedefaults to 1 andpageSizedefaults to 50, with a maximum of 1000. Defaults apply only when a parameter is omitted.- Supplied values must be single integers. Malformed, empty, repeated or out-of-range values return
400. - Read pages until you have received
totalrows. Each page counts towards the rate limit, so use the largest page size your system can process.
page=1
while : ; do
body=$(curl --silent --fail-with-body \
--url "${FTB_API_BASE_URL}/api/v1/employers/${FTB_COMPANY_ID}/salary-sacrifice?startDate=2026-04-01&endDate=2027-03-31&page=${page}&pageSize=1000" \
--header "Authorization: Bearer ${ACCESS_TOKEN}" \
--header "Accept: application/json")
echo "${body}" | jq -c '.data[]'
count=$(echo "${body}" | jq '.data | length')
size=$(echo "${body}" | jq '.pageSize')
total=$(echo "${body}" | jq '.total')
if [ "${count}" -eq 0 ] || [ $((page * size)) -ge "${total}" ]; then break; fi
page=$((page + 1))
done // Each page is one request against the rate limit, so use the largest page size you can process.
static async Task<List<PayrollDeduction>> GetAllPayrollAsync(
HttpClient http, string companyId, DateOnly startDate, DateOnly endDate)
{
var rows = new List<PayrollDeduction>();
for (var page = 1; ; page++)
{
var result = await http.GetFromJsonAsync<WorkforcePage<PayrollDeduction>>(
$"/api/v1/employers/{companyId}/salary-sacrifice?startDate={startDate:yyyy-MM-dd}&endDate={endDate:yyyy-MM-dd}&page={page}&pageSize=1000");
rows.AddRange(result!.Data);
if (result.Data.Count == 0 || page * result.PageSize >= result.Total)
{
return rows;
}
}
}
var rows = await GetAllPayrollAsync(http, companyId, new DateOnly(2026, 4, 1), new DateOnly(2027, 3, 31)); def get_all_payroll(start_date: str, end_date: str) -> list[dict]:
"""Each page is one request against the rate limit, so use the largest page size you can process."""
rows, page = [], 1
while True:
response = requests.get(
f"{api_base_url}/api/v1/employers/{company_id}/salary-sacrifice",
params={"startDate": start_date, "endDate": end_date, "page": page, "pageSize": 1000},
headers={"Authorization": f"Bearer {access_token}", "Accept": "application/json"},
timeout=30,
)
response.raise_for_status()
body = response.json(parse_float=Decimal)
rows.extend(body["data"])
if not body["data"] or page * body["pageSize"] >= body["total"]:
return rows
page += 1
rows = get_all_payroll("2026-04-01", "2027-03-31") Errors and retries
Errors use RFC 9457 application/problem+json and include a non-secret correlationId. Quote the correlation ID when contacting support; it lets us trace the request without you sharing tokens or payloads.
| Status | Meaning | What to do |
|---|---|---|
400 | Invalid dates, date window, page or page size. | Correct the request. Do not retry it unchanged. |
401 | Missing, expired, wrongly issued, wrongly scoped or invalid token. | Acquire a fresh application token for the correct environment. |
403 | Role missing, client unknown or disabled, or company mismatch. | Check your handoff values and contact us. The response deliberately does not say which check failed. |
429 | Minute or hourly request limit exceeded. | Back off before retrying; immediate repeated retries extend the problem. |
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
{
"type": "about:blank",
"title": "Forbidden",
"status": 403,
"detail": "Access denied.",
"correlationId": "0HN7Q2K4ABCDE:00000001"
} Rate limits
429. Wait for the window to reset before retrying.Credentials and versioning
/v1/ is the compatibility boundary.Security checklist for integrators
Payroll.Read, HR.Read or both.
OpenAPI 3.0 specification
The complete machine-readable contract for the Workforce API v1, generated from the API itself. Use it to generate a client in your language, import it into Postman or Insomnia, or validate responses in your tests. Environment values such as {tenantId}, {apiApplicationId} and {apiBaseUrl} are placeholders; use the values from your onboarding handoff.
Import into Postman
- Import the downloaded
openapi.jsonfile. - Set the collection's
baseUrlto your{apiBaseUrl}. - Under Authorization, choose OAuth 2.0 with the Client Credentials grant.
- Set the access token URL to your token endpoint, and the client ID and client secret from your handoff.
- Set the scope to
api://{apiApplicationId}/.defaultand send client authentication in the request body. - Use your company ID as
employerId. Do not persist or export the client secret from Postman.
{
"openapi": "3.0.1",
"info": {
"title": "Feel The Benefit Workforce API",
"description": "Invoice-backed payroll deductions and agreement history for one client-bound company.",
"version": "v1"
},
"servers": [
{
"url": "{apiBaseUrl}",
"description": "Environment base URL supplied during onboarding.",
"variables": {
"apiBaseUrl": {
"default": "https://api.example.com",
"description": "Replace with the base URL supplied in your secure integration handoff."
}
}
}
],
"paths": {
"/api/v1/employers/{employerId}/salary-sacrifice": {
"get": {
"tags": [
"Workforce API"
],
"summary": "Get invoice-backed payroll deductions",
"description": "Requires the Payroll.Read application role. Returns invoiced salary-sacrifice deductions for the client-bound employer.",
"operationId": "GetSalarySacrifice",
"parameters": [
{
"name": "employerId",
"in": "path",
"description": "Admin-issued company identifier. It must match the company bound to the calling client.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"example": "10000000-0000-0000-0000-000000000001"
},
{
"name": "startDate",
"in": "query",
"description": "Inclusive start date in yyyy-MM-dd format.",
"required": true,
"schema": {
"type": "string",
"format": "date"
},
"example": "2026-10-01"
},
{
"name": "endDate",
"in": "query",
"description": "Inclusive end date in yyyy-MM-dd format. The date window cannot span more than 12 months.",
"required": true,
"schema": {
"type": "string",
"format": "date"
},
"example": "2026-10-31"
},
{
"name": "page",
"in": "query",
"description": "One-based page number. Defaults to 1.",
"schema": {
"minimum": 1,
"type": "integer",
"format": "int32",
"default": 1
},
"example": 1
},
{
"name": "pageSize",
"in": "query",
"description": "Number of rows per page. Defaults to 50; maximum 1000.",
"schema": {
"maximum": 1000,
"minimum": 1,
"type": "integer",
"format": "int32",
"default": 50
},
"example": 50
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkforcePayrollRowWorkforceApiPage"
},
"example": {
"data": [
{
"employeeId": "#10042",
"employeeName": "Alex Morgan",
"payrollReference": "PAY-1042",
"agreementReference": "#870021",
"invoiceNumber": "INV-2026-0042",
"invoiceDate": "2026-09-09",
"feeMonth": "2026-10",
"deductionAmount": 905.05,
"currency": "GBP"
}
],
"page": 1,
"pageSize": 50,
"total": 1
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v1/employers/{employerId}/agreements": {
"get": {
"tags": [
"Workforce API"
],
"summary": "Get invoice-backed agreement history",
"description": "Requires the HR.Read application role. Returns agreements having invoiced deductions in the requested window.",
"operationId": "GetAgreements",
"parameters": [
{
"name": "employerId",
"in": "path",
"description": "Admin-issued company identifier. It must match the company bound to the calling client.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"example": "10000000-0000-0000-0000-000000000001"
},
{
"name": "startDate",
"in": "query",
"description": "Inclusive start date in yyyy-MM-dd format.",
"required": true,
"schema": {
"type": "string",
"format": "date"
},
"example": "2026-10-01"
},
{
"name": "endDate",
"in": "query",
"description": "Inclusive end date in yyyy-MM-dd format. The date window cannot span more than 12 months.",
"required": true,
"schema": {
"type": "string",
"format": "date"
},
"example": "2026-10-31"
},
{
"name": "page",
"in": "query",
"description": "One-based page number. Defaults to 1.",
"schema": {
"minimum": 1,
"type": "integer",
"format": "int32",
"default": 1
},
"example": 1
},
{
"name": "pageSize",
"in": "query",
"description": "Number of rows per page. Defaults to 50; maximum 1000.",
"schema": {
"maximum": 1000,
"minimum": 1,
"type": "integer",
"format": "int32",
"default": 50
},
"example": 50
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkforceHrRowWorkforceApiPage"
},
"example": {
"data": [
{
"employeeId": "#10042",
"employeeName": "Alex Morgan",
"payrollReference": "PAY-1042",
"agreementReference": "#870021",
"startDate": "2026-01-15",
"scheduledEndDate": "2027-01-14",
"status": "Active",
"monthlyDeductions": [
{
"feeMonth": "2026-10",
"amount": 905.05
}
],
"currency": "GBP"
}
],
"page": 1,
"pageSize": 50,
"total": 1
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"ProblemDetails": {
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"type": "integer",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"additionalProperties": {}
},
"WorkforceHrRow": {
"type": "object",
"properties": {
"employeeId": {
"type": "string",
"nullable": true
},
"employeeName": {
"type": "string",
"nullable": true
},
"payrollReference": {
"type": "string",
"nullable": true
},
"agreementReference": {
"type": "string",
"nullable": true
},
"startDate": {
"type": "string",
"nullable": true
},
"scheduledEndDate": {
"type": "string",
"nullable": true
},
"status": {
"type": "string",
"nullable": true
},
"monthlyDeductions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkforceMonthlyDeduction"
},
"nullable": true
},
"currency": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"WorkforceHrRowWorkforceApiPage": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkforceHrRow"
},
"nullable": true
},
"page": {
"type": "integer",
"format": "int32"
},
"pageSize": {
"type": "integer",
"format": "int32"
},
"total": {
"type": "integer",
"format": "int32"
}
},
"additionalProperties": false
},
"WorkforceMonthlyDeduction": {
"type": "object",
"properties": {
"feeMonth": {
"type": "string",
"nullable": true
},
"amount": {
"type": "number",
"format": "double"
}
},
"additionalProperties": false
},
"WorkforcePayrollRow": {
"type": "object",
"properties": {
"employeeId": {
"type": "string",
"nullable": true
},
"employeeName": {
"type": "string",
"nullable": true
},
"payrollReference": {
"type": "string",
"nullable": true
},
"agreementReference": {
"type": "string",
"nullable": true
},
"invoiceNumber": {
"type": "string",
"nullable": true
},
"invoiceDate": {
"type": "string",
"nullable": true
},
"feeMonth": {
"type": "string",
"nullable": true
},
"deductionAmount": {
"type": "number",
"format": "double"
},
"currency": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"WorkforcePayrollRowWorkforceApiPage": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkforcePayrollRow"
},
"nullable": true
},
"page": {
"type": "integer",
"format": "int32"
},
"pageSize": {
"type": "integer",
"format": "int32"
},
"total": {
"type": "integer",
"format": "int32"
}
},
"additionalProperties": false
}
},
"securitySchemes": {
"oauth2": {
"type": "oauth2",
"description": "Microsoft Entra application-only OAuth 2.0. Request the API's /.default scope; delegated user tokens are rejected.",
"flows": {
"clientCredentials": {
"tokenUrl": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
"scopes": {
"api://{apiApplicationId}/.default": "Application roles assigned to this client (Payroll.Read and/or HR.Read)."
}
}
}
}
}
},
"security": [
{
"oauth2": [
"api://{apiApplicationId}/.default"
]
}
]
} Try the synthetic demo
See the shape of real responses before onboarding. The demo page shows the first page of genuine cached payroll and HR API responses, built from synthetic Sandbox data, through our public backend and without any credentials in your browser.
- Visitor’s browserExplicit demo button only
- Public .NET backendValidates request, applies anti-abuse limits and sends an admin notification
- Server-side data cacheSynthetic API responses; refresh at most once every 6 hours
- Restricted Sandbox APIServer-to-server access only; never contacted by the browser
Server-side token cache → supports authenticated Sandbox access. Tokens and credentials remain on the server.
The output is genuine cached synthetic API output, not live-per-click data or a fabricated browser response. Refreshes occur at most once every 6 hours. A timestamp identifies when the data was fetched; stale results may be served for up to 24 hours and are labelled clearly.
Every accepted button request triggers an admin email from the backend, including the trusted source IP. Server-side anti-abuse limits protect the demo. A button request does not guarantee a new upstream fetch.
Payroll and HR API FAQs
Yes. Feel The Benefit provides full payroll data integration through its Workforce API. The payroll endpoint returns one row per invoiced salary sacrifice nursery fee deduction, with the employee, payroll reference, fee month, deduction amount and invoice, so your payroll platform can apply the correct workplace nursery deduction without re-keying.
Yes. Feel The Benefit provides full HR integration through the same API. The HR endpoint returns each employee's workplace nursery benefit agreement with its status, start date, scheduled end date and invoiced monthly deductions, so your HR platform can keep employee benefit records current on demand.
Yes. The complete OpenAPI 3.0 specification is published on the developer guide and can be downloaded as JSON. Use it to generate a client in your language, import it into Postman or Insomnia, or validate responses in your tests.
Each API request reads our live data at the moment you call it, so your systems can update securely and instantly whenever you like within the limits of 15 requests per minute and 100 requests per hour. The data is invoice-backed: it reflects deductions that have been invoiced, including credits, rather than projected future deductions.
Each integration authenticates from your server with Microsoft Entra ID OAuth 2.0 client credentials and is bound to your company only, so it can never read another employer's data. Roles limit access to payroll data, HR data or both. Client secrets expire after 180 days, requests are rate limited, and errors never expose internal details.
Any platform, integration tool or custom middleware that can make HTTPS requests and authenticate with OAuth 2.0 client credentials. If you prefer not to integrate, the payroll deduction file can be imported directly or keyed manually; see payroll integrations.
API access is set up for employer clients during onboarding. We send your developers the environment details, client credentials, company ID and assigned roles through a secure channel. Contact us to start a payroll or HR integration.
Yes. We can accommodate other data connections for clients with bespoke requirements, on request and at an additional charge.
Talk to Feel The Benefit Ltd
Discuss payroll and HR integration with our team. We can explain the approved integration contract, onboarding and the access your developers will need.
Get in touch
Our team is ready to answer any questions you may have.