Employment API Reference

Minimum Wage

GET /v1/employment/minimum-wage/rates

Current national minimum and living wage rates by age band.

Query parameters

Parameter	Type	Required	Description
`tax_year`	string	No	Tax year in `YYYY-YY` format. Defaults to current year.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.govdata.dev/v1/employment/minimum-wage/rates

Response

{
  "data": {
    "tax_year": "2025-26",
    "effective_from": "2025-04-01",
    "rates": [
      { "band": "National Living Wage (21+)", "hourly_rate": 12.21 },
      { "band": "18-20", "hourly_rate": 10.00 },
      { "band": "16-17", "hourly_rate": 7.55 },
      { "band": "Apprentice", "hourly_rate": 7.55 }
    ]
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "GOV.UK",
    "source_url": "https://www.gov.uk/national-minimum-wage-rates"
  }
}

Auto-Enrolment

GET /v1/employment/auto-enrolment/thresholds

Pension auto-enrolment earnings thresholds and contribution rates.

Query parameters

Parameter	Type	Required	Description
`tax_year`	string	No	Tax year in `YYYY-YY` format. Defaults to current year.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.govdata.dev/v1/employment/auto-enrolment/thresholds

Response

{
  "data": {
    "tax_year": "2025-26",
    "thresholds": {
      "lower_qualifying_earnings": 6240,
      "earnings_trigger": 10000,
      "upper_qualifying_earnings": 50270
    },
    "contribution_rates": {
      "employee_minimum": 0.05,
      "employer_minimum": 0.03,
      "total_minimum": 0.08
    }
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "GOV.UK",
    "source_url": "https://www.gov.uk/workplace-pensions/what-your-employer-must-do"
  }
}

Gender Pay Gap

Search statutory employer reports to benchmark organisations, research sectors, or chart an employer's published history. Percentages are returned as rates: 0.067 means 6.7%, while a negative gap means women's pay was higher.

Search reports

GET /v1/employment/pay-gap

Name	Type	Required	Default	Description
`employer_name`	string	No	—	Case-insensitive literal prefix; % and _ are not wildcards.
`company_number`	string	No	—	Exact Companies House number.
`year`	integer	No	—	Start year from 2017 through the current reporting year.
`sic_code`	string	No	—	Exact code in the employer's reported SIC-code list.
`page`	integer	No	1	Page number.
`per_page`	integer	No	25	Records per page, from 1 to 100.

curl -G -H "Authorization: Bearer YOUR_API_KEY" --data-urlencode "employer_name=HM T" --data-urlencode "year=2025" https://api.govdata.dev/v1/employment/pay-gap

Employer history

Return every loaded report for one service employer ID or company number, ordered oldest first. Use this for trend charts or due-diligence timelines.

GET /v1/employment/pay-gap/history

Name	Type	Required	Default	Description
`company_number`	string	Conditional	—	Required unless `employer_id` is supplied.
`employer_id`	integer	Conditional	—	Required unless `company_number` is supplied.

curl -G -H "Authorization: Bearer YOUR_API_KEY" --data-urlencode "employer_id=303" https://api.govdata.dev/v1/employment/pay-gap/history

Captured response

{"data":[{"employer_id":697,"employer_name":"3663 TRANSPORT LIMITED","current_name":"3663 TRANSPORT LIMITED","reporting_year":2025,"company_number":"00456846","address":"814 Leigh Road, Slough, England, SL1 4BD","postcode":"SL1 4BD","sic_codes":["52290"],"employer_size":"1000 to 4999","pay_gaps":{"mean_hourly":-0.0469,"median_hourly":-0.0006,"mean_bonus":-10.6186,"median_bonus":-20.0},"bonus_rates":{"male":0.1064,"female":0.18},"quartile_rates":{"lower":{"male":0.9292,"female":0.0708},"lower_middle":{"male":0.972,"female":0.028},"upper_middle":{"male":0.9591,"female":0.0409},"top":{"male":0.9376,"female":0.0624}},"responsible_person":"Heather Angus (People Director)","company_link":null,"submitted_late":false,"due_at":"2026-04-05T00:00:00.000Z","submitted_at":"2026-04-02T14:38:12.000Z","company":null}],"meta":{"api_version":"v1","licence":"Open Government Licence v3.0","source":"UK Gender Pay Gap Service","source_url":"https://gender-pay-gap.service.gov.uk/viewing/download","reporting_years":"2017-18 to 2026-27"},"pagination":{"total":1,"page":1,"per_page":25,"total_pages":1}}

