> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Preview Payroll
> There are several key use cases for which we would want a breakdown of a payroll before it is processed.
## In this guide
* How to preview upcoming payroll.
* How to preview hypothetical payroll.
***
## Preview Pending Payroll
With either the [Preview Payroll by Check IDs](/reference/preview/preview-payroll-by-check-ids) or [Preview Payroll by Check Date](/reference/preview/preview-payroll-by-check-date), Zeal allows us to get a breakdown of upcoming payroll. For this example, we'll look at viewing upcoming payroll by check date:
### Start a preview payroll job
Call [Preview Payroll by Check Date](/reference/preview/preview-payroll-by-check-date) with the `companyID` and desired `check_date`. This will return a `job_id`.
```bash bash theme={null}
curl --request POST \
--url https://api.zeal.com/preview/checkDate \
--header 'Authorization: Bearer {{testApiKey}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"companyID": "{{companyID}}",
"check_date": "2023-01-18"
}
'
```
### Receive updates from the Job Queue Event
When the job is finished processing, Zeal will send you an update via the [Job Queue Event](/reference/webhooks/report-status-change-webhook) webhook.
### Get the results of the job
Include the `job_id` in a call to [Get Preview](/reference/preview/get-preview).
```bash bash theme={null}
curl --request GET \
--url 'https://api.zeal.com/preview?job_id={{jobID}}' \
--header 'Authorization: Bearer {{testApiKey}}' \
--header 'Accept: application/json'
```
This will return a JSON object with a `payload` field detailing the breakdown of the payroll.
```bash bash theme={null}
{
"status": 200,
"success": true,
"data": {
"job_id": "12351f1-cc224-4654-81120-39cafeacd8551",
"status": "complete",
"code": 200,
"created_at": "2022-05-04T19:29:39.134Z",
"request_body": {
"companyID": "ae12ffj4141040ac8a3cc3132a3b22l62",
"checks": [
"oq16c5ffccd740e28czz39442f315",
"22reabd897e3345a2ttyfa22b1712be52",
"1337448bd4534cc34tfd783ef1ce8391"
],
"test_mode": false
},
"payload": {
"success": true,
"result": {
"checks": [
{
"gross_pay": 20230,
"net_pay": 46544,
"employer_taxes": 8240,
"employee_taxes": 3856,
"employee_deductions": 0,
"employer_deductions": 0,
"taxes": [
{
"name": "Federal Income Tax",
"codename": "FIT",
"amount": 0
},
{
"name": "Social Security",
"codename": "FICA_SocialSecurity_EE",
"amount": 3125
},
{
"name": "Social Security",
"codename": "FICA_SocialSecurity_ER",
"amount": 3125
},
{
"name": "Medicare",
"codename": "FICA_Medicare_EE",
"amount": 731
},
{
"name": "Medicare",
"codename": "FICA_Medicare_ER",
"amount": 731
},
{
"name": "Medicare Additional",
"codename": "FICA_MedicareAdditional_EE",
"amount": 0
},
{
"name": "Federal Unemployment Tax",
"codename": "FUTA",
"amount": 302
},
{
"name": "State Unemployment Tax",
"codename": "SUTA_GA",
"amount": 4082
}
]
}
"total_employer_taxes": 8240,
"total_employee_taxes": 3856,
"total_employee_deductions": 0,
"total_employer_deductions": 0
}
}
}
}
```
## Preview Hypothetical Payroll
There are some scenarios where it's useful to preview the breakdown of an Employee Check without first submitting it to Zeal. For example, you may want to get a view of what the *net pay* would be for one specific shift in a reporting period. The Preview Check Data endpoint allows us to do just this.
### Preview check data
Submit an Employee Check Object to [Preview Check Data](/reference/preview/preview-check-data) (similar to how data is submitted to the [Create Employee Check](/reference/employee-checks/employee-checks/create-employee-check) endpoint).
```bash bash theme={null}
curl --request POST \
--url https://api.zeal.com/preview/checkData \
--header 'Authorization: Bearer {{testApiKey}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"companyID": "{{companyID}}",
"employeeID": "{{employeeID}}",
"reportingPeriodID": "{{reportingPeriodID}}",
"check_date": "2022-01-14",
"shifts": [
{
"time": "2022-01-05T17:00:00Z",
"hourly: {
"hours": 8,
"wage": 25
}
}
],
}
'
```
This will return JSON with a `payload` field detailing the breakdown of the *hypothetical* payroll.
```bash bash theme={null}
{
"success": true,
"data": {
"success": true,
"result": {
"checks": [
{
"gross_pay": "200.00",
"net_pay": "183.58",
"employer_taxes": "26.10",
"employee_taxes": "16.42",
"employee_deductions": "0.00",
"employer_deductions": "0.00",
"taxes": [
{
"name": "Federal Income Tax",
"codename": "FIT",
"amount": "0.00"
},
{
"name": "Social Security",
"codename": "FICA_SocialSecurity_EE",
"amount": "12.40"
},
{
"name": "Social Security",
"codename": "FICA_SocialSecurity_ER",
"amount": "12.40"
},
{
"name": "Medicare",
"codename": "FICA_Medicare_EE",
"amount": "2.90"
},
{
"name": "Medicare",
"codename": "FICA_Medicare_ER",
"amount": "2.90"
},
{
"name": "Medicare Additional",
"codename": "FICA_MedicareAdditional_EE",
"amount": "0.00"
},
{
"name": "Federal Unemployment Tax",
"codename": "FUTA",
"amount": "0.00"
},
{
"name": "State Unemployment Tax",
"codename": "SUTA_AK",
"amount": "10.80"
},
{
"name": "State Unemployment Tax",
"codename": "SUI_AK",
"amount": "1.12"
}
]
}
],
"total_employer_taxes": "26.10",
"total_employee_taxes": "16.42",
"total_employee_deductions": "0.00",
"total_employer_deductions": "0.00"
}
}
}
```
### Include deductions in a hypothetical preview
Preview Check Data never loads an existing Employee Check, so it does not know about deductions already saved against one. To see them in the preview, list them in the `deductions` array along with every shift you want counted — both the shifts already on the check and the ones you are proposing to add. Leaving a saved garnishment out is the most common reason a preview reports a higher net pay than the real check.
You can pass either kind of template ID:
* A 24-character check-scoped deduction template ID from [Get Deduction Template](/reference/employee-checks/deductions/get-deduction-template). These apply only when you also supply a contribution amount.
* A 32-character employee deduction template ID from [List Employee Deduction Templates](/reference/employee-deduction-templates/list-employee-deduction-templates). These apply with their own saved contribution, so `employee_contribution` and `employer_contribution` are optional overrides.
A template is left out of the preview if it is archived, if `check_date` falls outside its effective date range, or if it is a Zeal-managed garnishment. Zeal-managed garnishments are already applied to the preview automatically, so passing one would withhold it twice.
***
## Recap
* There are two ways to preview payroll with Zeal:
* Preview *upcoming* payroll - data that is in Zeal's system awaiting processing.
* Preview *hypothetical* payroll - data that is not submitted to Zeal for processing.
* To preview *upcoming* payroll use the [Preview Payroll by Check IDs](/reference/preview/preview-payroll-by-check-ids) or [Preview Payroll by Check Date](/reference/preview/preview-payroll-by-check-date) endpoints.
* Previewing *upcoming* payroll is an asynchronous process and returns a `job_id`.
* Use the [Job Queue Event](/reference/webhooks/report-status-change-webhook) webhook to receive updates on a job's status.
* Use the [Get Preview](/reference/preview/get-preview) to get the results of a job.
* To preview *hypothetical* payroll use the [Preview Check Data](/reference/preview/preview-check-data) endpoint.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.