WEB API User Manual


Last update: April 26, 2018

Withholding32 API

 The Withholding32 API lets you dynamically calculate Federal, State and Local withholding with any device which has web access. The Withholding32 API returns calculated taxes in response to a URL GET request.  You can send the URL request using a web page, smart phone app, or any other device which can access the Internet.

You can try it right now using your browser. Copy the following line into your computers clipboard

https://www.withholding32.com/api/wh32calc.php?userid=T14X55734&fdy=&fpp=12&ffs=Married&fa=2&fgp=6000&figp=6000&st=0

Then Paste it into the URL line of your browser and press Enter. You will get a page with tax withholding information for Married person, with 2 allowances and an income of $6000.

You can see that your app builders task is to put required information into a url (like that above) and then parse the returned page to pull out the required tax information. The rest of this manual tells how to do this.

Using Withholding32 API

Using the Withholding API involves 3 steps.
  1. Send request to Withholding32 API
  2. Receive Data Back from Call
  3. Process Received Data

You call the Withholding32 API by sending an URL with a string of parameters attached.  These parameters are used to pass things like number of pay periods per year, gross pay, state, filing status and many more.

You can use any programming language used to program a mobile device. Examples for a variety of languages are given at the end of this document.

Note 1: In this document we show all URL's in plain text format for ease of reading. In reality URL's must be sent in URL-format. E.G. "Head of Household" would be sent as "Head%20of%20Household". Almost all smart phone programming languages and general programming languages have functions to perform this conversion for you. For example the Javascript function encodeURIComponent does this.

Note 2: This page is automatically updated to show a valid TEST user id.  This user id may change periodically.  Always refer to this document to find the current test user id.

Here are some examples showing parameters you will typically send.

Example 1

This example illustrates the URL required to calculate Federal Withholding.  Parameters are 12 pay periods per year, pretax cafeteria contribution of $200.00, pretax retirement contribution of $100.00,Federal filing status of Single, 2 allowancees, gross pay of 6000.00,FICA income of $6000.00,$0.00 previous fica contribution,supplemental pay of $1000.00,no state calculation

http://www.withholding32.com/api/wh32calc.php?userid=&fdy=&fpp=12&fpr=100.00&fpc=200.00&ffs=Single&fa=2&fgp=6000.00&figp=6000.00&fiytd=0&fsam=1000.00&st=0

HTML returned will be

Error=0,0
Federal withhold=891.06
FICA=285.60
Medicare=98.60
Federal Supplemental withhold=250.00
State withhold=0.00
State Supplemental withhold=0.00
City withhold=0.00
City Supplemental withhold=0.00
City Resident withhold=0.00
City Resident Supplemental withhold=0.00
County withhold=0.00
County Supplemental withhold=0.00
School withhold=0.00
School Supplemental withhold=0.00
SDI withhold=0.00
Version=2012.09,1.02
No messages

 

 

Example 2

This example illustrates the URL required to calculate Federal and California Withholding.

http://www.withholding32.com/api/wh32calc.php?userid=&fdy=&fpp=12&ffs=Married&fa=2&fgp=6000&figp=6000&fiytd=0&st=6&stp=6000&ss=Married&sa=2&sad=50&stca=1

HTML returned will be

Error=0,0
Federal withhold=631.25
FICA=252.00
Medicare=87.00
Federal Supplemental withhold=0.00
State withhold=202.92
State Supplemental withhold=0.00
City withhold=0.00
City Supplemental withhold=0.00
City Resident withhold=0.00
City Resident Supplemental withhold=0.00
County withhold=0.00
County Supplemental withhold=0.00
School withhold=0.00
School Supplemental withhold=0.00
SDI withhold=0.00
Version=2012.09,1.02
No messages

Your app would have to search for the desired tax information (i.e. search for "Federal withhold=" and then use the number that follows)

List of API Parameters

This section is divided into the following sections

Federal Tax Parameters

