Penfold Partner API

1.0

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.

This is version 1.0 of this API documentation. Last update on Feb 23, 2026.