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"
        }
    }
}

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

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

​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

Recap