TaxServer Web Service

Tax Properties

Properties for a specific tax

http://3.213.184.41:8000/tax/<name>[?<parameters>]

where <name> is the tax name

parameter

Description

paydate

Check date in the form YYYY-mm-dd. Defaults to current date.

field

Specific property to return. Default is all fields
name - tax name (string)
title - tax title (string)
taxtype - tax type (string) - F, S, L, O, or P
published - Date tax published by Caliber Technology--may be empty (string)
effective_date - Date tax goes became effective--may be empty (string)
withheld - True if withheld from employee pay (boolean)
rounding_required - True if tax calculation must be rounded (boolean)
rounding_optional - True if tax calculation can be rounded (boolean)
has_tax - True if tax exists
nonresident - True if tax only applies to nonresidents (boolean)
exemptions_instructions - Description of value required in the exemptions field, suitable as help text for a user-facing form (string)
stateexemptions_instructions - Description of value required in the stateexemptions field, suitable as help text for a user-facing form (string)
stateexemptions_tag - Brief description of the stateexemptions field, suitable as a label on a user-facing form (string)
miscellaneous_instructions - Description of value required in the miscellaneous field, suitable as help text for a user-facing form (string)
miscellaneous_tag - Brief description of the miscellaneous field, suitable as a label on a user-facing form (string)
auxiliary_instructions - Description of value required in the auxiliary field, suitable as help text for a user-facing form (string)
auxiliary_tag - Brief description of the auxiliary field, suitable as a label on a user-facing form (string)
psd - Tax identifier required for OH and PA W-2 reporting (numeric)

For example, to list all properities for the 'CA' tax:

http://3.213.184.41:8000/tax/ca

To retrieve the effective date for the "AL Fairfield" tax:

http://3.213.184.41:8000/tax/al fairfield?field=effective_date

Batch Tax Properties

Properties for a batch of taxes

http://3.213.184.41:8000/batch/<names>[?<parameters>]

Returns an array of objects, one for each taxname included in the 'names' list, which is a comma-delimited list of tax names. Each returned object will be the same format used by "Tax Properties" above (endpoint /tax/<name>), with the addition of a "taxname" element. At least one taxname is required in the <names> portion of the url.

parameter	Description
paydate	Check date in the form YYYY-mm-dd. Defaults to current date.
field	Specific property to return. Default is all fields. Identical to "field" parameter of "Tax Properties" above.

For example, to list all properties for the "KY" and "AR" taxes:

http://3.213.184.41:8000/batch/KY,AR

To retrieve the published date for the "NY", "NJ", and "PA" taxes:

http://3.213.184.41:8000/batch/NY,NJ,PA?field=published

Tax Calculation

Calculation of a specific tax

http://3.213.184.41:8000/taxamount/<name>[?<parameters>]

where <name> is the tax name

parameter	Description
paydate	Check date in the form YYYY-mm-dd. Defaults to current date.
payperiods	Number of pay periods per year. Defaults to 12 (monthly).
supplemental	Set to "1", "Y", or "True" to indicate a non-regular or bonus payment. Defaults to false.
filingstatus	0 - Single (default) 1 - Head of Household 2 - Widow(er) 3 - Married Filing Jointly 4 - Married Filing Separately 5 - Married Both Employed
earnings	Gross taxable earnings for the pay period. Defaults to 0.
ytdearnings	YTD earnings paid PRIOR TO the current pay period. Defaults to 0.
exemptions	Employee's federal exemptions. Defaults to 0.
stateexemptions	Employee's state exemptions. Defaults to 0.
ytdtax	YTD taxes paid PRIOR TO the current pay period. Defaults to 0.
miscellaneous	Additional information needed for some tax calculations. Taxes which require miscellaneous input include a non-empty miscellaneous_instructions property. Defaults to 0.
auxiliary	Additional information needed for some tax calculations. Taxes which require miscellaneous input include a non-empty auxiliary_instructions property. Defaults to 0.
unemploymentrate	Employer's unemployment rate, expressed as a floating point (e.g., 2.4% => 0.024). Defaults to 0.
round	Set to "1", "Y", or "True" to request rounding when it is optional. Defaults to false.
companyzip	Set to employer ZIP code for unemployment tax purposes. Required only for FUTA calculation.

For example, to calculate NY with:
	earnings = 1000
	stateexemtions = 2
	payperiods = 12 (default)
http://3.213.184.41:8000/taxamount/ny?earnings=1000&stateexemptions=2

Batch Tax Calculation

Calculation for a batch of taxes

http://3.213.184.41:8000/batch_taxamount

Note: This end-point requires a POST request with a TaxBatch JSON body as described below.

