Retrieve a 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

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

GET /organisations/{organisation_id}

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 a managed organisation your Partner organisation has created. Returns 404 Not Found when the organisation does not exist or is not managed by your Partner organisation.

Path parameters

organisation_id string Required

Unique identifier for the managed organisation.

Responses

200 application/json

Managed organisation retrieved successfully.
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.
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.
404 application/json

Organisation not found, or not managed by your Partner organisation.
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/{organisation_id}

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

Response examples (200)

{
  "id": "cm1abcd2e0000xyz123456789",
  "display_name": "Acme Payroll Services",
  "type": "single_employer",
  "created_at": "2026-10-20T12:00:00.000Z"
}

Response examples (401)

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

Response examples (403)

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

Response examples (404)

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

Response examples (405)

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