Set the worker's elected fund allocation

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 Partner API MCP server": {
    "url": "https://docs.getpenfold.dev/mcp"
  }
}

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

O auth2 client credentials

Set the worker's elected fund allocation. Partners 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."
    }
  ]
}