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(sample)
- List of API Parameters
- Federal Parameters
- Supplemental Calculations of FICA/Medicare
- FICA and Medicare Parameters
- State Parameters
- Local Taxing Names and Calculation Numbers(sample)
- Alabama(sample)
- Arizona
- Arkansas
- California
- Colorado
- Connecticut
- Delaware
- District of Columbia
- Georgia
- Hawaii
- Idaho
- Illinois
- Indiana
- Iowa
- Kansas
- Kentucky
- Louisiana
- Maine
- Maryland
- Massachusetts
- Michigan
- Minnesota
- Mississippi
- Missouri
- Montana
- Nebraska
- New Jersey
- New Mexico
- New York(sample)
- North Carolina
- North Dakota
- Ohio
- Oklahoma
- Oregon
- Pennsylvania
- Rhode Island
- South Carolina
- Utah
- Vermont
- Virginia
- West Virginia
- Wisconsin
- State Unemployment Insurance (SUI)
- Federal Unemployment Insurance (FUTA)
- Family Leave
- Oregon Transit Taxes
- Returned Data Format
- PHP Example
- AJAX Example
- AJAX Example
Using Withholding32 API
Using the Withholding API involves 3 steps.- Send request to Withholding32 API
- Receive Data Back from Call
- 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.
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) |
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 |
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.
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.
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.
- Send Request
- Receive Data
String inputLine;
String allLines;
while ((inputLine = in.readLine()) != null){
allLines[index++]=inputLine;
}
in.close();
- 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=")){
//...
}
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();