List employee documents

GET /employers/{employerId}/employees/{employeeId}/documents

Returns all documents for a specific employee, including contract notes, valuation statements, and direct debit notices.

Each document includes a downloadUrl that returns a pre-signed S3 URL valid for 5 minutes. To download the PDF, follow the URL returned by downloadUrl.

Path parameters

employerId string(uuid) Required

Penfold employer UUID
employeeId string Required

Unique identifier for the employee

Query parameters

type string

Filter documents by type.

Values are AnnualBenefitStatement, ContractNote, DirectDebitMandateConfirmation, or DirectDebitMandateNotice.
pageSize integer

The maximum number of documents to return per page.

Minimum value is 1, maximum value is 500. Default value is 200.
pageNumber integer

The page number to return.

Minimum value is 1. Default value is 1.

Responses

200 application/json

A paginated list of documents for the employee.
Hide response attributes Show response attributes object
- pageNumber integer Required
  
  The current page number.
- pageSize integer Required
  
  The number of items per page.
- totalItems integer Required
  
  The total number of items available.
- items array[object] Required
  
  An array of Document objects on the current page.
  
  Hide items attributes Show items attributes object
  
  id string Required
  
  Unique identifier for the document.
  
  type string Required
  
  The type of document:
  
  AnnualBenefitStatement: Annual benefit statement (SMPI)
  
  ContractNote: Generated when funds are bought, sold, or switched
  
  DirectDebitMandateConfirmation: Direct debit setup confirmation
  
  DirectDebitMandateNotice: Direct debit advance notice
  
  Values are AnnualBenefitStatement, ContractNote, DirectDebitMandateConfirmation, or DirectDebitMandateNotice.
  
  title string Required
  
  Human-readable document title.
  
  createdAt string(date-time) Required
  
  When the document was created (ISO 8601).
  
  downloadUrl string Required
  
  Relative URL to download the document PDF. Returns a pre-signed S3 URL valid for 5 minutes.
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}/documents

curl \
 --request GET 'https://partner-api.getpenfold.com/v1/employers/{employerId}/employees/{employeeId}/documents' \
 --header "Authorization: Bearer $ACCESS_TOKEN"

Response examples (200)

{
  "items": [
    {
      "id": "d2b3c4d5-f6a7-8901",
      "type": "AnnualBenefitStatement",
      "title": "Annual Benefit Statement - 2025",
      "createdAt": "2025-06-15T10:00:00Z",
      "downloadUrl": "/v1/employers/emp123/employees/ee456/documents/d2b3c4d5-f6a7-8901/download"
    },
    {
      "id": "d3c4d5e6-a7b8-9012",
      "type": "ContractNote",
      "title": "Contract Note - Buy PenfoldLifetime",
      "createdAt": "2025-06-20T14:30:00Z",
      "downloadUrl": "/v1/employers/emp123/employees/ee456/documents/d3c4d5e6-a7b8-9012/download"
    }
  ],
  "pageSize": 200,
  "pageNumber": 1,
  "totalItems": 3
}

Response examples (401)

{
  "error": "unauthorized"
}

Response examples (404)

{
  "error": "not found"
}

Response examples (500)

{
  "error": "internal server error"
}