forms (POST)

The forms endpoint receives a single home address and one or more work address(es) representing the employee’s physical work locations. See the sample json request below.

{
	"homeAddress": {
	    "streetAddress1": "11 S Union St",
		"city": "Montgomery",
		"state": "AL",
		"zipCode": "36130"
	},
	"workAddresses": [
		{
			"streetAddress1": "64 N Union St",
			"city": "Montgomery",
			"state": "AL",
			"zipCode": "36130"
		}
	]
}

The /forms endpoint returns a list of applicable forms for the employee’s withholding scenario and various details about the form. In addition this endpoint will return a location data object that will check to make sure home and work addresses are valid and can also normalize and geocode them.

🚧

Location Data

For more information about the location data object navigate to Location Data Page

{
    "forms": [
        {
            "id": "W4101",
            "name": "W-4",
            "title": "Employee's Withholding Certificate",
            "formVersion": "2021.1.0",
            "formLocality": "FEDERAL",
            "formType": "RESIDENT",
            "recommended": true,
            "initialQuestionSet": "QS1"
        },
        {
            "id": "AL101",
            "name": "A4",
            "title": "Employee's Withholding Exemption Tax Certificate",
            "formVersion": "2014.3.0",
            "formLocality": "AL",
            "formType": "RESIDENT",
            "recommended": true,
            "initialQuestionSet": "QS1"
        }
    ],
    "locationData": [
        {
            "id": "home",
            "inputAddress": {
                "streetAddress1": "11 S Union St",
                "city": "Montgomery",
                "state": "AL",
                "zipCode": "36130"
            },
            "normalizedAddress": {
                "streetAddress1": "11 S Union St",
                "city": "Montgomery",
                "state": "AL",
                "zipCode": "36130-2102"
            },
            "addressResultMessages": {
                "GS01": {
                    "message": "Geocoded to Street Level",
                    "description": "The record was coded to the street level (Zip+4 for US, full postal code for CA)."
                },
                "AS01": {
                    "message": "Valid Address",
                    "description": "The address is valid and deliverable according to official postal agencies."
                }
            },
            "latitude": "32.376634",
            "longitude": "-86.299645",
            "verified": true,
            "geocoded": false
        },
        {
            "id": "work1",
            "inputAddress": {
                "streetAddress1": "64 N Union St",
                "city": "Montgomery",
                "state": "AL",
                "zipCode": "36130"
            },
            "normalizedAddress": {
                "streetAddress1": "64 N Union St",
                "city": "Montgomery",
                "state": "AL",
                "zipCode": "36130-3020"
            },
            "addressResultMessages": {
                "GS01": {
                    "message": "Geocoded to Street Level",
                    "description": "The record was coded to the street level (Zip+4 for US, full postal code for CA)."
                },
                "AS01": {
                    "message": "Valid Address",
                    "description": "The address is valid and deliverable according to official postal agencies."
                }
            },
            "latitude": "32.378229",
            "longitude": "-86.299726",
            "verified": true,
            "geocoded": false
        }
    ]
}

Displayed above is an example object returned based upon the home and work address(es) provided.

1. id represents the actual form id which can be referenced from the getAllFormIds endpoint.
2. name the actual name of the form to be completed
3. formVersion the latest and recommended form version to be completed
4. formLocality what the forms locality is
5. formType what type of form resident, nonresident, military, exempt, pension etc..
6. Based upon your home and work addresses, the response also provides whether a form is recommended to be completed by your employee.
7. initialQuestionSet is provided and most always defaults to QS1 for what question set is the start of the form process

You can use the id and initialQuestionSet to submit to the /formQuestionSet/{formId}/{questionSetId} endpoint to begin the form completion process and get details about the next question set.

Lock In Letters

At times, the IRS may give an employer an order to withhold taxes at a minimum rate. Therefore, SPF-API provides a mechanism to prevent employees from changing certain state or federal withholding forms. Refer to the Lock In Letter documenation for more details and a sample request.

Nexus

Nexus can be specified using the forms endpoint. Refer to the Nexus documentation for more details and a sample request.

At Symmetry, we have a dedicated Tax Research team that helps us filter down forms based upon a business's tax presence when they have operations in more than one state. Deciding which state's payroll tax to withhold from an employee can be a confusing process.

No matter which state or multiple states an employee or employer operates in, SPF-API will automatically filter down the proper withholding forms for each scenario and return it in the forms (POST) endpoint.

Interstate Employees

Interstate commerce means any work involving or related to the movement of persons or things (including intangibles, such as information) across state lines or from foreign countries. Interstate employees are not taxed at the states they drive through or where the destination resides.

For Pennsylvania residents, this has the effect of limiting multi-state form determination to Federal forms and PA local forms, removing any other forms outside of those jurisdictions. To mark a PA resident employee as an interstate employee, set the interstateEmployee field to true.

📘

Timezones

The /forms endpoint may be passed a timezone in the headers, as the Timezone header, of the request to specify the timezone that should be used when signing and dating a completed form. Specified timezones will only be used if signForm is set to SIGN. If no value is passed with the request, then the API with default to UTC.

Information on accepted Timezone IDs can be found here.