Penfold Partner API
GET /employers/{employerId}/employees/{employeeId}/pension-summary
Bearer auth

Returns pension summary for a specific employee.

The employer must belong to your organisation. Returns 404 only if the employee is genuinely not found. Opted-out employees return 200 with "status": "optedOut" and null data fields.

Path parameters

  • employerId string(uuid) Required

    Penfold employer UUID

  • employeeId string Required

    Unique identifier for the employee

Responses

  • 200 application/json

    Employee pension summary

    Hide response attributes Show response attributes object
    • provider string Required

      Pension provider name

      Value is Penfold.

    • status string Required
      • active: employee is enrolled, balance and contributions are populated
      • optedOut: employee opted out of the scheme, all data fields are null

      Values are active or optedOut.

    • balance object Required
      Hide balance attributes Show balance attributes object
      • currentValuePence integer Required

        Current total pot value in pence

      • totalContributionsPence integer Required

        Total contributions paid in, in pence

      • totalGainsPence integer Required

        Investment gains (or losses if negative) in pence

      • gainPercentage number(double) Required

        Gain as percentage of total contributions, rounded to 2dp

    • latestContributions object Required

      Most recent contribution breakdown. Null if opted out or no contributions yet.

      Hide latestContributions attributes Show latestContributions attributes object
      • employeePence integer Required

        Employee contribution in pence

      • employerPence integer Required

        Employer contribution in pence

      • period string Required

        Pay period (YYYY-MM)

        Format should match the following pattern: ^\d{4}-\d{2}$.

    • deepLink string(uri) | null Required

      URL for "View & manage your pension" CTA. Null if opted out.
  • 401 application/json

    Missing or invalid authentication token

    Hide response attribute Show response attribute object
    • error string Required
  • 404 application/json

    Resource not found

    Hide response attribute Show response attribute object
    • error string Required
  • 500 application/json

    Internal server error

    Hide response attribute Show response attribute object
    • error string Required
GET /employers/{employerId}/employees/{employeeId}/pension-summary 
curl \
 --request GET 'https://partner-api.getpenfold.com/v1/employers/{employerId}/employees/{employeeId}/pension-summary' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "status": "active",
  "balance": {
    "gainPercentage": 7.14,
    "totalGainsPence": 10000,
    "currentValuePence": 150000,
    "totalContributionsPence": 140000
  },
  "deepLink": "https://penfold.go.link",
  "provider": "Penfold",
  "latestContributions": {
    "period": "2024-01",
    "employeePence": 5000,
    "employerPence": 3000
  }
}
{
  "status": "optedOut",
  "balance": null,
  "deepLink": null,
  "provider": "Penfold",
  "latestContributions": null
}
Response examples (401) 
{
  "error": "unauthorized"
}
Response examples (404) 
{
  "error": "not found"
}
Response examples (500) 
{
  "error": "internal server error"
}