Payroll & HR API for salary sacrifice nursery fees

Bring nursery fee deductions into payroll and workplace nursery benefit details into your HR platform.

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 and HR API integration for the salary sacrifice nursery fee scheme
Overview

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

Deductions for payroll

One row per invoiced salary sacrifice nursery fee deduction: employee, payroll reference, fee month, amount and invoice. Requires the Payroll.Read role.
Benefit details for HR

Benefit details for HR

Workplace nursery benefit agreements per employee: status, start date, scheduled end date and invoiced monthly deductions. Requires the HR.Read role.
At A Glance

API at a glance

Workforce API v1 summary
Base URL{apiBaseUrl}, supplied for your environment during onboarding
AuthenticationMicrosoft Entra ID OAuth 2.0 client credentials (application-only)
Token URLhttps://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
Scopeapi://{apiApplicationId}/.default
RolesPayroll.Read, HR.Read, or both
FormatJSON over HTTPS; money as numbers to two decimal places; currency GBP
ErrorsRFC 9457 application/problem+json with a correlationId
Rate limits15 requests per minute and 100 per hour, per client and environment
VersioningMajor version in the URL: /api/v1/
SpecificationOpenAPI 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

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 employerId in 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.

Environment variables used by the samples
# 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.

Request an app-only access token (cURL + jq)
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')
Request an app-only access token (C# with MSAL)
// 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;
Request an app-only access token (Python with MSAL)
# 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.

GET salary sacrifice nursery fee deductions (cURL)
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"
GET salary sacrifice nursery fee deductions (C#)
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);
GET salary sacrifice nursery fee deductions (Python)
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"])
Payroll Endpoint

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 is null when no payroll reference is recorded; fall back to employeeId and keep your own mapping.
  • Apply the deduction in deductionAmount to the nursery fee month in feeMonth. It is the nursery fee balance plus the scheme management fee, net of credits.
  • Handle credits: a fully credited invoice keeps its row with deductionAmount of 0.00, so reconcile by invoiceNumber and feeMonth rather than assuming rows disappear.
  • Choose the window by invoice date. startDate and endDate filter on invoiceDate. Rows are ordered newest invoice first.

Parameters

NameInTypeRequiredDescription
employerIdpathstring (uuid)YesYour company ID from the onboarding handoff. It must match the company bound to your client.
startDatequerystring (date)YesInclusive start of the invoice-date window, yyyy-MM-dd.
endDatequerystring (date)YesInclusive end of the window, yyyy-MM-dd. The window cannot span more than 12 calendar months; see date windows.
pagequeryintegerNoOne-based page number. Defaults to 1.
pageSizequeryintegerNoRows per page, 1 to 1000. Defaults to 50.

Response fields

FieldTypeDescription
employeeIdstringFeel The Benefit identifier for the employee.
employeeNamestringEmployee's name as recorded with Feel The Benefit.
payrollReferencestring or nullThe employee's payroll reference recorded with Feel The Benefit, or null if none is recorded.
agreementReferencestringWorkplace nursery benefit agreement reference, for example #870021.
invoiceNumberstringInvoice that contains the deduction.
invoiceDatestring (date)Invoice date, yyyy-MM-dd.
feeMonthstringNursery fee month the deduction relates to, yyyy-MM.
deductionAmountnumberSalary sacrifice deduction for the fee month, to two decimal places. 0.00 when fully credited.
currencystringISO 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).

200 OK: application/json
{
  "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
}
HR Endpoint

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, page and pageSize parameters apply as for the payroll endpoint.
  • monthlyDeductions lists each invoiced fee month in the window with its total deduction, oldest first. A credited month remains with an amount of 0.00.
  • Rows are ordered by employeeId, then agreementReference.
  • Schedule a regular sync, for example daily, rather than calling on every page view; the rate limits are sized for scheduled integrations.

Agreement statuses

StatusMeaning
ActiveThe agreement is in force.
ExpiredThe agreement was active but its scheduled end date has passed.
CompletedThe agreement has completed.
CancelledThe agreement was cancelled.

Response fields

