openapi: 3.2.0 info: title: check-api Report Runs API version: '2025-01-01' servers: - url: https://sandbox.checkhq.com security: - sec0: [] tags: - name: Report Runs paths: /report_runs: post: summary: Create a report run description: Creates a report run. Poll `GET /report_runs/{id}` or listen for `report_run` webhooks until `status` is `completed` or `failed`. When completed, download the file from `result.url`. Report generation may take up to 20 minutes. Data that report runs rely on may be up to 10 minutes out of date. Create requests are rate limited to 1 per second per partner, with a maximum of 20 report runs generating at once. operationId: create-a-report-run requestBody: content: application/json: schema: type: object required: - report - parameters properties: report: type: string description: Report to generate. One of `payroll_journal` or `payroll_summary`. enum: - payroll_journal - payroll_summary company: type: string description: Company ID to scope the report. parameters: type: object description: Parameters for the selected report. Required fields depend on the report type. properties: payday_from: type: string format: date description: Inclusive start of the payday range (YYYY-MM-DD). payday_to: type: string format: date description: Inclusive end of the payday range (YYYY-MM-DD). additional_columns: type: array description: Optional extra columns. Allowed values are `employee.id`, `contractor.id`, `payroll.id` (payroll journal only), or `employee.metadata.`. items: type: string payroll: type: string description: Optional payroll ID to scope the report to a single payroll. group_by: type: string description: Payroll journal only. When set to `workplace`, groups rows by workplace. enum: - workplace contractors: type: boolean description: Include contractor payments. default: false taxable_wages: type: boolean description: Include taxable wage columns. default: false gross_taxable_wages: type: boolean description: Include gross taxable wage columns. default: false metadata: type: object description: Additional loosely structured information to associate with the report run. additionalProperties: true examples: Payroll journal: value: report: payroll_journal company: com_MkBYRtUviD6kYO0b85H8 parameters: payday_from: '2025-01-01' payday_to: '2025-03-31' additional_columns: - employee.id responses: '200': description: '200' content: application/json: examples: Result: value: "{\n \"id\": \"run_w4wDuqfuSqpMrSXbERrL\",\n \"report\": \"payroll_journal\",\n \"status\": \"generating\",\n \"company\": \"com_MkBYRtUviD6kYO0b85H8\",\n \"created_at\": \"2024-11-03T19:52:15Z\",\n \"completed_at\": null,\n \"parameters\": {\n \"payday_from\": \"2025-01-01\",\n \"payday_to\": \"2025-03-31\",\n \"additional_columns\": [\n \"employee.id\"\n ],\n \"contractors\": false,\n \"taxable_wages\": false,\n \"gross_taxable_wages\": false\n },\n \"result\": null,\n \"metadata\": {}\n}" schema: type: object properties: id: type: string description: Report run ID. example: run_w4wDuqfuSqpMrSXbERrL report: type: string description: Report to generate. One of `payroll_journal` or `payroll_summary`. enum: - payroll_journal - payroll_summary example: payroll_journal status: type: string description: One of `generating`, `completed`, or `failed`. New report runs start as `generating`. enum: - generating - completed - failed example: generating company: type: string nullable: true description: Company ID to scope the report. Required for some report types. example: com_MkBYRtUviD6kYO0b85H8 created_at: type: string format: date-time description: When the report run was created. completed_at: type: string format: date-time nullable: true description: When the report run finished successfully or failed. parameters: type: object description: Parameters for the selected report. Required fields depend on the report type. properties: payday_from: type: string format: date description: Inclusive start of the payday range (YYYY-MM-DD). payday_to: type: string format: date description: Inclusive end of the payday range (YYYY-MM-DD). additional_columns: type: array description: Optional extra columns. Allowed values are `employee.id`, `contractor.id`, `payroll.id` (payroll journal only), or `employee.metadata.`. items: type: string payroll: type: string description: Optional payroll ID to scope the report to a single payroll. group_by: type: string description: Payroll journal only. When set to `workplace`, groups rows by workplace. enum: - workplace contractors: type: boolean description: Include contractor payments. default: false taxable_wages: type: boolean description: Include taxable wage columns. default: false gross_taxable_wages: type: boolean description: Include gross taxable wage columns. default: false result: type: object nullable: true description: Present when the report run has completed successfully. Use `url` to download the generated file. Download URLs are short-lived. properties: url: type: string description: URL that returns a short-lived download for the generated report file. metadata: type: object description: Additional loosely structured information associated with the report run. additionalProperties: true deprecated: false parameters: - name: X-Idempotency-Key in: header description: Optional idempotency key. Replays the first response when the same key is reused. schema: type: string tags: - Report Runs get: summary: List report runs description: Returns a list of report runs for the authenticated partner, newest first. Expired report runs are omitted. operationId: list-report-runs parameters: - name: company in: query description: Return report runs for this company ID. schema: type: string - name: report_type in: query description: Return report runs of this report type. One of `payroll_journal` or `payroll_summary`. schema: type: string enum: - payroll_journal - payroll_summary - name: status in: query description: Return report runs in this status. One of `generating`, `completed`, or `failed`. schema: type: string enum: - generating - completed - failed - name: limit in: query description: Number of report runs returned per page. The maximum value is 100. schema: type: integer format: int32 default: 25 responses: '200': description: '200' content: application/json: examples: Result: value: "{\n \"next\": null,\n \"previous\": null,\n \"results\": [\n {\n \"id\": \"run_w4wDuqfuSqpMrSXbERrL\",\n \"report\": \"payroll_journal\",\n \"status\": \"completed\",\n \"company\": \"com_MkBYRtUviD6kYO0b85H8\",\n \"created_at\": \"2024-11-03T19:52:15Z\",\n \"completed_at\": \"2024-11-03T19:55:11Z\",\n \"parameters\": {\n \"payday_from\": \"2025-01-01\",\n \"payday_to\": \"2025-03-31\",\n \"additional_columns\": [\n \"employee.id\"\n ],\n \"contractors\": false,\n \"taxable_wages\": false,\n \"gross_taxable_wages\": false\n },\n \"result\": {\n \"url\": \"https://sandbox.checkhq.com/report_runs/run_w4wDuqfuSqpMrSXbERrL/download\"\n },\n \"metadata\": {}\n },\n {\n \"id\": \"run_w4wDuqfuSqpMrSXbERrL\",\n \"report\": \"payroll_journal\",\n \"status\": \"generating\",\n \"company\": \"com_MkBYRtUviD6kYO0b85H8\",\n \"created_at\": \"2024-11-03T19:52:15Z\",\n \"completed_at\": null,\n \"parameters\": {\n \"payday_from\": \"2025-01-01\",\n \"payday_to\": \"2025-03-31\",\n \"additional_columns\": [\n \"employee.id\"\n ],\n \"contractors\": false,\n \"taxable_wages\": false,\n \"gross_taxable_wages\": false\n },\n \"result\": null,\n \"metadata\": {}\n }\n ]\n}" schema: type: object properties: next: type: string nullable: true previous: type: string nullable: true results: type: array items: type: object properties: id: type: string description: Report run ID. example: run_w4wDuqfuSqpMrSXbERrL report: type: string description: Report to generate. One of `payroll_journal` or `payroll_summary`. enum: - payroll_journal - payroll_summary example: payroll_journal status: type: string description: One of `generating`, `completed`, or `failed`. New report runs start as `generating`. enum: - generating - completed - failed example: generating company: type: string nullable: true description: Company ID to scope the report. Required for some report types. example: com_MkBYRtUviD6kYO0b85H8 created_at: type: string format: date-time description: When the report run was created. completed_at: type: string format: date-time nullable: true description: When the report run finished successfully or failed. parameters: type: object description: Parameters for the selected report. Required fields depend on the report type. properties: payday_from: type: string format: date description: Inclusive start of the payday range (YYYY-MM-DD). payday_to: type: string format: date description: Inclusive end of the payday range (YYYY-MM-DD). additional_columns: type: array description: Optional extra columns. Allowed values are `employee.id`, `contractor.id`, `payroll.id` (payroll journal only), or `employee.metadata.`. items: type: string payroll: type: string description: Optional payroll ID to scope the report to a single payroll. group_by: type: string description: Payroll journal only. When set to `workplace`, groups rows by workplace. enum: - workplace contractors: type: boolean description: Include contractor payments. default: false taxable_wages: type: boolean description: Include taxable wage columns. default: false gross_taxable_wages: type: boolean description: Include gross taxable wage columns. default: false result: type: object nullable: true description: Present when the report run has completed successfully. Use `url` to download the generated file. Download URLs are short-lived. properties: url: type: string description: URL that returns a short-lived download for the generated report file. metadata: type: object description: Additional loosely structured information associated with the report run. additionalProperties: true deprecated: false tags: - Report Runs /report_runs/{report_run}: get: summary: Get a report run description: Returns the specified report run. operationId: get-a-report-run parameters: - name: report_run in: path description: ID of the report run to return. schema: type: string required: true responses: '200': description: '200' content: application/json: examples: Result: value: "{\n \"id\": \"run_w4wDuqfuSqpMrSXbERrL\",\n \"report\": \"payroll_journal\",\n \"status\": \"completed\",\n \"company\": \"com_MkBYRtUviD6kYO0b85H8\",\n \"created_at\": \"2024-11-03T19:52:15Z\",\n \"completed_at\": \"2024-11-03T19:55:11Z\",\n \"parameters\": {\n \"payday_from\": \"2025-01-01\",\n \"payday_to\": \"2025-03-31\",\n \"additional_columns\": [\n \"employee.id\"\n ],\n \"contractors\": false,\n \"taxable_wages\": false,\n \"gross_taxable_wages\": false\n },\n \"result\": {\n \"url\": \"https://sandbox.checkhq.com/report_runs/run_w4wDuqfuSqpMrSXbERrL/download\"\n },\n \"metadata\": {}\n}" schema: type: object properties: id: type: string description: Report run ID. example: run_w4wDuqfuSqpMrSXbERrL report: type: string description: Report to generate. One of `payroll_journal` or `payroll_summary`. enum: - payroll_journal - payroll_summary example: payroll_journal status: type: string description: One of `generating`, `completed`, or `failed`. New report runs start as `generating`. enum: - generating - completed - failed example: generating company: type: string nullable: true description: Company ID to scope the report. Required for some report types. example: com_MkBYRtUviD6kYO0b85H8 created_at: type: string format: date-time description: When the report run was created. completed_at: type: string format: date-time nullable: true description: When the report run finished successfully or failed. parameters: type: object description: Parameters for the selected report. Required fields depend on the report type. properties: payday_from: type: string format: date description: Inclusive start of the payday range (YYYY-MM-DD). payday_to: type: string format: date description: Inclusive end of the payday range (YYYY-MM-DD). additional_columns: type: array description: Optional extra columns. Allowed values are `employee.id`, `contractor.id`, `payroll.id` (payroll journal only), or `employee.metadata.`. items: type: string payroll: type: string description: Optional payroll ID to scope the report to a single payroll. group_by: type: string description: Payroll journal only. When set to `workplace`, groups rows by workplace. enum: - workplace contractors: type: boolean description: Include contractor payments. default: false taxable_wages: type: boolean description: Include taxable wage columns. default: false gross_taxable_wages: type: boolean description: Include gross taxable wage columns. default: false result: type: object nullable: true description: Present when the report run has completed successfully. Use `url` to download the generated file. Download URLs are short-lived. properties: url: type: string description: URL that returns a short-lived download for the generated report file. metadata: type: object description: Additional loosely structured information associated with the report run. additionalProperties: true deprecated: false tags: - Report Runs /report_runs/{report_run}/download: get: summary: Download a report run description: Returns a short-lived download URL for the generated report artifact. The report run must be in the `completed` status and its artifact must not have expired. operationId: download-a-report-run parameters: - name: report_run in: path description: ID of the report run to download schema: type: string required: true responses: '200': description: '200' content: application/json: examples: Result: value: "{\n \"download_url\": \"https://check-reportruns.s3.amazonaws.com/ssn_report_output/2026/06/24/run_Bw6EkMDmxCPeVQ2eYzLu.zip?...\",\n \"extension\": \"zip\",\n \"content_type\": \"application/zip\"\n}" deprecated: false tags: - Report Runs components: securitySchemes: sec0: type: apiKey in: header name: Authorization x-bearer-format: bearer x-default: YOUR_API_KEY x-readme-fauxas: true x-provenance: method: searched source: https://docs.checkhq.com/reference harvested: '2026-10-14' tool: harvest-readme-openapi.py note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored. assembled_from: - https://docs.checkhq.com/reference/add-filing-blockers.md - https://docs.checkhq.com/reference/approve-a-correction.md - https://docs.checkhq.com/reference/approve-an-external-payroll.md - https://docs.checkhq.com/reference/approve-payroll.md - https://docs.checkhq.com/reference/bulk-get-employee-tax-parameter-settings.md - https://docs.checkhq.com/reference/bulk-get-employee-tax-params.md - https://docs.checkhq.com/reference/bulk-update-employee-tax-parameters.md - https://docs.checkhq.com/reference/cancel-a-payment.md - https://docs.checkhq.com/reference/company-business-details.md - https://docs.checkhq.com/reference/company-checklist-component.md - https://docs.checkhq.com/reference/company-connect-bank-account.md - https://docs.checkhq.com/reference/company-employee-setup.md - https://docs.checkhq.com/reference/company-filing-authorization.md - https://docs.checkhq.com/reference/company-pay-history.md - https://docs.checkhq.com/reference/company-payment-setup.md - https://docs.checkhq.com/reference/company-progress-tracker.md - https://docs.checkhq.com/reference/company-signatory-agreements.md - https://docs.checkhq.com/reference/company-tax-setup.md - https://docs.checkhq.com/reference/company-team-setup.md - https://docs.checkhq.com/reference/company-terms-of-service.md - https://docs.checkhq.com/reference/company-verification-documents.md - https://docs.checkhq.com/reference/contractor-roster.md - https://docs.checkhq.com/reference/create-a-bank-account.md - https://docs.checkhq.com/reference/create-a-company-provided-document.md - https://docs.checkhq.com/reference/create-a-contractor-payment.md - https://docs.checkhq.com/reference/create-a-correction.md - https://docs.checkhq.com/reference/create-a-pay-schedule.md - https://docs.checkhq.com/reference/create-a-payroll-item.md - https://docs.checkhq.com/reference/create-a-post-tax-deduction.md - https://docs.checkhq.com/reference/create-a-report-run.md - https://docs.checkhq.com/reference/create-a-workplace.md - https://docs.checkhq.com/reference/create-an-earning-code.md - https://docs.checkhq.com/reference/create-an-earning-rate.md - https://docs.checkhq.com/reference/create-an-external-payroll.md - https://docs.checkhq.com/reference/create-company-tax-elections.md - https://docs.checkhq.com/reference/create-net-pay-split.md - https://docs.checkhq.com/reference/create-payroll.md - https://docs.checkhq.com/reference/create-the-enrollment-profile.md - https://docs.checkhq.com/reference/credit-limits.md - https://docs.checkhq.com/reference/delete-a-bank-account.md - https://docs.checkhq.com/reference/delete-a-company-benefit.md - https://docs.checkhq.com/reference/delete-a-contractor-payment.md - https://docs.checkhq.com/reference/delete-a-correction.md - https://docs.checkhq.com/reference/delete-a-pay-schedule.md - https://docs.checkhq.com/reference/delete-a-payroll-copy-1.md - https://docs.checkhq.com/reference/delete-a-payroll-item-1.md - https://docs.checkhq.com/reference/delete-a-payroll-item.md - https://docs.checkhq.com/reference/delete-a-payroll.md - https://docs.checkhq.com/reference/delete-a-post-tax-deduction.md - https://docs.checkhq.com/reference/delete-a-webhook-config.md - https://docs.checkhq.com/reference/delete-an-employee-benefit.md - https://docs.checkhq.com/reference/download-a-report-run.md - https://docs.checkhq.com/reference/download-a-setup-document.md - https://docs.checkhq.com/reference/download-a-tax-package.md - https://docs.checkhq.com/reference/employee-roster.md - https://docs.checkhq.com/reference/employee-tax-setup.md - https://docs.checkhq.com/reference/employee-tax-statements-1.md - https://docs.checkhq.com/reference/employee-withholdings-setup.md - https://docs.checkhq.com/reference/filing-preview-component.md - https://docs.checkhq.com/reference/full-service-setup-submission.md - https://docs.checkhq.com/reference/generate-contractor-onboard-link.md - https://docs.checkhq.com/reference/generate-onboard-link.md - https://docs.checkhq.com/reference/get-a-communication.md - https://docs.checkhq.com/reference/get-a-company-filing.md - https://docs.checkhq.com/reference/get-a-contractor-pay-statement.md - https://docs.checkhq.com/reference/get-a-contractor-payment.md - https://docs.checkhq.com/reference/get-a-correction-receipt-download.md - https://docs.checkhq.com/reference/get-a-correction-receipt.md - https://docs.checkhq.com/reference/get-a-correction.md - https://docs.checkhq.com/reference/get-a-form.md - https://docs.checkhq.com/reference/get-a-fulfillment-receipt-2.md - https://docs.checkhq.com/reference/get-a-fulfillment.md - https://docs.checkhq.com/reference/get-a-log.md - https://docs.checkhq.com/reference/get-a-notification.md - https://docs.checkhq.com/reference/get-a-paper-check-2.md - https://docs.checkhq.com/reference/get-a-paper-check.md - https://docs.checkhq.com/reference/get-a-pay-schedule.md - https://docs.checkhq.com/reference/get-a-report-run.md - https://docs.checkhq.com/reference/get-a-setup-document.md - https://docs.checkhq.com/reference/get-a-setup.md - https://docs.checkhq.com/reference/get-a-tax-package.md - https://docs.checkhq.com/reference/get-a-tax.md - https://docs.checkhq.com/reference/get-a-webhook-delivery.md - https://docs.checkhq.com/reference/get-an-agency.md - https://docs.checkhq.com/reference/get-an-earning-code.md - https://docs.checkhq.com/reference/get-an-earning-rate.md - https://docs.checkhq.com/reference/get-an-employees-paystubs.md - https://docs.checkhq.com/reference/get-an-external-payroll.md - https://docs.checkhq.com/reference/get-an-integration-partner-copy.md - https://docs.checkhq.com/reference/get-child-support-payments-report.md - https://docs.checkhq.com/reference/get-company-paydays.md - https://docs.checkhq.com/reference/get-paper-checks-report.md - https://docs.checkhq.com/reference/get-paper-checks.md - https://docs.checkhq.com/reference/get-paydays.md - https://docs.checkhq.com/reference/get-payroll-journal.md - https://docs.checkhq.com/reference/get-payroll.md - https://docs.checkhq.com/reference/integration-partners-copy.md - https://docs.checkhq.com/reference/integration-partners.md - https://docs.checkhq.com/reference/list-a-webhook-config.md - https://docs.checkhq.com/reference/list-active-funding-strikes.md - https://docs.checkhq.com/reference/list-agencies.md - https://docs.checkhq.com/reference/list-bank-accounts.md - https://docs.checkhq.com/reference/list-benefits.md - https://docs.checkhq.com/reference/list-communications.md - https://docs.checkhq.com/reference/list-companies.md - https://docs.checkhq.com/reference/list-company-authorization-documents.md - https://docs.checkhq.com/reference/list-company-benefits.md - https://docs.checkhq.com/reference/list-company-filings.md - https://docs.checkhq.com/reference/list-company-tax-documents.md - https://docs.checkhq.com/reference/list-company-tax-elections.md - https://docs.checkhq.com/reference/list-company-tax-parameter-settings.md - https://docs.checkhq.com/reference/list-company-tax-parameters.md - https://docs.checkhq.com/reference/list-contractor-forms.md - https://docs.checkhq.com/reference/list-contractor-payments.md - https://docs.checkhq.com/reference/list-contractor-tax-documents.md - https://docs.checkhq.com/reference/list-contractors.md - https://docs.checkhq.com/reference/list-corrections.md - https://docs.checkhq.com/reference/list-earning-codes.md - https://docs.checkhq.com/reference/list-earning-rates.md - https://docs.checkhq.com/reference/list-employee-tax-documents.md - https://docs.checkhq.com/reference/list-employee-tax-elections.md - https://docs.checkhq.com/reference/list-employee-tax-parameter-settings.md - https://docs.checkhq.com/reference/list-employee-tax-statements.md - https://docs.checkhq.com/reference/list-employees-tax-parameters.md - https://docs.checkhq.com/reference/list-employees.md - https://docs.checkhq.com/reference/list-external-payrolls.md - https://docs.checkhq.com/reference/list-forms.md - https://docs.checkhq.com/reference/list-fulfillments.md - https://docs.checkhq.com/reference/list-integration-accesses-1.md - https://docs.checkhq.com/reference/list-integration-permissions-copy.md - https://docs.checkhq.com/reference/list-integration-permissions.md - https://docs.checkhq.com/reference/list-logs.md - https://docs.checkhq.com/reference/list-net-pay-splits.md - https://docs.checkhq.com/reference/list-notifications.md - https://docs.checkhq.com/reference/list-pay-schedules.md - https://docs.checkhq.com/reference/list-payments.md - https://docs.checkhq.com/reference/list-payroll-items.md - https://docs.checkhq.com/reference/list-payrolls.md - https://docs.checkhq.com/reference/list-post-tax-deductions.md - https://docs.checkhq.com/reference/list-report-runs.md - https://docs.checkhq.com/reference/list-setup-documents.md - https://docs.checkhq.com/reference/list-setups.md - https://docs.checkhq.com/reference/list-tax-deposits.md - https://docs.checkhq.com/reference/list-taxes.md - https://docs.checkhq.com/reference/list-usage-records.md - https://docs.checkhq.com/reference/list-usage-summaries.md - https://docs.checkhq.com/reference/list-webhook-deliveries.md - https://docs.checkhq.com/reference/list-workplaces.md - https://docs.checkhq.com/reference/preview-a-correction.md - https://docs.checkhq.com/reference/preview-an-external-payroll.md - https://docs.checkhq.com/reference/preview-payroll.md - https://docs.checkhq.com/reference/previous-payroll-provider-access.md - https://docs.checkhq.com/reference/refund-a-payment.md - https://docs.checkhq.com/reference/remove-filing-blockers.md - https://docs.checkhq.com/reference/reopen-a-correction.md - https://docs.checkhq.com/reference/reopen-a-pending-payroll.md - https://docs.checkhq.com/reference/reopen-payroll.md - https://docs.checkhq.com/reference/request-a-tax-package.md - https://docs.checkhq.com/reference/request-embedded-setup.md - https://docs.checkhq.com/reference/retry-a-payment.md - https://docs.checkhq.com/reference/retry-a-webhook-delivery-in-sandbox.md - https://docs.checkhq.com/reference/reveal-account-number.md - https://docs.checkhq.com/reference/reveal-contractor-ssn.md - https://docs.checkhq.com/reference/reveal-employee-ssn.md - https://docs.checkhq.com/reference/run-payroll.md - https://docs.checkhq.com/reference/sandbox-complete-disbursements.md - https://docs.checkhq.com/reference/sandbox-complete-funding.md - https://docs.checkhq.com/reference/sandbox-correction-complete-funding.md - https://docs.checkhq.com/reference/sandbox-correction-fail-funding.md - https://docs.checkhq.com/reference/sandbox-correction-start-processing.md - https://docs.checkhq.com/reference/sandbox-fail-funding.md - https://docs.checkhq.com/reference/sandbox-start-processing.md - https://docs.checkhq.com/reference/submit-a-contractor-form.md - https://docs.checkhq.com/reference/update-a-bank-account.md - https://docs.checkhq.com/reference/update-a-company.md - https://docs.checkhq.com/reference/update-a-correction.md - https://docs.checkhq.com/reference/update-a-webhook-config.md - https://docs.checkhq.com/reference/update-a-workplace.md - https://docs.checkhq.com/reference/update-an-earning-rate.md - https://docs.checkhq.com/reference/update-an-external-payroll.md - https://docs.checkhq.com/reference/update-company-tax-elections.md - https://docs.checkhq.com/reference/update-employee-tax-elections.md - https://docs.checkhq.com/reference/update-payroll.md - https://docs.checkhq.com/reference/update-the-enrollment-profile.md - https://docs.checkhq.com/reference/validate-address.md - https://docs.checkhq.com/reference/validate-an-external-payroll.md - https://docs.checkhq.com/reference/void-a-payroll.md - https://docs.checkhq.com/reference/workplace-roster.md merge: pages: 188 deduped: 195 conflicts_kept_first: 0