List managed organisations

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

GET /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.

Returns the managed organisations your Partner organisation has created, newest first.

Query parameters

page_size integer

The maximum number of managed organisations to return per page.

Minimum value is 1, maximum value is 500. Default value is 200.
page_number integer

The page number to return in the list of managed organisations.

Minimum value is 1. Default value is 1.

Responses

200 application/json

List of managed organisations retrieved successfully.
Hide response attributes Show response attributes object
- page_number integer Required
  
  The current page number.
- page_size integer Required
  
  The number of managed organisations per page.
- total_items integer Required
  
  The total number of managed organisations available.
- items array[object] Required
  
  An array of managed organisation objects on the current page.
  
  Hide items attributes Show items attributes object
  
  An organisation you have created on Penfold via the API.
  
  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, page_size or page_number is out of range.
Hide response attribute Show response attribute object
- error string
  
  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.

GET /organisations

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

Response examples (200)

{
  "page_number": 1,
  "page_size": 200,
  "total_items": 10,
  "items": [
    {
      "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."
}

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