parameter you supply
userid string which contains your unique API code. You received 3 of these when you set up your account.  A temporary API code is available on the Withholding32 website for development purposes
ffs filing status (from w4).  Options are 'Single' or 'Married'
fa allowances (from w4). 
fad additional withholding (from w4) decimal
fpp pay periods per year
fgp federal gross pay for pay period decimal
fpr Decimal with amount of pretax contribution for this paycheck
fpc Decimal with amount of cafeteria plan contribution for this paycheck
fsam Decimal with supplemental amount
fsytd Decimal year to date supplemental amount (do not include this pay period)
fsct Supplemental tax type (0 = flat rate, 1=add to salary)
fdy year of calculation
fdm month of calculation
fdd day of calculation

Supplemental and FICA/Medicare Calculations

FICA and Medicare tax will automatically be calculated for supplemental income. Care must be taken in the case where pretax retirement is greater than regular pay and less than supplemental payment. In this situation FICA and Medicare could be calculated incorrectly. The safest thing to do in this situation is to calculate FICA/Medicare in a separate call the the engine and then perform the regular calculation but using the FICA/Medicare amount returned in the first calculation.

FICA and Medicare Tax Parameters

parameter you supply
figp fica gross pay for pay period
fiytd Decimal with employee gross year to date FICA wages.  Do not include current paycheck

State Specific Parameters

Local Withholding Information


State parameters include local parameters for states to which this applies. In order to calculate local withholding you will need the calculation number. for each local taxing body. We provide a way to get the calculation id as-well-as the actual name of each taxing body. You can use the name to setup a combo box or other method to prompt a user to select what taxing body they are under. Before we get to state parameters let's see how to get the local calcution id. If you are only interested in states who do not have local withholding then you can skip this section.
 

Local Taxing Names and Calculation Numbers

We support county, city and school district withholding for a number of states.  To calculate local withholding you have to pass the calculation API a calculation number which identifies the local taxing body.  You also have to prompt the end user to select the local taxing body.  We provide an API which equates the calculation number to local taxing body name.   You can use the name information in user prompts. You MUST use the calculation number when calling the calculation api.  As in the calculation api, you use a URL GET request to retrieve a page of information.  Calls this this api do not count against your limit.

Example

This example illustrates the URL required to request Kentucky city taxing names and the corresponding calculation number you would use when calling the calculation api..

https://www.withholding32.com/api/wh32prompts.php?state=21&muni=1

The return will be a page with each line containing the calculation number, a comma, and then the taxing body name. In the above example the return would be

2061,Adairville
1004,Ashland
2062,Auburn
...etc

 

Short Cut

The list of local taxing districts can be lengthy. It is better if you only request the list when it changes. As illustrated in the first examples 'version number' is the last line returned by most url calls.

Version=2017.09,1.02
When the Version number changes you should reload all local name/calcution number information.

   http://www.withholding32.com/api/wh32prompts.php?state=21&muni=0&returndate=Yes

You can save the returned version number along with the list of calculation numbers and names.  Then the next time you need the prompts request version number first and only retrieve the complete list if required.

State-by-state Instructions for returning Local Taxing Body information

Alabama

parameter you supply
state state(1=Alabama)
muni not used

Returned is a list of Cities

Colorado

parameter you supply
state state(7=Colorado)
muni not used

Returned is a list of Cities

Delaware

parameter you supply
state state(9=Delaware)
muni not used

Returned is a list of Cities

 

Indiana

parameter you supply
state state(18=Indiana)
muni not used

Returned is a list of Counties

Kentucky

parameter you supply
state state(21=Kentucky)
muni 0=school district
1=city
2=county

Returned is a list of either school districts, cities or counties

Maryland

parameter you supply
state state(25=Maryland)
muni not used

Returned is a list of Counties

Michigan

parameter you supply
state state(27=Michigan)
muni not used

Returned is a list of Cities

Missouri

parameter you supply
state state(30=Missouri)
muni not used

Returned is a list of Cities

New York

parameter you supply
state state(37=New York)
muni not used

Returned is a list of Cities

Ohio

parameter you supply
state state(41=Ohio)
muni 0=school district
1=city

Returned is a list of either school districts or cities

Pennsylvania

