Penfold Payroll API v4

Create managed organisation

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 Payroll API v4 MCP server": {
    "url": "https://docs.getpenfold.dev/mcp"
  }
}
Close
POST /organisations
O auth2 client credentials

Partner organisations only. A Payroll organisation calling this endpoint receives 405 Method Not Allowed. An employer-scoped access token receives 403 Forbidden.

Creates a managed organisation and records your Partner organisation as its manager. Use single_employer for an organisation that is one employer, and multi_employer for one that runs payroll for several employers.

Penfold is the source of truth for managed organisations; see Managed organisations above.

application/json

Body Required

  • display_name string Required

    The name of the managed organisation, as shown to its users.

  • type string Required

    The shape of a managed organisation.

    • single_employer: the organisation is one employer.
    • multi_employer: the organisation runs payroll for several employers, for example a payroll bureau.

    Values are single_employer or multi_employer.

Responses

  • 201 application/json

    Managed organisation created

    Hide response attributes Show response attributes object
    • id string Required

      The unique identifier for the managed organisation. Store this; it is the key for every other organisation endpoint.

    • display_name string Required

      The name of the managed organisation.

    • type string Required

      The shape of a managed organisation.

      • single_employer: the organisation is one employer.
      • multi_employer: the organisation runs payroll for several employers, for example a payroll bureau.

      Values are single_employer or multi_employer.

    • created_at string(date-time) Required

      The date and time the managed organisation was created, in ISO 8601 format.
  • 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

    Hide response attribute Show response attribute object
    • error string

      A descriptive error message.
  • 403 application/json

    Forbidden, the access token is scoped to an employer.

    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.
  • 500 application/json

    Internal server error

    Hide response attribute Show response attribute object
    • error string

      A descriptive error message.
POST /organisations 
curl \
 --request POST 'https://payroll-api.getpenfold.dev/v4/organisations' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{
  "display_name": "Acme Payroll Services",
  "type": "single_employer"
}'
Request examples 
{
  "display_name": "Acme Payroll Services",
  "type": "single_employer"
}
Response examples (201) 
{
  "id": "cm1abcd2e0000xyz123456789",
  "display_name": "Acme Payroll Services",
  "type": "single_employer",
  "created_at": "2026-10-20T12:00:00.000Z"
}
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 (403) 
{
  "error": "Bad request: invalid data provided."
}
Response examples (405) 
{
  "error": "Bad request: invalid data provided."
}
Response examples (500) 
{
  "error": "Bad request: invalid data provided."
}