**Partner organisations only

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

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

PUT /employers/{employer_id}/employees/{employee_id}/fund_allocation

O auth2 client credentials

Partner organisations only. A Payroll organisation calling this endpoint receives 405 Method Not Allowed.

Set the worker's elected fund allocation. Choose a target from GET /fund_allocations; this endpoint applies it immediately and returns the new state. Lifetime fund strategies are not supported — only concrete catalogue allocations.

Idempotent: requesting the worker's current fund_allocation_id returns 200 with the current allocation and does not re-apply fund-change side effects.

When the allocation actually changes, emits a FundAllocation webhook with action Changed. Idempotent no-ops do not emit a webhook.

Path parameters

employer_id string Required
employee_id string Required

application/json

Body Required

fund_allocation_id string Required

Penfold fund allocation id to elect for the worker.

Responses

200 application/json

Fund allocation updated successfully (or unchanged when idempotent).
Hide response attributes Show response attributes object
- id string Required
  
  Penfold fund allocation id.
- name string Required
  
  Display name (e.g. "Penfold Growth", "Penfold Balance").
- description string | null
- provider string | null
  
  Fund manager or provider label.
- risk_level integer | null
  
  Standardised risk scale (TBD).
- effective_annual_fee_percent number Required
  
  Combined effective annual fee percentage (Penfold administration fee plus fund manager charge), weighted by the worker's current pot value and applicable fee tier thresholds.
- asset_allocation array[object] | null
  
  Hide asset_allocation attributes Show asset_allocation attributes object
  
  asset_class string Required
  
  percent number Required
  
  Minimum value is 0, maximum value is 100.
- asset_allocation_as_of_date string(date) | null
  
  Date the asset allocation breakdown was last updated.
400 application/json

Request body validation failed (e.g. missing fund_allocation_id).
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.
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.
404 application/json

Employee or employer not found, or fund allocation is not available for the employee.
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.
405 application/json

Method not allowed
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.
422 application/json

fund_allocation_id is unknown or not in the workplace catalogue (GET /fund_allocations).
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.

PUT /employers/{employer_id}/employees/{employee_id}/fund_allocation

curl \
 --request PUT 'https://payroll-api.getpenfold.dev/v4/employers/{employer_id}/employees/{employee_id}/fund_allocation' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{
  "fund_allocation_id": "string"
}'

Request examples

{
  "fund_allocation_id": "string"
}

Response examples (200)

{
  "id": "string",
  "name": "string",
  "description": "string",
  "provider": "string",
  "risk_level": 42,
  "effective_annual_fee_percent": 42.0,
  "asset_allocation": [
    {
      "asset_class": "string",
      "percent": 42.0
    }
  ],
  "asset_allocation_as_of_date": "2026-05-04"
}

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."
}

Response examples (405)

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

Response examples (422)

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