List Filings

Returns Filings:

From oldest to newest by creation time, then ID.
Matching the exact payRunId filter when supplied. At most one Filing is returned.
With an empty items array when no Filing matches.

Notifications may be delayed, duplicated or arrive out of order. Retrieve the current Filing after each resource.changed notification instead of inferring its status from notification order.

OAuth scopes

payroll:read

Path Parameters

employerId
Type: string
min length:
1
max length:
200
required

PayrollKit Employer ID.

Query Parameters

cursor
Type: string
min length:
1
max length:
1000

Unchanged nextCursor value used to retrieve the next page. It is valid for 24 hours and only with the Partner, endpoint and filters that produced it. See Pagination.
limit
Type: integer
min:
1
max:
100

Number of records to return, from 1 to 100. Defaults to 50. See Pagination.
payRunId
Type: string
min length:
1
max length:
200

Exact PayrollKit Pay Run ID. At most one Filing is returned.

Headers

X-Request-Id
Type: stringFormat: uuid

Client-generated UUID for tracing. This does not make retries safe.

Responses

application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json

get/employers/{employerId}/filings

Show Schema

Filing for an approved Pay Run

{
  "items": [
    {
      "id": "filing_72ca81f0",
      "payRunId": "payrun_a3f9c217",
      "type": "fps",
      "status": "accepted",
      "reportedPaymentDate": "2026-08-31",
      "taxYear": "2026-27",
      "taxPeriod": "month_5",
      "coveredEmploymentCalculationIds": [
        "employment_calculation_3e91a7c2",
        "employment_calculation_7c24d9e1"
      ],
      "requiredAction": "none",
      "issues": [],
      "createdAt": "2026-08-27T16:10:00Z",
      "resolvedAt": "2026-08-27T16:15:00Z",
      "updatedAt": "2026-08-27T16:15:00Z"
    }
  ],
  "nextCursor": null
}

Filing page