# Penfold Partner API

## Description
This is version `1.0` of this API documentation. Last update on Feb 23, 2026.
Unified API for payroll partners to onboard employers, manage employees,
contributions, and file uploads.

## Authentication

OAuth2 client credentials via AWS Cognito.

1. POST to the Cognito token endpoint with `grant_type=client_credentials`
   and scope `penfold-partner-api/read`.
2. Include the access token as a Bearer token in the Authorization header.

The token's `client_id` is mapped to your organisation, which scopes all
requests to your employers only.

## Identifier conventions

- **Employer ID** (`id`): UUID assigned by Penfold when the employer is
  created. Used as the `{employerId}` path parameter.
- **External reference** (`externalReference`): The Penfold employer
  reference (e.g. `PEN12345678`). This is `PEN` + the Companies House
  number. Returned alongside `id` in employer responses for cross-referencing.
- **Employee ID**: Unique identifier assigned by Penfold when the employee
  is enrolled.


## Servers
- Production: https://partner-api.getpenfold.com/v1 (Production)
- Staging: https://partner-api.getpenfold.dev/v1 (Staging)

## Authentication




## Endpoints and operations

### [Health](https://docs.getpenfold.dev/group/endpoint-health.md)
- [Health check](https://docs.getpenfold.dev/operation/operation-gethealth.md)
### [Employers](https://docs.getpenfold.dev/group/endpoint-employers.md)
- [List employers](https://docs.getpenfold.dev/operation/operation-getemployers.md)
- [Create employer](https://docs.getpenfold.dev/operation/operation-createemployer.md)
- [Update employer](https://docs.getpenfold.dev/operation/operation-updateemployer.md)
### [Payments](https://docs.getpenfold.dev/group/endpoint-payments.md)
- [List payments](https://docs.getpenfold.dev/operation/operation-getemployerpayments.md)
### [Employees](https://docs.getpenfold.dev/group/endpoint-employees.md)
- [List employees](https://docs.getpenfold.dev/operation/operation-getemployees.md)
- [Create employees](https://docs.getpenfold.dev/operation/operation-createemployees.md)
- [Update employee](https://docs.getpenfold.dev/operation/operation-updateemployee.md)
- [Get employee pension summary](https://docs.getpenfold.dev/operation/operation-getemployeepensionsummary.md)
### [Documents](https://docs.getpenfold.dev/group/endpoint-documents.md)
- [List employee documents](https://docs.getpenfold.dev/operation/operation-getemployeedocuments.md)
- [Download document](https://docs.getpenfold.dev/operation/operation-downloademployeedocument.md)
### [Transfers](https://docs.getpenfold.dev/group/endpoint-transfers.md)
- [List pension transfers](https://docs.getpenfold.dev/operation/operation-getemployeetransfers.md)
- [Initiate pension transfer](https://docs.getpenfold.dev/operation/operation-initiatetransfer.md)
### [Payroll Contributions](https://docs.getpenfold.dev/group/endpoint-payroll-contributions.md)
- [List employee contributions](https://docs.getpenfold.dev/operation/operation-getemployeecontributions.md)
- [List employer contributions](https://docs.getpenfold.dev/operation/operation-getemployercontributions.md)
- [Create contributions](https://docs.getpenfold.dev/operation/operation-createcontributions.md)
### [Payroll Uploads](https://docs.getpenfold.dev/group/endpoint-payroll-uploads.md)
- [List uploads](https://docs.getpenfold.dev/operation/operation-getuploads.md)
- [Initiate file upload](https://docs.getpenfold.dev/operation/operation-initiateupload.md)
- [Get upload status](https://docs.getpenfold.dev/operation/operation-getupload.md)
- [Get upload errors](https://docs.getpenfold.dev/operation/operation-getuploaderrors.md)
- [Get upload contributions](https://docs.getpenfold.dev/operation/operation-getuploadcontributions.md)
- [Get upload enrolments](https://docs.getpenfold.dev/operation/operation-getuploadenrolments.md)



[Powered by Bump.sh](https://bump.sh)