# List pay periods for an employer

**GET /employers/{employer_id}/pay_periods**

**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.



## Servers
- https://payroll-api.getpenfold.dev/v4: https://payroll-api.getpenfold.dev/v4 ()


## Authentication methods
- O auth2 client credentials


## Parameters

### Path parameters

- **employer_id** (string)


### Query parameters

- **page_size** (integer)
  The maximum number of pay periods to return per page.

- **page_number** (integer)
  The page number to return in the list of pay periods.

- **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).



## Responses
### 200
Paginated list of pay periods for the specified employer.

#### Body: application/json (object)
- **page_number** (integer)
  The current page number.

- **page_size** (integer)
  The number of items per page.

- **total_items** (integer)
  The total number of items available.

- **items** (array[object])
  An array of PayPeriod objects on the current page.


### 400
Bad request, the request is malformed or contains invalid data.

#### Body: application/json (object)
- **error** (string)
  A descriptive error message.


### 401
Unauthorized, the request requires authentication, and the provided credentials are either missing or incorrect.

#### Body: application/json (object)
- **error** (string)
  A descriptive error message.


### 404
Employer not found, the specified employer_id does not match any existing employer.

#### Body: application/json (object)
- **error** (string)
  A descriptive error message.


### 405
Method not allowed for this client type.

#### Body: application/json (object)
- **error** (string)
  A descriptive error message.



[Powered by Bump.sh](https://bump.sh)