Quickstart Guide

Contact Zeal to create a Partner account and obtain an API Key.

Overview

In this quickstart, we will look at creating a gross to net calculation for an employee whose gross regular wage is $1000, and who lives in California. They have a 401k plan with their employer, where their employer contributes $100.

The following steps will be followed.

  1. Get Pay Types
  2. Get Tax Types
  3. Get Deduction Types
  4. Get Employee Tax Parameter Summary
  5. Calculate Taxes

Get Pay Types

First, we get the Pay Types that are supported by Zeal.

curl --request GET \
     --url https://api.joinpuzzl.com/abacus/getPayTypes \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer 1812kjasjkbasjkg' \
     --header 'Content-Type: application/json'

The response will look like this, from which we will use REG (Regular pay) for the rest of the guide

{
    "success": true,
    "data": [
        {
            "isImputed": false,
            "isSupplemental": false,
            "_id": "03dfffcd-f408-4956-a0b5-40384380508d",
            "__v": 0,
            "codename": "REG",
            "name": "Regular Pay"
        },
        {
            "isImputed": false,
            "isSupplemental": true,
            "_id": "0359cf92-cf37-467c-8fe6-2fc18bc76790",
            "__v": 0,
            "codename": "COMMISSION",
            "name": "Commission"
        },
        {
            "isImputed": false,
            "isSupplemental": true,
            "_id": "55f97fc8-c2bb-4e96-90d8-d9cb136da571",
            "__v": 0,
            "codename": "BONUS",
            "name": "Bonus"
        },
        {
            "isImputed": false,
            "isSupplemental": true,
            "_id": "1645b05f-cd35-4b98-8c08-8ff3a122ce2a",
            "__v": 0,
            "codename": "TIPS",
            "name": "Tips"
        },
        {
            "isImputed": true,
            "isSupplemental": false,
            "_id": "4ec684c6-ce0b-4024-8b60-c0281de661e4",
            "__v": 0,
            "codename": "GTL_WHFIT",
            "name": "GTL W/H FIT"
        },
        {
            "isImputed": true,
            "isSupplemental": false,
            "_id": "7aa6b790-9143-48d7-b0e0-723b1fe5697b",
            "__v": 0,
            "codename": "GTL_NOWHFIT",
            "name": "GTL"
        }
    ]
}

Get Tax Types

Secondly, we use the API to get the different tax types that will apply to this employee

curl --request GET \
     --url https://api.joinpuzzl.com/abacus/getTaxTypes \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer 1812kjasjkbasjkg' \
     --header 'Content-Type: application/json' \
     --data '
{
     "jurisdictions": [
          "US",
          "CA"
     ]
}
'

The response returns the entire list of taxes that can be applied to a check