You should also include a header for Content-Type: application/json.

TaxBatch:

{
  "paydate": string,
  "payperiods": integer,
  "earnings": number,
  "supplemental": boolean,
  "ytdearnings": number,
  "exemptions": integer,
  "stateexemptions": integer,
  "filingstatus": integer,
  "unemploymentrate": number,
  "round": boolean,
  "companyzip": integer,
  "taxlist": TaxInfo[] (required)
}

All keys are optional unless specifically designated as required.

parameter	Description
paydate	Check date in the form YYYY-mm-dd. Defaults to current date.
payperiods	Number of pay periods per year. Defaults to 12 (monthly).
earnings	Gross taxable earnings for the pay period. Defaults to 0.
supplemental	A true value indicates a non-regular or bonus payment. Defaults to false.
ytdearnings	YTD earnings paid PRIOR TO the current pay period. Defaults to 0.
exemptions	Employee's federal exemptions. Defaults to 0.
stateexemptions	Employee's state exemptions. Defaults to 0.
filingstatus	0 - Single (default) 1 - Head of Household 2 - Widow(er) 3 - Married Filing Jointly 4 - Married Filing Separately 5 - Married Both Employed
unemploymentrate	Employer's unemployment rate, expressed as a floating point (e.g., 2.4% => 0.024). Defaults to 0.
round	A true value requests rounding of tax amounts which may be optionally rounded. Defaults to false.
companyzip	Set to employer ZIP code for unemployment tax purposes. Required only for FUTA calculation.
taxlist	A JSON array of TaxInfo objects (described below).

TaxInfo:

{
  "taxname": string (required),
  "ytdtax": number,
  "miscellaneous": number,
  "auxiliary": number,
  "paydate": string,
  "payperiods": integer,
  "supplemental": boolean,
  "ytdearnings": number,
  "exemptions": integer,
  "stateexemptions": integer,
  "filingstatus": integer,
  "unemploymentrate": number,
  "round": boolean,
  "companyzip": integer
}

parameter	Description
taxname	The name of the tax to be computed for this entry of the batch.
ytdtax	YTD taxes (for this taxname) paid PRIOR TO the current pay period. Defaults to 0.
miscellaneous	Additional information needed for some tax calculations. Taxes which require miscellaneous input include a non-empty miscellaneous_instructions property. Defaults to 0.
auxiliary	Additional information needed for some tax calculations. Taxes which require miscellaneous input include a non-empty auxiliary_instructions property. Defaults to 0.
...	The remaining parameters are for overriding the corresponding parameter in the enclosing TaxBatch for this entry of the batch.

Result:

{
  "status": string ("ok" | "error")
  "value": BatchResponse | error message
}

BatchResponse:

{
    "earnings": number,
    "net": number,
    "taxes": TaxResponse[]
}

Key	Description
earnings	Same as the earnings passed in the request.
net	The calculated net pay for this batch.
taxes	An array of TaxResponse objects, one for each entry in the TaxBatch request.

TaxResponse:

{
  "taxname": string,
  "amount": number,
  "taxtype": string,
  "withheld": boolean
}

Key	Description
taxname	The name of the tax for this entry of the batch.
amount	The resulting computed amount for this tax.
taxtype	The taxtype (F, S, L, O, or P) for this tax.
withheld	True if this tax should be withheld from employee pay, false if tax is paid by the employer.

Example request JSON

Note that this request takes the default value for several keys, including "exemptions", "payperiods", and "supplemental". By including exemptions in the "fit" TaxInfo object, this calculation gets a value of 2 while the other tax entries get the default value of 0.

{
  "earnings": 3000,
  "ytdearnings": 2000,
  "filingstatus": 1,
  "stateexemptions": 1,
  "paydate": "2022-01-01",
  "companyzip": 10001,
  "unemploymentrate": 0.052,
  "round": true,
  "taxlist":
    [
      { "taxname": "fit", "exemptions": 2 },
      { "taxname": "fica med" },
      { "taxname": "futa", "ytdearnings": 6000, "auxiliary": 1 }
    ]
}

This request would result in the following response (based on 2021 tables):

{
  "status":"ok",
  "value": {
    "earnings":3000.0,
    "net":2814.5,
    "taxes":
      [
         {"amount":142.0,"taxname":"fit","taxtype":"F","withheld":true},
         {"amount":43.5,"taxname":"fica med","taxtype":"F","withheld":true},
         {"amount":60.0,"taxname":"futa","taxtype":"O","withheld":false}
      ]
   }
}

TaxServer API Overview

A summary of TaxServer's payroll tax calculation interface.