Retrieve a list of contributions for a specified 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}/contributions

O auth2 client credentials

Retrieve a list of contributions for a specified employer.

Optionally filter by pay_period_ids to return only the contributions belonging to one or more pay periods (OR match). This is the recommended way to reconcile a period: read the period ids from GET /employers/{employer_id}/pay_periods, then request just those periods' contributions rather than paging the employer's full history.

Contributions are returned for the employer that ran the pay period they belong to. Employees who have since left are therefore still included, so a historic period reconciles to the same totals after a leaver has gone.

Path parameters

employer_id string Required

Query parameters

page_size integer

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

Minimum value is 1. Default value is 1.
pay_period_ids string

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

Minimum length is 1.
sort_by string

Sort Contributions by date

Values are pay_period_start_date, pay_period_end_date, or created_at. Default value is created_at.
sort_order string

Sort order (ascending or descending). Case-insensitive; asc and desc are accepted.

Default value is desc.

Responses

200 application/json

A paginated list of contributions 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 Contribution objects on the current page.
  
  Hide items attributes Show items attributes object
  
  id string Required
  
  Unique identifier for the contribution record.
  
  upload_id string
  
  ID of the file upload from which the contribution was created. Omitted for contributions that were not created from an upload.
  
  pay_period_id string Required
  
  ID of the pay period this contribution belongs to. Use this to join contributions back to GET /employers/{employer_id}/pay_periods without matching on the period start and end dates.
  
  employee_id string Required
  
  Identifier for the employee associated with the contribution.
  
  employer_contributions_amount number Required
  
  The amount of the employer's contribution for the given pay period.
  
  employee_contributions_amount number Required
  
  The amount of the employee's contribution for the given pay period.
  
  employer_contributions_percent number | null Required
  
  The employer's contribution for the given pay period expressed as a percentage.
  
  Minimum value is 0, maximum value is 100.
  
  employee_contributions_percent number | null Required
  
  The employee's contribution for the given pay period expressed as a percentage.
  
  Minimum value is 0, maximum value is 100.
  
  created_at string(date-time) Required
  
  The date and time the contribution record was created, in ISO 8601 format.
  
  pay_period_start_date string(date) Required
  
  The start date of the pay period for which the contributions were made, in YYYY-MM-DD format.
  
  pay_period_end_date string(date) Required
  
  The end date of the pay period for which the contributions were made, in YYYY-MM-DD format.
  
  status string Required
  
  The status of the contribution. Note this does not represent the status of processing but rather the underlying payment. Possible values are: - Cancelled: The contribution has been cancelled. - NotSubmitted: The contribution has not been submitted. - Deleted: The contribution has been deleted. - Pending: The contribution is currently being processed. - Completed: The contribution has been successfully processed.
  
  Values are Cancelled, NotSubmitted, Deleted, Pending, or Completed.
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.

GET /employers/{employer_id}/contributions

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

Response examples (200)

{
  "page_number": 1,
  "page_size": 200,
  "total_items": 1,
  "items": [
    {
      "id": "c1234-abcd-5678-efgh",
      "upload_id": "string",
      "pay_period_id": "clxyz123payperiod",
      "employee_id": "e9876-wxyz-4321-stuv",
      "employer_contributions_amount": 1000.0,
      "employee_contributions_amount": 250.0,
      "employer_contributions_percent": 10,
      "employee_contributions_percent": 20,
      "created_at": "2023-03-22T12:00:00Z",
      "pay_period_start_date": "2023-03-01",
      "pay_period_end_date": "2023-03-15",
      "status": "Pending"
    }
  ]
}

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