Get a pay period 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/{pay_period_id}

O auth2 client credentials

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

Returns a single pay period for the employer. The response shape matches list items. Returns 404 when the pay period is missing, belongs to another employer, or has no active contributions.

Path parameters

employer_id string Required
pay_period_id string Required

Unique identifier for the pay period.

Responses

200 application/json

Pay period retrieved successfully.
Hide response attributes Show response attributes object
- 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).
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 or pay period not found. Also returned when the pay period belongs to another employer or has no active contributions.
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/{pay_period_id}

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

Response examples (200)

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