Captured after a development database reset and import of the trimmed real 2025 fixture. company is null when the Companies House dataset has no matching loaded company; otherwise it contains number, name, and status. Blank source percentages remain null, never zero.

Errors

HTTP 400
{"error":{"code":"invalid_parameter","message":"year must be an integer.","documentation_url":"https://docs.govdata.dev/errors/invalid_parameter"}}

HTTP 404
{"error":{"code":"not_found","message":"No pay-gap reports found for that employer.","documentation_url":"https://docs.govdata.dev/errors/not_found"}}

HTTP 422
{"error":{"code":"invalid_year","message":"year must be between 2017 and 2026.","documentation_url":"https://docs.govdata.dev/errors/invalid_year"}}

Coverage and cadence: 94,471 unique employer-year reports across every available file: 2017-18 through partial 2026-27. Completed reporting deadlines are 30 March for most public authorities and 4 April for other employers, so GovData refreshes annually on 7 April. The current year may grow through late submissions.

Licence and caveats: Gender Pay Gap Service, Open Government Licence v3.0. Values are employer-submitted and can contain blanks, negative gaps, extreme bonus percentages, late corrections, changing names, and missing company numbers for public bodies. A report describes an employer, not necessarily a single legal company.

ASHE Earnings

GET /v1/employment/earnings

Median and mean gross hourly, weekly and annual earnings from ASHE Tables 5 and 29. Results are paginated. ONS x/.. markers become null with suppressed: true; null never means zero.

Query parameters

Name	Type	Required	Default	Description
`year`	integer	No	—	ASHE reference year, for example 2025.
`region`	string	No	—	Region name or official geography code, for example London or E12000007.
`industry_code`	string	No	—	SIC 2007 industry code, including all for the aggregate.
`occupation_code`	string	No	—	SOC 2020 occupation code, including all for the aggregate.
`statistic`	string	No	—	Filter by mean or median.
`suppressed`	boolean	No	—	Filter by whether ONS suppressed the estimate.
`page`	integer	No	1	Page number.
`per_page`	integer	No	25	Records per page, from 1 to 100.

curl -G -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "year=2025" --data-urlencode "region=London" \
  --data-urlencode "statistic=mean" \
  https://api.govdata.dev/v1/employment/earnings

Response

{
  "data": [
    {
      "year": 2025,
      "geography": { "code": "E12000007", "name": "London" },
      "industry": { "code": "all", "name": "All industries" },
      "occupation": { "code": "all", "name": "All occupations" },
      "statistic": "mean",
      "median": { "hourly_pay": null, "weekly_pay": null, "annual_pay": null },
      "mean": { "hourly_pay": 30.94, "weekly_pay": 1047.3, "annual_pay": 60673.0 },
      "suppressed": false,
      "source_table": 5
    }
  ],
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "ONS Annual Survey of Hours and Earnings",
    "source_url": "https://www.ons.gov.uk/employmentandlabourmarket/peopleinwork/earningsandworkinghours/datasets/regionbyindustry2digitsicashetable5"
  },
  "pagination": { "total": 1, "page": 1, "per_page": 25, "total_pages": 1 }
}

Data Coverage

Source	HMRC / GOV.UK / ONS
Date range	Minimum wage and auto-enrolment: 2020-21 to 2026-27 tax years; ASHE earnings: 2025 provisional reference year
Records	Minimum wage rates, auto-enrolment thresholds, and ASHE earnings by geography, industry, and occupation
Updated	Annually
Limitations	Historical rates before 2020-21 are not available. Minimum-wage bands follow the law in each year: NLW applied from age 25 in 2020-21, age 23 from 2021-22, and age 21 from 2024-25; a separate age 21–22 band therefore exists only from 2021-22 through 2023-24.