parameter you supply
state state(45=Pennsylvania)
muni 0=school district
1=city

Returned is a list of either school districts or cities

In addition to the Federal and Fica parameters each state requires the additional parameters shown below.

Alabama

parameter you supply
st state number (1 = Alabama)
stp state taxable pay
ss state filing status  Alabama options are
'Single'    'Married'   'Married filing Separately'   'Head of Household' ( from state w4)
stal number of Alabama dependents (from state w4)
stal2 number indicating if employee wants to claim personal exemption (0=no, 1=yes) (from state w4)
stall  calculation number of local taxing body
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)
Alabama Example

This example illustrates the URL required to calculate Alabama Withholding.

https://www.withholding32.com/api/wh32calc.php?userid=T14X55734&fpp=12&ffs=Married&fa=2&fgp=6000&figp=6000&fiytd=0&st=1&stp=6000&ss=Married&sa=2&sad=50&stall=1

HTML returned will be

Error=0,0
Federal withhold=612.90
FICA=372.00
Medicare=87.00
Federal Supplemental withhold=0.00
State withhold=296.02
State Supplemental withhold=0.00
City withhold=120.00
City Supplemental withhold=0.00
City Resident withhold=0.00
City Resident Supplemental withhold=0.00
County withhold=0.00
County Supplemental withhold=0.00
School withhold=0.00
School Supplemental withhold=0.00
SDI withhold=0.00
SDI employer withhold=0.00
SUI employer withhold=0.00
SUI employee withhold=0.00
FUTA employer withhold=0.00
Version=2018.01,1.02
No messages

Arizona