FieldTypeDescription
employeeIdstringFeel The Benefit identifier for the employee.
employeeNamestringEmployee's name as recorded with Feel The Benefit.
payrollReferencestring or nullThe employee's payroll reference recorded with Feel The Benefit, or null if none is recorded.
agreementReferencestringWorkplace nursery benefit agreement reference.
startDatestring (date) or nullAgreement start date, yyyy-MM-dd.
scheduledEndDatestring (date) or nullScheduled end date at the end of the contract term, yyyy-MM-dd.
statusstringOne of Active, Expired, Completed or Cancelled.
monthlyDeductionsarrayInvoiced fee months in the window, each with feeMonth (yyyy-MM) and amount (number).
currencystringISO 4217 currency code. Always GBP.
GET workplace nursery benefit agreements (cURL)
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"
GET workplace nursery benefit agreements (C#)
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);
GET workplace nursery benefit agreements (Python)
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"])
200 OK: application/json
{
  "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

Pagination and date windows

  • startDate and endDate are required, inclusive and in yyyy-MM-dd format. A request can span at most 12 calendar months, counted by month: 2026-04-01 to 2027-03-31 is 12 months, but a UK tax year from 2026-04-06 to 2027-04-05 counts as 13 and returns 400. Split longer periods into separate requests.
  • page defaults to 1 and pageSize defaults 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 total rows. Each page counts towards the rate limit, so use the largest page size your system can process.
Read every page for a 12-month window (bash + jq)
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
Read every page for a 12-month window (C#)
// 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));
Read every page for a 12-month window (Python)
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

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.

StatusMeaningWhat to do
400Invalid dates, date window, page or page size.Correct the request. Do not retry it unchanged.
401Missing, expired, wrongly issued, wrongly scoped or invalid token.Acquire a fresh application token for the correct environment.
403Role missing, client unknown or disabled, or company mismatch.Check your handoff values and contact us. The response deliberately does not say which check failed.
429Minute or hourly request limit exceeded.Back off before retrying; immediate repeated retries extend the problem.
Example error response
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

Rate limits

15 requests per minute per client and environment.
100 requests per hour per client and environment.
Exceeding either window returns 429. Wait for the window to reset before retrying.
Token requests go to Microsoft Entra ID and do not count towards these limits.
Credentials And Versioning

Credentials and versioning

Renew before 180 days. Client secrets expire after 180 days; request renewal in good time. During an approved rotation the old credential may overlap for no more than 30 days.
The URL major version is the contract. /v1/ is the compatibility boundary.
Ignore unknown properties. Optional fields may be added within v1.
Breaking changes need a new major version. Removing or renaming fields, changing a type or meaning, or making optional data required. Deprecations are announced before removal.
Security Checklist

Security checklist for integrators

Keep authentication server-side. Store credentials in a secret store and request tokens from your server. Never put tokens or secrets in browser code, URLs or logs.
Request only what you need. Ask for only the roles your integration uses: Payroll.Read, HR.Read or both.
Protect personal data. Responses contain employee names and payroll references. Store them under your data protection controls and keep raw payloads out of logs.
Validate before reconciling. Check dates, currency and amounts before applying deductions in payroll.
Test with synthetic data first. Verify permissions and reconciliation before using production information.
Person reconciling payroll paperwork on a laptop with a calculator
OpenAPI Specification

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.

Download the OpenAPI JSON

Import into Postman

  1. Import the downloaded openapi.json file.
  2. Set the collection's baseUrl to your {apiBaseUrl}.
  3. Under Authorization, choose OAuth 2.0 with the Client Credentials grant.
  4. Set the access token URL to your token endpoint, and the client ID and client secret from your handoff.
  5. Set the scope to api://{apiApplicationId}/.default and send client authentication in the request body.
  6. Use your company ID as employerId. Do not persist or export the client secret from Postman.
workforce-api-openapi.v1.json
{
  "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"
      ]
    }
  ]
}
Synthetic Demo

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.

  1. Visitor’s browserExplicit demo button only
  2. Public .NET backendValidates request, applies anti-abuse limits and sends an admin notification
  3. Server-side data cacheSynthetic API responses; refresh at most once every 6 hours
  4. 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.

Demo architecture: browser → public backend → server cache → restricted Sandbox. Cached results return through the public backend, not directly from the Sandbox.

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.

Explore synthetic API examples

FAQs

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.

Fully managed from day one
No set up fees
Dedicated support throughout

Get in touch


Our team is ready to answer any questions you may have.