Skip to navigation
API ReferenceContribution Reports

Finalize a contribution report

This endpoint finalizes the contribution report object, making it immutable and preventing any further updates. Once finalized, its status changes to finalized, and it serves as a historical record for payroll reporting. Any changes or adjustments that occur after the finalization will roll into the next reporting period.

Authentication

AuthorizationBearer
Authorization header using the Bearer scheme

Path parameters

contribution_report_idstringRequiredformat: "ctr_.+"

Headers

X-Platform-IdstringOptional

The target platform id. Required only when calling with a dashboard (WorkOS AuthKit) access token instead of a platform API key — the token carries no platform claim, so the caller must say which platform it means. Ignored for platform API key / embed session token callers.

Response

OK
idstringformat: "ctr_.+"
Unique identifier for the contribution report
employer_idstringformat: "er_.+"
Unique identifier of the employer for which the report is created
periodobject
Period covered by the contribution report
statusenum
Current status of the contribution report
Allowed values:
created_atdatetime
Date and time the report was created
last_updated_atdatetime
Date and time of the last update to the report
aggregatesobject
Summary figures for the report, meant for dashboards and overviews. They keep changing while the report is open. For payroll processing or reconciliation use the employee breakdowns, which carry the itemised contributions.
objectstringOptionalRead-only
The object type
external_customer_idstring or nullOptional

Unique identifier of the customer for which the report is created. This identifier is assigned by the Employer of Record (EoR) platform to the Customer (i.e. the company using the EoR service) for which the employee is employed. This parameter is only available to EoR platforms.

finalized_atdatetime or nullOptional
Date and time the report was finalized, if applicable
file_idstring or nullOptionalformat: "file_.+"

Identifier of the report’s downloadable CSV file. Null until the CSV has been prepared, which happens shortly after the report is finalized — use file_status to tell whether it is still on its way. Exchange it for a download link via GET /files/{file_id}/download_link.

file_statusenumOptional

Whether the report’s downloadable CSV is ready yet. pending: still being prepared. Re-fetch the report; it normally becomes available within seconds of finalization. ready: available, and file_id is set. failed: preparation did not succeed and is not retried automatically, so further polling will not help. Contact support to have it prepared again. Null while the report is open, because a CSV is only prepared once a report is finalized.

Allowed values:

Errors

400
Bad Request Error
404
Not Found Error