Get 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/{employerId}

Bearer auth

Returns a single employer by ID. The employer must belong to your organisation. Useful for polling onboarding status after creation.

Path parameters

employerId string(uuid) Required

Penfold employer UUID

Responses

200 application/json

Employer details
Hide response attributes Show response attributes object
- id string(uuid) Required
  
  Unique identifier for the employer
- name string Required
  
  Employer name
- externalReference string Required
  
  Penfold employer reference (PEN + Companies House number)
- companyNumber string Required
  
  Companies House number
- status string Required
  
  Current status of the employer:
  
  AwaitingAgreement: Employer must complete onboarding on Penfold's platform (agreement, AML/KYB)
  
  Pending: Onboarding complete, awaiting first payroll submission
  
  Active: Fully operational, can process payroll
  
  Closed: Employer account closed
  
  Values are AwaitingAgreement, Pending, Active, or Closed.
- defaultEmployeeContributionsPercent number Required
  
  Default employee contribution percentage
- defaultEmployerContributionsPercent number Required
  
  Default employer contribution percentage
- contributionBasis string Required
  
  Basis on which pension contributions are calculated
  
  Values are QualifyingEarnings, TotalPay, or BasicPay.
- allowsSalarySacrifice boolean Required
  
  Whether the employer allows salary sacrifice
- paymentMethod string Required
  
  Payment method for pension contributions
  
  Value is BankTransfer.
- createdAt string(date-time) Required
  
  When the employer was created (ISO 8601)
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}

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

Response examples (200)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Acme Ltd",
  "externalReference": "PEN12345678",
  "companyNumber": "12345678",
  "status": "Active",
  "defaultEmployeeContributionsPercent": 5,
  "defaultEmployerContributionsPercent": 3,
  "contributionBasis": "QualifyingEarnings",
  "allowsSalarySacrifice": false,
  "paymentMethod": "BankTransfer",
  "createdAt": "2025-01-15T10:00:00Z"
}

Response examples (401)

{
  "error": "unauthorized"
}

Response examples (404)

{
  "error": "not found"
}

Response examples (500)

{
  "error": "internal server error"
}