[
    {
        "_id": "602c1300dcba4d66b786d673",
        "id": "a6c73644-fba5-4dd2-b114-bd9dc68371d5",
        "__v": 0,
        "codename": "SIT_CA",
        "jurisdiction": "CA",
        "name": "State Income Tax",
        "payer": "EE"
    },
    {
        "_id": "602c1300dcba4d66b786d6b4",
        "id": "2e977a28-4dbe-41bb-92d0-e520baaface4",
        "__v": 0,
        "codename": "SUTA_CA",
        "jurisdiction": "CA",
        "name": "State Unemployment Tax",
        "payer": "ER"
    },
    {
        "_id": "602c1300dcba4d66b786d6c3",
        "id": "a759cfdd-5054-4d0d-a5ad-0a05de90023c",
        "__v": 0,
        "codename": "SDI_CA_EE",
        "jurisdiction": "CA",
        "name": "California Temporary Disability Insurance Tax",
        "payer": "EE"
    },
    {
        "_id": "602c1300dcba4d66b786d6d8",
        "id": "7687a886-6b11-4759-97f9-3df3f827e9cd",
        "__v": 0,
        "codename": "FEE_CA_SACRAMENTO",
        "jurisdiction": "CA",
        "name": "Sacramento Business Operations Tax",
        "payer": "ER"
    },
    {
        "_id": "602c1300dcba4d66b786d6da",
        "id": "e384de87-6bed-480d-9923-af33b4bfa607",
        "__v": 0,
        "codename": "SDI_CA_ER",
        "jurisdiction": "CA",
        "name": "California Temporary Disability Voluntary Plan Assesesement",
        "payer": "ER"
    },
    {
        "_id": "602c1300dcba4d66b786d6ea",
        "id": "0236ba4d-ad28-4ee3-8957-31fe0b6e28d0",
        "__v": 0,
        "codename": "FEE_CA_SANFRANCISCO",
        "jurisdiction": "CA",
        "name": "San Francisco Payroll Expense Tax",
        "payer": "ER"
    },
    {
        "_id": "602c1300dcba4d66b786d5ff",
        "id": "823a7d58-9ff5-4c63-9c5c-3fefeb9fcca5",
        "__v": 0,
        "codename": "FIT",
        "jurisdiction": "US",
        "name": "Federal Income Tax",
        "payer": "EE"
    },
    {
        "_id": "602c1300dcba4d66b786d606",
        "id": "d8f52736-72d1-4861-83d5-7fe2f4323515",
        "__v": 0,
        "codename": "FUTA",
        "jurisdiction": "US",
        "name": "Federal Unemployment Tax",
        "payer": "ER"
    },
    {
        "_id": "602c1300dcba4d66b786d620",
        "id": "41756b81-0abc-4f33-b845-75f75b6d12a1",
        "__v": 0,
        "codename": "FICA_SocialSecurity_EE",
        "jurisdiction": "US",
        "name": "Social Security",
        "payer": "EE"
    },
    {
        "_id": "602c1300dcba4d66b786d635",
        "id": "d7390a40-9443-4e7f-8da8-8dcfce2c94c0",
        "__v": 0,
        "codename": "FICA_SocialSecurity_ER",
        "jurisdiction": "US",
        "name": "Social Security",
        "payer": "ER"
    },
    {
        "_id": "602c1300dcba4d66b786d64d",
        "id": "4615b027-8ce8-4972-a2de-950880da9256",
        "__v": 0,
        "codename": "FICA_Medicare_EE",
        "jurisdiction": "US",
        "name": "Medicare",
        "payer": "EE"
    },
    {
        "_id": "602c1300dcba4d66b786d648",
        "id": "edf8546a-0890-4faf-a512-fdffa4621d29",
        "__v": 0,
        "codename": "FICA_MedicareAdditional_EE",
        "jurisdiction": "US",
        "name": "Medicare Additional",
        "payer": "EE"
    },
    {
        "_id": "602c1300dcba4d66b786d64e",
        "id": "6295a95e-4336-40a3-a5cd-3e2037ef6c5b",
        "__v": 0,
        "codename": "FICA_Medicare_ER",
        "jurisdiction": "US",
        "name": "Medicare",
        "payer": "ER"
    }
]

Get Deduction Types

Next, we get the type of Deduction that we need. As mentioned, this employee gets $100 added to their 401k from their employer. We make an API request to fetch the list of deduction types supported by Zeal, to get the code for 401k.

curl --request GET \
     --url https://api.joinpuzzl.com/abacus/getDeductionTypes \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer 1812kjasjkbasjkg'

From the response, we know that we will need the codename, "Traditional_401K"

{
  "success": true,
  "data": [
    {
      "_id": "de4d1c10-ae67-4759-9872-0591f4b68a3d",
      "__v": 0,
      "codename": "TRADITIONAL_401K",
      "name": "Traditional 401(k)"
    },
    {
      "_id": "83fd004f-b36f-41fb-8dc9-8d50a33ed44e",
      "__v": 0,
      "codename": "SECTION_125",
      "name": "Section 125"
    },
    {
      "_id": "e3c87aaf-0fb5-4011-90cb-c935e369ed4e",
      "__v": 0,
      "codename": "HSA",
      "name": "Health Savings Account (HSA)"
    }
  ]
}

Get Employee Tax Parameter Summary

Next, we need to get the tax parameters that apply to the employee we are creating the check for. For this request, we will need the Zeal created companyID and employeeID.

curl --request POST \
     --url https://api.joinpuzzl.com/employees/getTaxParameterSummary \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer 92e4043469d84c488cce8a050361cff2' \
     --header 'Content-Type: application/json' \
     --data '
{
     "jurisdictions": [
          "US",
          "CA"
     ],
     "employeeID": "6160dea81505530022bb9a72",
     "companyID": "ad2123asdaseseas"
}
'

In the response, we get the federal (jurisdiction "US") and the state (jurisdiction "CA"). Use the isUserProvidedValue or the isDefaultValue flag to filter. ie get all the non default value params or get all the user provided value params. These will be passed in the final step.

