List pay periods for an employer

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 /employers/{employer_id}/pay_periods

O auth2 client credentials

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

Returns a paginated list of pay periods for the employer, newest first by pay_period_end_date. Only periods with at least one active contribution are included. Each item includes contribution totals, associated upload ids, and collection payments for the period.

Optionally filter by upload_ids to return only periods associated with at least one of the given file upload ids (OR match). Matching periods still return their full upload_ids and payments arrays.

Path parameters

employer_id string Required

Query parameters

page_size integer

The maximum number of pay periods 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 pay periods.

Minimum value is 1. Default value is 1.
upload_ids string

Optional filter. When provided, only pay periods associated with at least one of these upload ids are returned. Pass as a single comma-separated value (upload_ids=id1,id2). Do not repeat the query key. Plain commas between ids are fine; percent-encoding is not required for Penfold upload ids. Maximum 100 ids (enforced by the API). Unknown or unmatched ids simply contribute no matches (they do not cause a 404).

Minimum length is 1.

Responses

200 application/json

Paginated list of pay periods for the specified employer.
Hide response attributes Show response attributes object
- page_number integer Required
  
  The current page number.
- page_size integer Required
  
  The number of items per page.
- total_items integer Required
  
  The total number of items available.
- items array[object] Required
  
  An array of PayPeriod objects on the current page.
  
  Hide items attributes Show items attributes object
  
  An employer pay period with contribution totals, associated upload ids, and collection payments. Overall payment completion is derived by clients from payments[].status; there is no period-level payment status.
  
  id string Required
  
  Unique identifier for the pay period.
  
  pay_period_start_date string(date) Required
  
  Start date of the pay period (YYYY-MM-DD, UTC calendar date).
  
  pay_period_end_date string(date) Required
  
  End date of the pay period (YYYY-MM-DD, UTC calendar date).
  
  frequency string Required
  
  Cadence of the pay period. Unknown is returned when the stored frequency is not set.
  
  Values are Weekly, Fortnightly, FourWeekly, Monthly, or Unknown.
  
  total_contributions_pence integer Required
  
  Sum of employee and employer contribution expectation amounts in pence for active contributions in this period.
  
  employee_contributions_pence integer Required
  
  Sum of employee contribution expectation amounts in pence for active contributions in this period.
  
  employer_contributions_pence integer Required
  
  Sum of employer contribution expectation amounts in pence for active contributions in this period.
  
  upload_ids array[string] Required
  
  Distinct file upload ids associated with this pay period (via contributions and/or payments). May contain multiple ids when several uploads share the same period dates.
  
  payments array[object] Required
  
  Collection payments linked to this period. Empty when contributions exist but no Direct Debit or Bank Transfer payment has been created yet.
  
  Hide payments attributes Show payments attributes object
  
  A Direct Debit or Bank Transfer payment linked to contributions in the pay period. id is the underlying payment row id; use payment_method to disambiguate the source table.
  
  id string Required
  
  Identifier of the Direct Debit or Bank Transfer payment row.
  
  amount_pence integer Required
  
  Payment amount in pence.
  
  status string Required
  
  Collection status for a single Direct Debit or Bank Transfer payment linked to the pay period.
  
  Values are Pending, Complete, or Failed.
  
  payment_method string Required
  
  How the employer payment for this upload was collected.
  
  Values are DirectDebit or BankTransfer.
  
  upload_id string | null Required
  
  File upload id associated with this payment when known. Null when the payment row has no linked upload (for example some Direct Debit rows created from payment events).
400 application/json

Bad request, the request is malformed or contains invalid data.
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.
401 application/json

Unauthorized, the request requires authentication, and the provided credentials are either missing or incorrect.
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.
404 application/json

Employer not found, the specified employer_id does not match any existing employer.
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.
405 application/json

Method not allowed for this client type.
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.

GET /employers/{employer_id}/pay_periods

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

Response examples (200)

{
  "page_number": 1,
  "page_size": 200,
  "total_items": 1,
  "items": [
    {
      "id": "clxyz123payperiod",
      "pay_period_start_date": "2026-01-01",
      "pay_period_end_date": "2026-01-31",
      "frequency": "Monthly",
      "total_contributions_pence": 250000,
      "employee_contributions_pence": 100000,
      "employer_contributions_pence": 150000,
      "upload_ids": [
        "clxyz123upload",
        "clxyz456upload"
      ],
      "payments": [
        {
          "id": "clxyz123payment",
          "amount_pence": 150000,
          "status": "Pending",
          "payment_method": "DirectDebit",
          "upload_id": "clxyz123upload"
        }
      ]
    }
  ]
}

Response examples (400)

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

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