> ## Documentation Index > Fetch the complete documentation index at: https://docs.intermezzo.ai/llms.txt > Use this file to discover all available pages before exploring further. # List High Earners > Employees whose annualised gross exceeds £100,000 for the tax year. ## OpenAPI ````yaml /api-reference/preview.json get /gb/organizations/{organization_id}/reports/high-earners/{tax_year} openapi: 3.2.0 info: title: Intermezzo Global Payroll summary: Global Payroll Platform description: Intermezzo's global payroll apis, organized by country version: '2026-10-16' x-logo: url: /static/icon.svg servers: - url: https://preview.intermezzo.ai description: Preview security: [] paths: /gb/organizations/{organization_id}/reports/high-earners/{tax_year}: get: tags: - Great Britain - Reports summary: List High Earners description: Employees whose annualised gross exceeds £100,000 for the tax year. operationId: >- list_high_earners_gb_organizations__organization_id__reports_high_earners__tax_year__get parameters: - name: organization_id in: path required: true schema: type: string title: Organization Id - name: tax_year in: path required: true schema: type: integer maximum: 2100 minimum: 1901 description: Tax year start (2025 = 2025-26) title: Tax Year description: Tax year start (2025 = 2025-26) - name: breach_only in: query required: false schema: type: boolean description: >- Return only employees whose projected pension input exceeds their Annual Allowance. default: false title: Breach Only description: >- Return only employees whose projected pension input exceeds their Annual Allowance. - name: as_of_tax_month in: query required: false schema: anyOf: - type: integer maximum: 12 minimum: 1 - type: 'null' description: >- Reproduce the projection as at this tax month. Omitted, each employee's latest snapshot is used. title: As Of Tax Month description: >- Reproduce the projection as at this tax month. Omitted, each employee's latest snapshot is used. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Items per page default: 10 title: Limit description: Items per page - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: '`next_cursor` of the previous response, for the next page' title: Cursor description: '`next_cursor` of the previous response, for the next page' - name: prev_cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: >- `prev_cursor` of the previous response, for the page before it. Not together with `cursor`. title: Prev Cursor description: >- `prev_cursor` of the previous response, for the page before it. Not together with `cursor`. - name: sort in: query required: false schema: type: array items: type: string description: >- Fields to order by, `-` in front for descending (`-created_at`). Repeat the parameter for more fields. Keep the same sort while following cursors. default: - id title: Sort description: >- Fields to order by, `-` in front for descending (`-created_at`). Repeat the parameter for more fields. Keep the same sort while following cursors. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/HighEarnersListResponse' '400': description: >- - `ORG_BELONGS_TO_A_DIFFERENT_COUNTRY`: Raised when an organization belongs to a different country than the one in the path. content: application/json: schema: type: object title: ErrorResponse required: - errors properties: errors: type: array items: additionalProperties: false description: >- Represents an error that occurred during processing. Designed for client-side i18n: - code: Use this to look up translation (e.g., "ORG_NOT_FOUND") - message: English fallback if translation not available - field: Field name for form validation highlighting - params: Dynamic values for translation interpolation properties: code: type: string enum: - ORG_BELONGS_TO_A_DIFFERENT_COUNTRY title: Code description: Unique error code for i18n lookup message: type: string title: Message description: English fallback error message field: anyOf: - type: string - type: 'null' title: Field description: Field that caused the error params: anyOf: - additionalProperties: true type: object - type: 'null' title: Params description: Parameters for translation interpolation required: - code - message title: ErrorDetail type: object examples: ORG_BELONGS_TO_A_DIFFERENT_COUNTRY: summary: >- Raised when an organization belongs to a different country than the one in the path. value: errors: - code: ORG_BELONGS_TO_A_DIFFERENT_COUNTRY message: >- Raised when an organization belongs to a different country than the one in the path. '404': description: >- - `ORG_NOT_FOUND`: Raised when an organization is not found. - `HIGH_EARNERS_NO_SNAPSHOTS`: Raised when no period snapshots exist for the requested tax year. content: application/json: schema: type: object title: ErrorResponse required: - errors properties: errors: type: array items: additionalProperties: false description: >- Represents an error that occurred during processing. Designed for client-side i18n: - code: Use this to look up translation (e.g., "ORG_NOT_FOUND") - message: English fallback if translation not available - field: Field name for form validation highlighting - params: Dynamic values for translation interpolation properties: code: type: string enum: - ORG_NOT_FOUND - HIGH_EARNERS_NO_SNAPSHOTS title: Code description: Unique error code for i18n lookup message: type: string title: Message description: English fallback error message field: anyOf: - type: string - type: 'null' title: Field description: Field that caused the error params: anyOf: - additionalProperties: true type: object - type: 'null' title: Params description: Parameters for translation interpolation required: - code - message title: ErrorDetail type: object examples: ORG_NOT_FOUND: summary: Raised when an organization is not found. value: errors: - code: ORG_NOT_FOUND message: Raised when an organization is not found. HIGH_EARNERS_NO_SNAPSHOTS: summary: >- Raised when no period snapshots exist for the requested tax year. value: errors: - code: HIGH_EARNERS_NO_SNAPSHOTS message: >- Raised when no period snapshots exist for the requested tax year. '422': description: >- The request failed validation. Type and format errors use the generic FIELD_* codes. - `HIGH_EARNERS_UNSUPPORTED_TAX_YEAR`: Raised when the High Earners report is asked for a tax year with no statutory constants (PA/AA taper, tax bands) defined. - `HIGH_EARNERS_INVALID_CURSOR`: Raised when the cursor passed to the High Earners list endpoint cannot be decoded or does not carry the expected sort-key fields. content: application/json: schema: type: object title: ErrorResponse required: - errors properties: errors: type: array items: additionalProperties: false description: >- Represents an error that occurred during processing. Designed for client-side i18n: - code: Use this to look up translation (e.g., "ORG_NOT_FOUND") - message: English fallback if translation not available - field: Field name for form validation highlighting - params: Dynamic values for translation interpolation properties: code: type: string enum: - HIGH_EARNERS_UNSUPPORTED_TAX_YEAR - HIGH_EARNERS_INVALID_CURSOR - FIELD_REQUIRED - FIELD_INVALID_TYPE_STRING - FIELD_INVALID_TYPE_INT - FIELD_INVALID_TYPE_FLOAT - FIELD_INVALID_TYPE_BOOL - FIELD_INVALID_TYPE_DICT - FIELD_INVALID_TYPE_LIST - FIELD_STRING_TOO_SHORT - FIELD_STRING_TOO_LONG - FIELD_STRING_PATTERN_MISMATCH - FIELD_VALUE_TOO_SMALL - FIELD_VALUE_TOO_LARGE - FIELD_INVALID_DATE - FIELD_INVALID_DATETIME - FIELD_INVALID_TIME - FIELD_INVALID_DATE_FORMAT - FIELD_INVALID_DATETIME_FORMAT - FIELD_INVALID_ENUM_VALUE - FIELD_INVALID_EMAIL - FIELD_INVALID_URL - FIELD_LIST_TOO_SHORT - FIELD_LIST_TOO_LONG - FIELD_UNKNOWN - FIELD_VALIDATION_ERROR title: Code description: Unique error code for i18n lookup message: type: string title: Message description: English fallback error message field: anyOf: - type: string - type: 'null' title: Field description: Field that caused the error params: anyOf: - additionalProperties: true type: object - type: 'null' title: Params description: Parameters for translation interpolation required: - code - message title: ErrorDetail type: object examples: HIGH_EARNERS_UNSUPPORTED_TAX_YEAR: summary: >- Raised when the High Earners report is asked for a tax year with no statutory constants (PA/AA taper, tax bands) defined. value: errors: - code: HIGH_EARNERS_UNSUPPORTED_TAX_YEAR message: >- Raised when the High Earners report is asked for a tax year with no statutory constants (PA/AA taper, tax bands) defined. HIGH_EARNERS_INVALID_CURSOR: summary: >- Raised when the cursor passed to the High Earners list endpoint cannot be decoded or does not carry the expected sort-key fields. value: errors: - code: HIGH_EARNERS_INVALID_CURSOR message: >- Raised when the cursor passed to the High Earners list endpoint cannot be decoded or does not carry the expected sort-key fields. security: - BearerToken: [] components: schemas: HighEarnersListResponse: properties: tax_year: type: integer title: Tax Year as_of_tax_month: anyOf: - type: integer - type: 'null' title: As Of Tax Month breach_only: type: boolean title: Breach Only default: false total_flagged: type: integer title: Total Flagged items: items: $ref: '#/components/schemas/HighEarnerSummaryRow' type: array title: Items pagination: $ref: '#/components/schemas/PaginationMeta' advisory_notice: type: string title: Advisory Notice default: >- Advisory only — not an HMRC filing and not a substitute for professional tax advice. Figures are straight-line projections from payroll data for this organisation only: they exclude other employments, non-payroll income, and unused Annual Allowance carried forward from earlier years. Treat every flagged employee as worth a conversation, not as a final liability figure. additionalProperties: false type: object required: - tax_year - total_flagged - items - pagination title: HighEarnersListResponse description: |- Cursor-paginated flagged employees for a tax year (PDR-0004). The rows are derived on request rather than read from a store, so the cursor page is built in memory, over the same sort order a query would use — the inclusion filter is computed, not a column, and cannot be pushed into SQL. HighEarnerSummaryRow: properties: employee_identity: $ref: '#/components/schemas/EmployeeIdentity' gross_figures: $ref: '#/components/schemas/GrossFigures' pension_contributions: $ref: '#/components/schemas/PensionContributions' tax_position: $ref: '#/components/schemas/TaxPosition' breach_assessment: $ref: '#/components/schemas/BreachAssessment' additionalProperties: false type: object required: - employee_identity - gross_figures - pension_contributions - tax_position - breach_assessment title: HighEarnerSummaryRow description: One row of the summary sheet — 13 columns. PaginationMeta: properties: limit: type: integer title: Limit description: Items per page, as requested has_next: type: boolean title: Has Next description: A page follows; fetch it with `next_cursor` default: false has_prev: type: boolean title: Has Prev description: A page precedes; fetch it with `prev_cursor` default: false next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Pass as `cursor` to get the next page; null on the last page prev_cursor: anyOf: - type: string - type: 'null' title: Prev Cursor description: >- Pass as `prev_cursor` to get the previous page; null on the first page total: type: integer title: Total description: Number of items across all pages default: 0 additionalProperties: false type: object required: - limit title: PaginationMeta EmployeeIdentity: properties: employee_id: type: string title: Employee Id default: '' employee_number: type: string title: Employee Number default: '' full_name: type: string title: Full Name default: '' additionalProperties: false type: object title: EmployeeIdentity description: Section A — employee identity. GrossFigures: properties: monthly_gross: type: string title: Monthly Gross default: '0.00' ytd_gross: type: string title: Ytd Gross default: '0.00' annualized_gross: type: string title: Annualized Gross default: '0.00' additionalProperties: false type: object title: GrossFigures description: >- Section B — cash gross, per month / to date / projected. ``annualized_gross`` is the cash figure the inclusion filter keys off, and ``monthly_gross`` is derived from it rather than from the current period. PensionContributions: properties: monthly_pension_contribution: type: string title: Monthly Pension Contribution default: '0.00' ytd_pension_contribution: type: string title: Ytd Pension Contribution default: '0.00' annual_pension_contribution: type: string title: Annual Pension Contribution default: '0.00' additionalProperties: false type: object title: PensionContributions description: |- Section C — employee pension contributions only. Employer contributions live on the calculation detail, since they affect Adjusted Income rather than the employee's own deduction. TaxPosition: properties: adjusted_net_income: type: string title: Adjusted Net Income default: '0.00' tax_bracket: $ref: '#/components/schemas/TaxBracket' default: BASIC pa_tapered: $ref: '#/components/schemas/PATaperStatus' default: NONE additionalProperties: false type: object title: TaxPosition description: Section D — the Personal Allowance taper outcome. BreachAssessment: properties: pension_breach: type: boolean title: Pension Breach default: false cause_of_breach: type: string title: Cause Of Breach default: '' additionalProperties: false type: object title: BreachAssessment description: Section E — the Annual Allowance breach outcome. TaxBracket: type: string enum: - BASIC - HIGHER - HIGHER_60_EFFECTIVE - ADDITIONAL title: TaxBracket description: >- Where the employee's Adjusted Net Income places them (rUK bands). ``HIGHER_60_EFFECTIVE`` is the Personal Allowance taper band: the 40% higher rate still applies while the allowance is withdrawn, giving a 60% effective marginal rate. PATaperStatus: type: string enum: - NONE - PARTIAL - FULL title: PATaperStatus description: How much Personal Allowance the employee retains. securitySchemes: BearerToken: type: http scheme: bearer bearerFormat: JWT description: Get token from Auth0 and paste it here ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.