POST/v1/compliance/pay-gap-report

Generate a gender pay gap report from anonymised workforce data

Generate a statistical gender pay gap analysis from a list of employee records for EU Pay Transparency Directive (2023/970) reporting. Use this when an HR department needs to calculate mean and median pay gaps for filing, or wants to benchmark their gap against the national average before publishing. **Inputs:** a country code and a list of `EmployeeRecord` objects — each with a job title, gender (M/F), salary, salary period, and employment type. The list must contain at least 2 and at most 10,000 records per request. **What it computes:** - Overall mean and median pay gap across the full workforce. - Per-ISCO-category breakdown (job titles are matched to ISCO major groups) including male/female headcounts, mean salaries per gender, per-category gap percentage, and a `requires_joint_assessment` flag when a category gap is >= 5 percent (Article 10 trigger). - Benchmark against the Eurostat national average gap. - A list of `recommendations` and a methodology note. **Privacy:** computation is fully stateless — no employee data is stored. The endpoint also applies a `k_anonymity_warning` to any category with fewer than 5 employees of a given gender. **Not legal advice** — consult an employment lawyer for formal Article 9/10 reporting. Source: EU Directive 2023/970, Eurostat gender pay gap statistics. Required scope: `compliance:report` (Enterprise tier).

Authentication

Requires API key via X-API-Key header.

Request body

countrystringrequired

employeesarray<EmployeeRecord>required

minItems 2 · maxItems 10000

array of EmployeeRecord

job_titlestringrequired

genderstringrequiredenum: M | F

salarynumberrequired

salary_periodstringoptionalenum: annual | monthly | hourly

default "annual"

employment_typestringoptionalenum: full_time | part_time

default "full_time"

Example request

curl

curl -X POST \
  "https://salary.wageapi.com/api/v1/compliance/pay-gap-report" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"DE","employees":[{"employment_type":"full_time","gender":"M","job_title":"Software Developer","salary":72000,"salary_period":"annual"},{"employment_type":"full_time","gender":"F","job_title":"Software Developer","salary":68000,"salary_period":"annual"},{"employment_type":"full_time","gender":"M","job_title":"Product Manager","salary":85000,"salary_period":"annual"},{"employment_type":"full_time","gender":"F","job_title":"Product Manager","salary":82000,"salary_period":"annual"}]}'

Responses

200Successful Response

country_codestringrequired

country_namestringrequired

overall_mean_gap_pctnumberrequired

overall_median_gap_pctnumberrequired

categoriesarray<CategoryGap>required

array of CategoryGap

isco_codestringrequired

category_namestringrequired

employee_countintegerrequired

male_countintegerrequired

female_countintegerrequired

mean_malenumberrequired

mean_femalenumberrequired

gap_pctnumberrequired

median_gap_pctanyoptional

one of:

option 1:

number

option 2:

null

requires_joint_assessmentbooleanrequired

national_benchmark_gap_pctanyrequired

one of:

option 1:

number

option 2:

null

k_anonymity_warningbooleanoptional

default false

national_average_gap_pctanyrequired

one of:

option 1:

number

option 2:

null

total_employeesintegerrequired

requires_any_joint_assessmentbooleanrequired

recommendationsarray<string>required

array of string

string

methodology_notestringrequired

disclaimerstringoptional

default "This report is a statistical analysis tool based on the data provided. It does not constitute legal advice or a formal pay gap audit. Consult a qualified employment lawyer for EU Directive 2023/970 compliance."

401Missing or invalid API key.

errorErrorDetailrequired

Structured error payload returned by all Aethar APIs. Mirrors the shape produced by aethar_auth.exception_handlers so the OpenAPI spec accurately describes real error bodies for documentation readers and MCP clients.

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

403API key lacks the required scope for this endpoint.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

422Unsupported country or malformed employee records.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

429Daily rate limit exceeded for this API key.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

500Unexpected server error. Includes a request_id for support.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

Try this endpoint

Create a free Aethar account and generate an API key in 2 minutes.

Create free account →