{
    "success": true,
    "data": [
        {
            "employeeID": "6160dea81505530022bb9a72",
            "effectiveDate": "2022-02-05T00:00:00.000Z",
            "jurisdiction": "US",
            "params": [
                {
                    "code": "FILINGSTATUS",
                    "type": "options",
                    "value": "M",
                    "valueDescription": "Married filing jointly",
                    "label": "Filing Status",
                    "isDefaultValue": false,
                    "isUserProvidedValue": true
                },
                {
                    "code": "IS_NON_RESIDENT_ALIEN",
                    "type": "boolean",
                    "value": "false",
                    "label": "IS_NON_RESIDENT_ALIEN",
                    "isDefaultValue": true,
                    "isUserProvidedValue": false
                },
                {
                    "code": "TWO_JOBS",
                    "type": "boolean",
                    "value": "true",
                    "label": "TWO_JOBS",
                    "isDefaultValue": false,
                    "isUserProvidedValue": true
                },
                {
                    "code": "DEPENDENTS_AMOUNT",
                    "type": "dollars",
                    "value": "0",
                    "label": "DEPENDENTS_AMOUNT",
                    "isDefaultValue": true,
                    "isUserProvidedValue": false
                },
                {
                    "code": "OTHER_INCOME",
                    "type": "dollars",
                    "value": "0",
                    "label": "OTHER_INCOME",
                    "isDefaultValue": true,
                    "isUserProvidedValue": false
                },
                {
                    "code": "EXTRA_WH",
                    "type": "dollars",
                    "value": "0",
                    "label": "EXTRA_WH",
                    "isDefaultValue": true,
                    "isUserProvidedValue": false
                },
                {
                    "code": "DEDUCTIONS",
                    "type": "dollars",
                    "value": "0",
                    "label": "DEDUCTIONS",
                    "isDefaultValue": true,
                    "isUserProvidedValue": false
                },
                {
                    "code": "EXEMPT",
                    "type": "boolean",
                    "value": "false",
                    "label": "Exempt from withholding",
                    "isDefaultValue": true,
                    "isUserProvidedValue": false
                },
                {
                    "code": "SUBJECT",
                    "type": "boolean",
                    "value": "true",
                    "label": "Subject to tax",
                    "isDefaultValue": true,
                    "isUserProvidedValue": false
                }
            ]
        },
        {
            "employeeID": "6160dea81505530022bb9a72",
            "effectiveDate": "2022-02-05T00:00:00.000Z",
            "jurisdiction": "CA",
            "params": [
                {
                    "code": "FILINGSTATUS",
                    "type": "options",
                    "value": "SM2",
                    "valueDescription": "SINGLE or MARRIED (with two or more incomes)",
                    "label": "Filing Status",
                    "isDefaultValue": true,
                    "isUserProvidedValue": true
                },
                {
                    "code": "REGULAR_ALLOWANCES",
                    "type": "integer",
                    "value": "0",
                    "label": "Regular Withholding Allowances",
                    "isDefaultValue": true,
                    "isUserProvidedValue": false
                },
                {
                    "code": "ADDITIONAL_ALLOWANCES",
                    "type": "integer",
                    "value": "0",
                    "label": "Additional Withholding Allowances",
                    "isDefaultValue": true,
                    "isUserProvidedValue": false
                },
                {
                    "code": "ADDITIONAL_WH",
                    "type": "dollars",
                    "value": "0",
                    "label": "Additional Withholding",
                    "isDefaultValue": true,
                    "isUserProvidedValue": false
                },
                {
                    "code": "EXEMPT",
                    "type": "boolean",
                    "value": "false",
                    "label": "Exempt from withholding",
                    "isDefaultValue": true,
                    "isUserProvidedValue": false
                },
                {
                    "code": "SUBJECT",
                    "type": "boolean",
                    "value": "true",
                    "label": "Subject to tax",
                    "isDefaultValue": true,
                    "isUserProvidedValue": false
                }
            ]
        }
    ]
}

Get Company Tax Parameter Summary

The next step would be to gather the company tax parameters that we would use when calculating taxes. The request only requires an effectiveDate body parameter that fetches all Company Tax Parameters by the effective date or defaults to today's current date if left blank.

curl --request GET \
     --url https://api.joinpuzzl.com/abacus/getCompanyTaxParameterDefinitions \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {API KEY}
     --data '
{
     "effectiveDate": "20-04-2022"
}
'

The response will be an array of Company Tax Parameters that we would then use in the companyConfig field when utilizing the final Calculate Taxes request
This is what the response would look like:

{
  "success": true,
  "data": {
      "generalParameters": [],
    "jurisdictionParameters": {
      "US": [
        {
          "type": "string",
          "code": "WITHHOLDING_TAX_ACCOUNT_NUMBER",
          "label": "Federal Employer Identifcation Number (EIN)",
          "scope": "FIT",
          "additional_scope": [
            "FUTA"
          ],
          "constraints": [
            {
              "effectiveDate": 2020,
              "maxLength": 10,
              "pattern": "^\\d{2}-\\d{7}$"
            }
          ],
          "effectiveDate": 2020,
          "internalOnly": false,
          "defaults": [
            {
              "effectiveDate": 2020,
              "value": "XX-XXXXXXX"
            }
          ]
        }
      ],
      "AL": [
        {
          "type": "string",
          "code": "WITHHOLDING_TAX_ACCOUNT_NUMBER",
          "label": "Withholding Tax Account Number",
          "scope": "SIT_AL",
          "constraints": [
            {
              "effectiveDate": 2020,
              "maxLength": 10,
              "pattern": "^(R\\d{9})|(\\d{10})$"
            }
          ],
          "effectiveDate": 2020,
          "internalOnly": false,
          "defaults": [
            {
              "effectiveDate": 2020,
              "value": "R999999999"
            }
          ]
        },
       },
     }

Calculate Taxes

In the final step, we will combine the outputs from all the preceding steps to calculate the gross to net for this employee. Just to refresh, our employee is getting paid $1000 gross, they live in California, and their employer contributes $100 to their 401. This is what the request will look like.

curl --request POST \
     --url https://api.joinpuzzl.com/abacus/calcTax \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {API KEY}' \
     --header 'Content-Type: application/json' \
     --data '
{
    "wages": [
        {
            "payType": "REG",
            "amount": 1000,
            "location": {
                "street1": "1 Ferry Building",
                "street2": "",
                "city": "San Francisco",
                "state": "CA",
                "zip": "94111"
            }
        }
    ],
    "deductions": [{"codename": "401K", "payer": "ER", "amount": 100}],
    "employeeConfig": {
        "residency": {
            "street1": "24 Willie Mays Plaza",
            "street2": "",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94107"
        },
        "taxparams": [
            {
                "jurisdiction": "US",
                "code": "FILINGSTATUS",
                "value": "H"
            },
            {
                "jurisdiction": "CA",
                "code": "REGULAR_ALLOWANCES",
                "value": "3"
            }
        ],
        "accruals": [
        ]
    },
    "companyConfig": {
        "taxparams": [
            {
                "jurisdiction": "CA",
                "code": "CALCULATE_FEE_CA_SANFRANCISCO",
                "value": "true"
            }
        ]
    },
    "payFrequency": "monthly",
    "payDate": "5/7/2021"
}

The response will be an array of taxes that will be levied for this employee. The net can be calculated by subtracting the sum of these from the gross pay of $1000

{
    "result": [
        {
            "codename": "FIT",
            "name": "Federal Income Tax",
            "payer": "EMPLOYEE_WITHHOLDING",
            "jurisdiction": "US",
            "withheld": 160.75
        },
        {
            "codename": "FICA_Medicare_EE",
            "name": "Medicare",
            "payer": "EMPLOYEE_WITHHOLDING",
            "jurisdiction": "US",
            "withheld": 14.50
        },
        {
            "codename": "FICA_Medicare_ER",
            "name": "Medicare",
            "payer": "EMPLOYER_LIABILITY",
            "jurisdiction": "US",
            "withheld": 14.50
        },
        {
            "codename": "FICA_MedicareAdditional_EE",
            "name": "Medicare Additional",
            "payer": "EMPLOYEE_WITHHOLDING",
            "jurisdiction": "US",
            "withheld": 0
        },
        {
            "codename": "FICA_SocialSecurity_EE",
            "name": "Social Security",
            "payer": "EMPLOYEE_WITHHOLDING",
            "jurisdiction": "US",
            "withheld": 62.0
        },
        {
            "codename": "FICA_SocialSecurity_ER",
            "name": "Social Security",
            "payer": "EMPLOYER_LIABILITY",
            "jurisdiction": "US",
            "withheld": 62.0
        },
        {
            "codename": "FUTA",
            "name": "Federal Unemployment Tax",
            "payer": "EMPLOYER_LIABILITY",
            "jurisdiction": "US",
            "withheld": 42.0
        },
        {
            "codename": "SUTA_CA",
            "name": "State Unemployment Tax",
            "payer": "EMPLOYER_LIABILITY",
            "jurisdiction": "CA",
            "withheld": 58.10
        },
        {
            "codename": "SIT_CA",
            "name": "State Income Tax",
            "payer": "EMPLOYEE_WITHHOLDING",
            "jurisdiction": "CA",
            "withheld": 72.05
        },
        {
            "codename": "SDI_CA_EE",
            "name": "California Temporary Disability Insurance Tax",
            "payer": "EMPLOYEE_WITHHOLDING",
            "jurisdiction": "CA",
            "withheld": 120.00
        },
        {
            "codename": "SDI_CA_ER",
            "name": "California Temporary Disability Voluntary Plan Assesesement",
            "payer": "EMPLOYER_LIABILITY",
            "jurisdiction": "CA",
            "withheld": 14.00
        },
        {
            "codename": "FEE_CA_SANFRANCISCO",
            "name": "San Francisco Payroll Expense Tax",
            "payer": "EMPLOYER_LIABILITY",
            "jurisdiction": "CA",
            "withheld": 38.00
        }
    ]
}