Retrieve an employer.

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://docs.getpenfold.dev/mcp

Standard setup for AI tools providing an mcp.json file

      
          mcp.json

"Penfold Partner API MCP server": {
  "url": "https://docs.getpenfold.dev/mcp"
}

GET /employers/{employer_id}

O auth2 client credentials

Responses

200 application/json

Employer retrieved successfully.
Hide response attributes Show response attributes object
- id string
  
  The unique identifier for the employer.
- created_at string(date-time)
  
  The date and time the employer record was created, in ISO 8601 format.
- updated_at string(date-time)
  
  The date and time the employer record was last updated, in ISO 8601 format.
- name string
  
  The name of the employer.
- contribution_basis string
  
  The basis on which the employer makes pension contributions. Informational only — Penfold does not validate submitted contribution amounts against this basis. Integrators must compute final amounts themselves. Possible values:
  
  QualifyingEarnings: contributions calculated on banded earnings (currently £6,240–£50,270).
  
  TotalPay: contributions calculated on all earnings, with no banding.
  
  BasicPay: contributions calculated on basic pay only.
  
  Values are QualifyingEarnings, TotalPay, or BasicPay.
- allows_salary_sacrifice boolean
  
  Whether the employer allows for salary sacrifice. Informational only — used to provide a tailored experience to members in the Penfold app. Penfold processes submissions as-is and makes no amendments to contribution amounts; integrators must provide final amounts regardless of salary sacrifice status.
  
  Default value is false.
- external_reference string
  
  An external reference for the employer. Should be used as the value in the EmployerId column in file uploads.
- company_number string
  
  Companies House registration number.
- payment_method string | null
  
  The payment method used by the employer.
  
  Values are BankTransfer or DirectDebit. Default value is DirectDebit.
- primary_contact_email string(email) | null
  
  The email address of the primary contact for the employer.
- primary_contact_role string | null
  
  Role of the employer primary contact.
  
  Values are CompanyDirector, Finance, or HR.
- default_employee_contributions_percent number | null
  
  Default employee contribution percentage.
  
  Minimum value is 0, maximum value is 100.
- default_employer_contributions_percent number | null
  
  Default employer contribution percentage.
  
  Minimum value is 0, maximum value is 100.
- status
  
  The status of the employer.
  
  Values are PendingPa, PaSent, Signed, PendingAml, or Active. Default value is PendingPa.
400 application/json

Bad request, the request is malformed or contains invalid data.
Hide response attributes Show response attributes object
- error string
  
  A descriptive error message.
- validation_errors array[object]
  
  Hide validation_errors attributes Show validation_errors attributes object
  
  field string Required
  
  The name of the field that failed validation.
  
  message string Required
  
  A descriptive error message.
401 application/json

Unauthorized, the request requires authentication, and the provided credentials are either missing or incorrect.
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.
404 application/json

Employer not found.
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.

GET /employers/{employer_id}

curl \
 --request GET 'https://payroll-api.getpenfold.dev/v4/employers/{employer_id}' \
 --header "Authorization: Bearer $ACCESS_TOKEN"

Response examples (200)

{
  "id": "e1234-abcd-5678-efgh",
  "created_at": "2023-03-01T12:00:00Z",
  "updated_at": "2023-03-15T12:00:00Z",
  "name": "Acme Corp.",
  "contribution_basis": "QualifyingEarnings",
  "allows_salary_sacrifice": false,
  "external_reference": "ABC123",
  "company_number": "12345678",
  "payment_method": "DirectDebit",
  "primary_contact_email": "john.doe@example.com",
  "primary_contact_role": "HR",
  "default_employee_contributions_percent": 5,
  "default_employer_contributions_percent": 3,
  "status": "Active"
}

Response examples (400)

{
  "error": "Bad request: invalid data provided.",
  "validation_errors": [
    {
      "field": "email",
      "message": "Email address is invalid."
    }
  ]
}

Response examples (401)

{
  "error": "Bad request: invalid data provided."
}

Response examples (404)

{
  "error": "Bad request: invalid data provided."
}