parameter you supply
st state number (4 = Arizona)
stp state taxable pay
staz decimal for Arizona withholding rate (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

Arkansas

parameter you supply
st state number (5 = Arkansas)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'   ( from state w4)
sa number of exemptions (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

California

parameter you supply
st state number (6=California)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'  'Head of Household ( from state w4)
sa number of allowances (from state w4)
stca number of state estimated deductions (de4 line 2)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)
sdip state sdi gross pay for pay period
sdiytd state sdi gross pay year-to-date (not including this pay period)

Colorado

parameter you supply
st state number (7=Colorado)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'  ( from state w4)
sa  number of allowances (from state w4)
stco  calculation number of local taxing body (link to be provided)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

Connecticut

parameter you supply
st state number (8=Connecticut)
stp state taxable pay
ss state filing status   options are
'Table A'    'Table B' 'Table C' 'Table D' 'Table E' 'Table F'  ( from state w4)
stct Decimal for Connecticut Reductional Amount (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

Delaware

parameter you supply
st state number (9=Delaware)
stp state taxable pay
ss state filing status   options are
'Single'    'Married' 'Married filing Separately'  ( from state w4)
sa  number of Claimed Credits
stde  calculation number of local taxing body (link to be provided)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

District of Columbia

parameter you supply
st state number (10=District of Columbia)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'  'Head of Household' 'Married filing Separately' ( from state w4)
sa  number of exemptions (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

Georgia

parameter you supply
st state number (13=Georgia)
stp state taxable pay
ss state filing status   options are
'Single'    'Married one Working'  'Married both Working' 'Married both Working Low Standard Deduction' 'Head of Household'  ( from state w4)
sa  number of allowances (from state w4)
stga  number of dependents (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

Hawaii

parameter you supply
st state number (15=Hawaii)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'   ( from state w4)
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)
sdip state sdi gross pay for pay period
sdiytd state sdi gross pay year-to-date (not including this pay period)
sdipp Number of Payperiods in year

Idaho

parameter you supply
st state number (16=Idaho)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'   'Head of Household'( from state w4)
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

Illinois

parameter you supply
st state number (17=Illinois)
stp state taxable pay
sa  number of allowances (from state w4)
stil  Illinois additional allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Indiana

parameter you supply
st state number (18=Indiana)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'  ( from state w4)
sa  number of exemptions (from state w4)
stin  number of dependents (from state w4)
stinl Local Taxing Body
stinr Residency (0 = Nonresident, 1 = Resident)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

Iowa

parameter you supply
st state number (19=Iowa)
stp Decimal state taxable pay
sa  number of allowances (from state w4)
sad Decimal state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd Decimial state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Kansas

parameter you supply
st state number (20=Kansas)
stp state taxable pay
ss state filing status   options are
'Single'    'Joint'  
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Kentucky

parameter you supply
st state number (21=Kentucky)
stp state taxable pay
sa  number of allowances (from state w4)
stkycnty  calculation number of county
stkycntyr  residency (0 = nonresident of county, 1=resident of county)
stkycity  calculation number of city
stkycityr  residency (0 = nonresident of city, 1=resident of city)
stkysch  calculation number of school district
stkyschr  residency (0 = nonresident of school, 1=resident of school)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Louisiana

parameter you supply
st state number (22=Louisiana)
stp state taxable pay
sa  number of personal exemptions (from state w4)
stla  number of dependent exemptions (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

Maine

parameter you supply
st state number (23=Maine)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'  ( from state w4)
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Maryland

parameter you supply
st state number (25=Maryland)
stp state taxable pay
sa  number of exemptions (from state w4)
stmd  calculation number of local taxing body (link to be provided)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Massachusetts

parameter you supply
st state number (26=Massachusetts)
stp state taxable pay
sa  number of exemptions and dependents (from state w4)
stmahoh  number of head of household allowances(from state w4)
stmabl  blind allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

Michigan

parameter you supply
st state number (27=Michigan)
stp state taxable pay
sa  number of personal and dependency exemptions (from state w4)
stmiwork  calculation number of local taxing body where employee works (link to be provided)
stmilive  calculation number of local taxing body where employee lives (link to be provided)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

Note: Michigan has both a tax for the location you work and the location you live. There will be an additional line output for Michigan e.g. city of residence withhold=

 

Minnesota

parameter you supply
st state number (28=Minnesota)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'   ( from state w4)
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

Mississippi

parameter you supply
st state number (29=Mississippi)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'   'Head of Household' 'Married both Working'( from state w4)
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Missouri

parameter you supply
st state number (30=Missouri)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'  'Head of Household'  'Married both Working' ( from state w4)
sa  number of allowances (from state w4)
stmo  calculation number of local taxing body (link to be provided)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Montana

parameter you supply
st state number (31=Montana)
stp state taxable pay
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

Nebraska

parameter you supply
st state number (32=Nebraska)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'   'Head of Household'  'Surviving Spouse' ( from state w4)
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

New Jersey

parameter you supply
st state number (35=New Jersey)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'   'Married filing Separate'  'Head of Household' 'Qualifying Widow' 'Table A' 'Table B' 'Table C' 'Table D' 'Table E'( from state w4)
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)
sdip state sdi gross pay for pay period
sdiytd state sdi gross pay year-to-date (not including this pay period)
sdier employer congtibution percentage (i.e.  .005 is 1/2 of 1%)

 

New Mexico

parameter you supply
st state number (36=New Mexico)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'   'Head of Household'   ( from state w4)
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

New York

parameter you supply
st state number (37 = New York)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'  ( from state w4)
sa  number of exemptions (from state w4)
sta  number of new york claimed allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
stnylocal Local Taxing Body
stnyla local allowances
stnyyr Yonkers Resident(1=yes, 0=no)(starting in year 2018)
stnylad decimal local additional withholding
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)
sdip state sdi gross pay for pay period
sdiytd state sdi gross pay year-to-date (not including this pay period)
sdipp Number of Payperiods in year
New York Example

This example illustrates the URL required to calculate New York Withholding. It calculates Yonkers Non-resident. The returned line City Resident withhold is not used. Whether resident or non-resident the city value is returned in City withhold.

https://www.withholding32.com/api/wh32calc.php?userid=T14X55734&fpp=12&ffs=Married&fa=2&fgp=6000&figp=6000&fiytd=0&st=37&stp=6000&ss=Married&sa=2&sad=50&stnylocal=1&stnyyr=0

HTML returned will be

Error=0,0
Federal withhold=612.90
FICA=372.00
Medicare=87.00
Federal Supplemental withhold=0.00
State withhold=351.28
State Supplemental withhold=0.00
City withhold=30.00
City Supplemental withhold=0.00
City Resident withhold=0.00
City Resident Supplemental withhold=0.00
County withhold=0.00
County Supplemental withhold=0.00
School withhold=0.00
School Supplemental withhold=0.00
SDI withhold=0.00
SDI employer withhold=0.00
SUI employer withhold=0.00
SUI employee withhold=0.00
FUTA employer withhold=0.00
Version=2017.11,1.02
No messages

 

North Carolina

parameter you supply
st state number (38=North Carolina)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'   'Head of Household'  'Qualifying Widower' ( from state w4)
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

North Dakota

parameter you supply
st state number (39=North Dakota)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'   ( from state w4)
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Ohio

parameter you supply
st state number (41=Ohio)
stp state taxable pay
sa  number of allowances (from state w4)
stohsc  calculation number of school district (link to be provided)
stohmu  calculation number of municipality (link to be provided)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Oklahoma

parameter you supply
st state number (42 = Oklahoma)
stp state taxable pay
ss state filing status   options are
'Single'    'Joint'   'Married both Working'
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Oregon

parameter you supply
st state number (43 = Oregon)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'   ( from state w4)
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Pennsylvania

parameter you supply
st state number (45 = Pennsylvania)
stp state taxable pay
stpasc  calculation number of school district (link to be provided)
stpamu  calculation number of municipality (link to be provided)
stpamur  municipal residency (0=nonresident, 1=resident)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Rhode Island

parameter you supply
st state number (47 = Rhode Island)
stp state taxable pay
ss state filing status   options are
'Single'    'Joint'   'Head of Household'
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)
sdip state sdi gross pay for pay period
sdiytd state sdi gross pay year-to-date (not including this pay period)

 

 

South Carolina

parameter you supply
st state number (48 = South Carolina)
stp state taxable pay
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Utah

parameter you supply
st state number (52 = Utah)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'  
sa  number of allowances (only used before May 1, 2018)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Vermont

parameter you supply
st state number (53 = Vermont)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'  
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Virginia

parameter you supply
st state number (55 = Virginia)
stp state taxable pay
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

West Virginia

parameter you supply
st state number (57 = West Virginia)
stp state taxable pay
sa  number of allowances (from state w4)
stwv  optional spouse now working withholding (from state w4) (1 = regular, 0=use lower rate since spouse doesn't work)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

Wisconsin

parameter you supply
st state number (58 Wisconsin)
stp state taxable pay
ss state filing status   options are
'Single'    'Married'  
sa  number of allowances (from state w4)
sad state additional withholding amount per pay period (from state w4)
ssam Decimal for state supplemental pay amount
ssytd state supplemental pay amount year -to-date
ssct supplemental tax type (0=flat, 1=add to regular pay)

 

 

        

State Unemployment Insurance

Withholding for State Unemployment Insurance is supported for all states.  The parameters below can be included in the regular calculation list parameters.  You have to pass the employer withholding rate since this varies with employer.  Our database will test against the annual maximum.

SUI

parameter you supply
suip state taxable pay
suiytd Year to date taxable pay not including this paycheck
suier Employer withholding percentage (1/2 % would be .005
suiee Employee withholding percentage (1/2 % would be .005
 

Returned Data Format

Data will be returned in the general format shown below.  Your app can search for the text to the left of the equal (=) sign and then retrieve the number to the right.  Each line ends with a "<br>" html command.  You should not assume that lines will necessarily be in the order shown.

        

Error=0,0
Federal withhold=631.25
FICA=252.00
Medicare=87.00
State withhold=0.00
State withhold=202.92
State Supplemental withhold=0.00
City withhold=0.00
City Supplemental withhold=0.00
City Resident withhold=0.00
City Resident Supplemental withhold=0.00
County withhold=0.00
County Supplemental withhold=0.00
School withhold=0.00
School Supplemental withhold=0.00
SDI withhold=0.00
SUI employer withhold=
SUI employee withhold=
Version=2012.09,1.02
No messages

Error codes

Two error codes are returned.  The first is the Withholding32 DLL error code and the 2nd is the WEB API error code

 

        

Federal Unemployment Insurance

Withholding for Federal Unemployment Insurance(FUTA) is supported for all states.  The parameters below can be included in the regular calculation list parameters.  You have to pass the employer withholding rate since this varies with employer.  Our database will test against the annual maximum.

FUTA

parameter you supply
futap federal taxable pay
futaytd Year to date taxable pay not including this paycheck
futaer Employer withholding percentage (1/2 % would be .005
 

Returned Data Format

Data will be returned in the general format shown below.  Your app can search for the text to the left of the equal (=) sign and then retrieve the number to the right.  Each line ends with a "<br>" html command.  You should not assume that lines will necessarily be in the order shown.

        

Error=0,0
Federal withhold=631.25
FICA=252.00
Medicare=87.00
State withhold=0.00
State withhold=202.92
State Supplemental withhold=0.00
City withhold=0.00
City Supplemental withhold=0.00
City Resident withhold=0.00
City Resident Supplemental withhold=0.00
County withhold=0.00
County Supplemental withhold=0.00
School withhold=0.00
School Supplemental withhold=0.00
FUTA employer Withhold= Version=2012.09,1.02
No messages

 

        

Family Leave

Family Leave Insurance is supported in New Jersey and New York.  A separate call should be made to the calculation api using the parameters below.  Our database will test against the annual maximum.

Family Leave

parameter you supply
fls State number (35 is New Jersey and 37 is New York)
fly year
flm month
fld day
flgp gross pay
flgpytd gross pay year-to-date (non including flgp)

 

        

Oregon Transit

There are two type of transit tax. There are several local taxes which are paid by employer. Since the rate varies we provide a variable to send the withholding percentage to our transit calculation function.

In addition, effective July 1, 2018 there is a statewide transit tax paid by almost all employees. On after this date we return the tax amount based on the percentage in our database and the amount of pay you pass.

We then return the local employer tax and the employee tax.

Transit Tax

parameter you supply
ttstate State number (43 is Oregon)
ortti Pay subject to tax
ortty year
orttm month
orttd day
orttytd gross pay year to date
orttrate Employer withholding percentage for optional local employer paid tax. .005 would be 1/2 of 1%

Optional employer tax withholding amount is returned in line: Oregon employer transit tax=

Statewide employee withholding amount is returned in line: Oregon statewide employee transit tax=  

Returned Data Format

Data will be returned in the general format shown below.  Your app can search for the text to the left of the equal (=) sign and then retrieve the number to the right.  Each line ends with a "<br>" html command.  You should not assume that lines will necessarily be in the order shown.

        

Family Leave Error=0

Family Leave Withholding=2.70

Error codes

Two error codes are returned.  The first is the Withholding32 DLL error code and the 2nd is the WEB API error code

Family Leave Example

This example illustrates the URL required to calculate New Jersey Family Leave.

https://www.withholding32.com/api/wh32calc.php?userid=T14X55734&fpp=12&ffs=Married&fa=2&fgp=6000&figp=6000&fiytd=0&st=37&stp=6000&ss=Married&sa=2&sad=50&stnylocal=1&stnyyr=0

HTML returned will be

Family Leave Error=0 Family Leave Withholding=1.80

Withholding32 DLL error codes

One or more of the following bits may be set.  If the returned code is 0 then no error occurred. 

  • bit 0:  Federal Error
  • bit 1:  FICA Error
  • bit 2:  Medicare Error
  • bit 3:  State Error
  • bit 4:  Local Error

Web API error codes

  • 0: no error
  • 1: invalid user id

 

 

 

PHP Example

Here is a code snipped demonstrating php use of this api.


//
// set up url to get withholding data from web api
//
$thedate=getdate();
$themonth=$thedate['mon'];
$theyear=$thedate['year'];
$theday=$thedate['mday'];
$surl="http://www.withholding32.com/api/wh32calc.php";
$surl=$surl."?userid=xxxx";                    // correct userid must be supplied
$surl=$surl."&fpp=".$pcpperyear;          // $pcpperyear has been initialized with number of pay periods/year
$surl=$surl."&fpr=".$pcpretax;              // $pcpretax has been initialized with pretax contribution
$surl=$surl."&fss=Married";                  // Federal status of Married
$surl=$surl."&fa=2";                               // 2 allowances
$surl=$surl."&fgp=".$pcgross;               // $pcgross has been initialized with gross pay for pay period
$surl=$surl."&figp=".$pcgross;
$surl=$surl."&fiytd=0";                          // first paycheck of year so no previous fica
$surl=$surl."&st=1";                              // alabama
$surl=$surl."&stp=".$pcgross;
$surl=$surl."&ss=".urlencode($ss);      // save way to put text in a url
$surl=$surl."&stal=".$sa;                       // state allowances
$surl=$surl."&stal2=0";                         // state optional value
$surl=$surl."&fdy=".$theyear;
$surl=$surl."&fdm=".$themonth;
$surl=$surl."&fdd=".$theday;
$surl=$surl."&debug99=99";

$thedata=file_get_contents($surl);         // call to get withholding data from url

//
//call function to extract values we want from data returned by url
//
list($errordis,$resultdis,$federal,$state,$local)= get_withhold_value($thedata);



//
// Return partial withholding data from string returned from web api
//
//Note this function does not return ALL withholding values, just a few to give the idea

function get_withhold_value($thedata){

$local=0;
$thelines=explode("
",$thedata);
$rows=count($thelines);
for($i=0;$i<$rows;$i++){
$mes=strpos($thelines[$i],"Error=",0);
if($mes!==false){
$errordis="";
$resultdis="";
}

$mes=strpos($thelines[$i],"Federal withhold=",0);
if($mes!==false){
$thesize=strlen($thelines[$i])-17;
$federal=substr($thelines[$i],17,$thesize);
}
$mes=strpos($thelines[$i],"State withhold=",0);
if($mes!==false){
$thesize=strlen($thelines[$i])-15;
$state=substr($thelines[$i],15,$thesize);
}

}

return array($errordis,$resultdis,$federal,$state,$local);
}

 

 

Asynchronous JavaScript and XML (AJAX)


Our API is totally usable using AJAX. Since most browsers limit cross platform scripting you will have to call our API through a link on your own server. Below is an example of a PHP program which will accept an AJAX request and pass it on to our API.  This code would recide on YOUR server.

Here is a code snipped demonstrating php use of this api.


$sstatus=session_start();
$all=$_SERVER['QUERY_STRING']; // get all arguments
//
// redirect to withholding32 api
//
$location="https://www.withholding32.com/api/wh32calc.php?".$all;
$ch=curl_init();
curl_setopt($ch,CURLOPT_URL,$location);
curl_setopt($ch,CURLOPT_HEADER,0);
$content=curl_exec($ch);
curl_close($ch);





 

 

JAVA Example


Our API is totally usable using AJAX. Since most browsers limit cross platform scripting you will have to call our API through a link on your own server. Below is an example of a PHP program which will accept an AJAX request and pass it on to our API.  This code would recide on YOUR server.

  1. Send Request

  2. String surl="https://www.withholding32.com/api/wh32calc.php?
      userid=T14X55734&fdy=&fpp=12&ffs=Married&fa=2&fgp=6000&figp=6000&st=0";
    surl=URLEncoder.encode(surl,"utf-8");
    URL url = new URL(surl);
    InputStream stream=url.openStream();
     
  3. Receive Data

    String inputLine;
    String allLines;
    while ((inputLine = in.readLine()) != null){
      allLines[index++]=inputLine;
    }
    in.close();
     
  4. Process Data  

    for(index i=0; index<allLines.length; index++){
     if(allLines[index].contains("Medicare=")){
       String medicarewithholdamount=allLines[index].substring(9,allLines[index].length);
     }
     else if(allLines[index].contains("Federal withhold=")){
      // extract Federal withholding from string would go here
     }
     else if(allLines[index].contains("more search fields=")){
      //...
     }