Preview Payroll

In this guide

How to preview upcoming payroll.
How to preview hypothetical payroll.

Preview Pending Payroll

With either the Preview Payroll by Check IDs or 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 with the companyID and desired check_date. This will return a job_id.

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

Get the results of the job

Include the job_id in a call to Get Preview.

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.

{
    "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 (similar to how data is submitted to the Create Employee Check endpoint).

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.

{
    "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. These apply only when you also supply a contribution amount.
A 32-character employee deduction template ID from 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 or Preview Payroll by Check Date endpoints.
Previewing upcoming payroll is an asynchronous process and returns a job_id.
Use the Job Queue Event webhook to receive updates on a job’s status.
Use the Get Preview to get the results of a job.
To preview hypothetical payroll use the Preview Check Data endpoint.

Getting Started

Onboard

Pay

Platform

Use Cases

In this guide

Preview Pending Payroll

Start a preview payroll job

Receive updates from the Job Queue Event

Get the results of the job

Preview Hypothetical Payroll

Preview check data

Include deductions in a hypothetical preview

Recap

​In this guide

​Preview Pending Payroll

​Start a preview payroll job

​Receive updates from the Job Queue Event

​Get the results of the job

​Preview Hypothetical Payroll

​Preview check data

​Include deductions in a hypothetical preview

​Recap

In this guide

Preview Pending Payroll

Start a preview payroll job

Receive updates from the Job Queue Event

Get the results of the job

Preview Hypothetical Payroll

Preview check data

Include deductions in a hypothetical preview

Recap