Taxes Endpoint
Retrieve taxes by home and work locations.
The /taxes endpoint is the main endpoint within Payroll Point that returns taxes by home and work location(s).
Clients must provide an active access token (accessToken) as a credential when connecting to this endpoint. Refer to the authentication endpoint overview for instructions on how to request an access token (accessToken). Additionally, when making the HTTP request to the /taxes endpoint, clients must set the accept-content header to application/json: --header 'Content-Type: application/json'.
Demo
Interested in seeing a demo of the PRP endpoints with one our product engineers? Connect with us to get access to the endpoints and product demos.
Current clients can log into Symmetry's Client Support Center to see a demo of this endpoint!
The /prp/v1/taxes endpoint can receive the following address combinations within the array:
- a single home address (or latitude/longitude pair) and one work address (or latitude/longitude pair) for an employee.
- a single home address (or latitude/longitude pair) and multiple work addresses (or latitude/longitude pairs) for an employee.
The /prp/v1/taxes endpoint returns a list of all applicable taxes for the employee.
Sample Request
{
"taxRequestId": "1",
"payDate": "",
"useAddressSuggestion": false,
"home": {
"companyHasNexus": true,
"location": {
"address": {
"streetAddress1": "123 main st",
"streetAddress2": "",
"city": "Edison",
"state": "NJ",
"zipCode": "08837"
},
"geoCoordinates": {
"latitude": 0,
"longitude": 0
}
}
},
"work": [
{
"locationName": "Symmetry Work Address",
"nonResidentCertificateOnFile": true,
"location": {
"address": {
"streetAddress1": "14350 87th st",
"streetAddress2": "",
"city": "Scottsdale",
"state": "AZ",
"zipCode": "85260"
},
"geoCoordinates": {
"latitude": 0,
"longitude": 0
}
}
}
]
}
Request Elements
| Element | Enforcement | Type | Description |
|---|---|---|---|
| home | Required | Object | Contains location object for employee’s home and whether the company has Nexus. See Location Object. |
| home.companyHasNexus | Required | Boolean | Set to true if company has a business presence. |
| payDate | Optional | String | Date payroll is run. Must be in YYYY-MM-DD format. Pass in an empty string to default to today’s date. |
| taxRequestId | Optional | String | Optional value set by client to track request. |
| work | Required | Array | An array of work objects. |
| work[x].locationName | Optional | String | Optional value set by client that refers to the work location. |
| work[x].nonResidentCertificateOnFile | Required | Boolean | When set to true, employee utilizes reciprocity and is exempt in the work state and withholds only in the home state. Please note that “nonresident certificate” may not always refer to an entirely separate form. For example, if Virginia was the work state, then it would correspond to the checkbox on line 3 of the Virginia Form VA-4. |
| work[x].location | Required | Object | Contains address and geocoordinate objects. See Location Object. |
| location | Required | Object | Contains address and geocoordinate objects. |
| location.address | Required if location.geoCoordinates is null | Object | Street address for specified location. |
| location.address.street Address1 | Required if location.geoCoordinates is null | String | Street number and street name. |
| location.address.street Address2 | Optional | String | Address identifier (e.g., apartment number, suite number, etc.). |
| location.address.city | Required if location.geoCoordinates is null | String | City name. |
| location.address.state | Required if location.geoCoordinates is null | String | State name or abbreviation. |
| location.address.zipCode | Required if location.geoCoordinates is null | String | Postal zip code (either 5 or 9 digits). |
| location.geoCoordinates | Required if location.address is null | Object | Longitude and latitude coordinates of specified location. |
| location.geoCoordinates.latitude | Required if location.address is null | Number | Latitude. |
| location.geoCoordinates.longitude | Required if location.address is null | Number | Longitude. |
| useAddressSuggestion | Optional | Boolean | When set to true, if an invalid address is provided in the location object, Payroll Point will use the first suggested address that closely matches the inputted address instead of returning a transaction error. If no suggested address is found, Payroll Point will geocode based on the ZIP code. Read more here. |
Sample Response
The response contains an array of result objects that include location details for the normalized home and work locations in addition to the taxes related to each jurisdiction.
Below is an example of a successful request. Repeated elements are omitted with an {...}.
{
"result": {
"homeResults": {
"inputGeoCoordinates": {
"longitude": 0.0,
"latitude": 0.0
},
"locationDetails": {
"taxJurisdictions": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"name": "New Jersey",
"steCode": "34",
"stateCode": "34",
"steCodeType": "STATE"
}
},
{...}
]
},
"locationCode": "34-023-0004052284107435813"
},
"locationTaxes": [
"34-000-0000-SIT-000",
...
],
"addressResults": {
"inputAddress": {
"streetAddress1": "123 Main St",
"streetAddress2": "",
"city": "Edison",
"state": "NJ",
"zipCode": "08837"
},
"normalizedAddress": {
"streetAddress1": "123 Main St",
"city": "Edison",
"state": "NJ",
"zipCode": "08837-2920"
},
"isVerified": true,
"addressResultMessages": {
"GS06": {
"shortDescription": "Geocoded to Interpolated Rooftop Level",
"longDescription": "The record was geocoded down to the rooftop level using interpolation (educated estimations using street coordinates). The point may be in or close to the property boundaries."
},
{...}
},
"addressErrorMessages": {},
"isGeocoded": false,
"latitude": 40.522835,
"longitude": -74.358125,
"addressTypeCode": "S",
"addressTypeDescription": "Street"
}
},
"workResults": {
"workLocation1": {
"locationName": "Main Office",
"inputGeoCoordinates": {. . .},
"locationDetails": {. . .},
"locationTaxes": [. . .],
"addressResults": {. . .},
}
},
"payDate": "2021-08-04",
"taxResults": [
{
"uniqueTaxID": "34-000-0000-SIT-000",
"description": "New Jersey State Tax",
"rate": 0.0,
"rateType": "RATE_GRADUATED",
"wageBase": 0.0,
"taxLimit": 0.0,
"taxLimitPeriod": "None",
"taxStartDate": "2016-01-01",
"credit": 0.0,
"creditLimit": 0.0,
"paid": true,
"stateWide": true,
"stateCode": "34",
"stateName": "New Jersey",
"employerTax": false,
"resident": true
},
{...}
],
"customCodes": [],
"minimumWage": [
{
"mwUid": "00-0-000000000-REG-000-000",
"state": "Federal",
"stateCode": 0,
"authorityCode": 0,
"authority": "",
"authorityType": "Federal",
"authorityTypeCode": 0,
"rate": "7.25",
"effectiveDate": "2017-01-01",
"majorType": "REG",
"industryType": "",
"industryTypeCode": 0,
"minorType": "",
"minorTypeCode": 0,
"details": " ",
"updated": "2020-10-27 14:39:28"
},
{...}
]
}
"transactionDetails": {
"timestamp": "2021-08-17T12:59:51.572",
"serviceVersion": "Address Service: 0.1.5, Address Data Build: 17296 (2021-07-15). Geo Data Build: 17260 (2021-07-15). ; Location service: 0.2.0. ; STE hosted: 1.74.0, STE: 2021-R9; Payroll Point service: 1.2.26",
"processedTransactions": 1,
"processingTime": 0.495000000
}
}
Response Elements
The descriptions below outline the key elements in a successful response.
Location Details Object
The Location Details object is returned for each home and work location passed into the endpoint.
| Element | Type | Description |
|---|---|---|
| locationDetails | Object | Returns details related to the location’s taxing jurisdiction |
| locationDetails.taxJurisdictions | Object | Feature details for the location including school, county, city, and state properties |
| locationDetails.taxJurisdictions.type | String | Always returns "FeatureCollection" |
| locationDetails.taxJurisdictions.features | Array | Array of Feature objects |
| locationDetails.locationCode | String | Location Code of the location’s geocoordinates |
| locationDetails.psdCode | String | Pennsylvania political subdivision code. Note: this element is only returned for PA locations ("stateCode": "42") |
Features Object
The Features object is returned for each home and work location passed into the endpoint.
| Element | Type | Description |
|---|---|---|
| features | Array | Returns feature properties including school, county, city, and state details. |
| features.type | String | Always returns "Feature" |
| features.properties | Object | Contains details including school, county, city, and state properties |
| features.properties.name | String | Feature location name that corresponds to properties.steCode returned |
| features.properties.steCode | String | Numeric code assigned to feature location. Defined by properties.name |
| features.properties.stateCode | String | Two-digit value that represents the state |
| features.properties.steCodeType | String | Feature location type that defines the properties.steCode and properties.name returned. Clients can login into Symmetry's Client Support Center to see the full list of possible values returned. |
| features.properties.fipsCode | String | 5-digit Federal Information Processing Standard (FIPS) code. Clients can log into Symmetry's Client Support Center to see additional details. |
Address Results Object
The Address Results object is returned for each home and work location passed into the endpoint.
| Element | Type | Description |
|---|---|---|
| addressResults | Object | Returns the original address, normalized address, and verification data |
| addressResults.inputAddress | Object | Contains street address provided to PRP API |
| addressResults.normalizedAddress | Object | The normalized address that conforms to USPS address standardization |
| address.isVerified | Boolean | Returns true when the address is successfully verified. The address must be verified before it can be geocoded. |
| address.addressResultMessages | Object | Contains normalized address status codes and geocode status codes. See addressResultMessages object. |
| address.addressErrorMessages | Object | Contains address normalization error codes. See addressErrorMessages object. |
| address.isGeocoded | Boolean | Returns true when the verified address was successfully geocoded without any errors or warnings. |
| address.latitude | Number | Latitude of normalized address |
| address.longitude | Number | Longitude of normalized address |
| address.addressTypeCode | String | Code that corresponds to an address type. Description of this value is provided in addressTypeDescription. |
| addressTypeDescription | String | Description of addressTypeCode (e.g., highrise, firm, or company, etc.) |
Address Result Message Object
The Address Result Message object contains the results of the address normalization and geocoding process.
Address Results Messages do not indicate a geocoding failure has occurred. These messages inform clients of possible changes due to the normalization process. Please refer to the Address Error Message Object for information on errors.
| Element | Type | Description |
|---|---|---|
| addressResults.addressResultMessages | Object | Returns the result message from geocoding the normalized address. Clients can read more information about this object within Symmetry's Client Support Center. |
| addressResultMessages.shortDescription | String | Short description describing the result code response (addressResultMessage) |
| addressResultMessages.longDescription | String | Explanation describing the result code response (addressResultMessage) |
Address Error Message Object
The Address Error Message object contains any applicable error codes related to the address normalization and geocoding process.
| Element | Type | Description |
|---|---|---|
| addressResults.addressErrorMessages | Object | Returns any error messages from the address normalization and geocoding process. Clients can read more information about this object within Symmetry's Client Support Center. |
| addressErrorMessages.shortDescription | String | Short description describing the error code response (addressErrorMessages) |
| addressErrorMessages.longDescription | String | Explanation describing the error code response (addressErrorMessages) |
Location Taxes Array
Returns all tax uTaxIDs applicable to the location. Refer to the Tax Results array for the details on each of the tax IDs.
Tax Results Array
The tax results array contains all applicable taxes for the locations within the tax request.
| Element | Type | Description |
|---|---|---|
| taxResults | Array | Returns all applicable taxes for the locations within the tax request |
| uniqueTaxID | String | Unique Symmetry tax code for the tax. Log into Symmetry's Client Support Center for additional information. |
| description | String | Description of the unique tax code (uniqueTaxID) |
| rate | Number | Tax rate |
| rateType | String | Describes the rate format. Log into Symmetry's Client Support Center for additional information. |
| wageBase | Number | The maximum wages that can be taxed for the given taxLimitPeriod |
| taxLimit | Number | The limit for this tax based on the rate x wageBase |
| taxLimitPeriod | String | Period in which the tax limit applies. Possible values are as follows: None, Annually, Quarterly, Monthly, and Weekly. A value of None means there’s no tax limit. |
| taxStartDate | String | Tax effective date |
| credit | Number | Tax credit |
| creditLimit | Number | Tax credit limit |
| paid | Boolean | Returns true if tax is potentially required to be withheld |
| stateWide | Boolean | Returns true if tax is a state tax (i.e., not a local tax) |
| stateCode | Number | Two-digit value that represents the state |
| stateName | String | State name that corresponds to stateCode returned |
| employerTax | Boolean | Tax imposed on employer |
| resident | Boolean | Returns true when tax belongs to home (resident) location. Returns false when tax belongs to work location. When tax belongs to both locations, returns true. |
Minimum Wage Object
The minimum wage array returns all applicable minimum wage rates for locations within the location tax request for clients who have purchased the Minimum Wage add-on for Symmetry Payroll Point.
| Element | Type | Description |
|---|---|---|
| minimumWage | Array | Returns all applicable minimum wage rates for the locations within the tax request |
| mwUid | String | Unique wage code for the minimum wage |
| state | String | State name that corresponds to stateCode returned |
| stateCode | Number | Two-digit value that represents the state |
| authorityCode | Number | Clients can log into Client Support Center for guidance on authorityCode. |
| authority | String | Name of the relevant city or local taxation authority. State and Federal return null. |
| authorityType | String | Taxing authority that defines the authorityTypeCode. Clients can log into Symmetry's Client Support Center for additional guidance. |
| authorityTypeCode | Number | One-digit value that corresponds to the taxing authority (authorityType). Clients can log into Symmetry's Client Support Center for additional guidance. |
| rate | String | Tax rate |
| effectiveDate | String | Tax effective date |
| majorType | String | Three-character code that represents wage type. Values are as follows: REG (regular), TIP (tipped), EXM (exempt) |
| industryType | String | Industry where the wages are earned. |
| industryTypeCode | Number | Three-digit value that corresponds to the industry where wages are earned (industryType) |
| minorType | String | Short description of employer and defines minorTypeCode |
| minorTypeCode | Number | Three-digit value that corresponds to the minorType value |
| details | String | Long description of minorType |
| updated | String | Timestamp when the minimum wage record was last updated. Note: this applies to any change to the record, not just rate changes. |
Response Errors
Below are examples of errors you may encounter when calling the /prp/v1/taxes endpoint.
Invalid Input Data
Below is an example of a rejected response when passing in an invalid request. To correct for this error, update the request schema to align to the sample provided above and confirm the request elements are in the proper format.
{
"timestamp": "2022-03-10T14:58:37.223+0000",
"status": 400,
"error": "Bad Request",
"message": "Invalid request input data. Check your JSON request object to ensure it conforms to the request schema.",
"path": "/prp/v1/taxes"
}
Invalid JSON Request
Below is an example of an invalid JSON requests, which produces a 500 error.
{
"timestamp": "2022-03-08T15:41:07.282+0000",
"status": 500,
"error": "Internal Server Error",
"message": "No message available",
"path": "/prp/v1/taxes"
}
Invalid Address
If an invalid address is included in the work or home address request body, a transactionError element with errorCode and errorMessage will be provided. A summary processingError element is also provided that encompasses other error conditions.
{
"result": {
"homeResults": {
"inputGeoCoordinates": {
"longitude": 0.0,
"latitude": 0.0
},
"locationTaxes": [],
"transactionError": {
"errorCode": "SLS-ERR-ADR-IID-010",
"errorMessage": "Unable to verify address."
},
"addressResults": {
"inputAddress": {
"streetAddress1": "1 Dawes Ave",
"streetAddress2": "",
"city": "Syosset",
"state": "NY",
"zipCode": "11791"
},
"isVerified": false,
"addressResultMessages": {},
"addressErrorMessages": {
"AE10": {
"shortDescription": "Premise Number Invalid",
"longDescription": "The premise (house or building) number for the address is not valid."
}
},
"isGeocoded": false,
"addressTypeCode": "S",
"addressTypeDescription": "Street"
}
},
"workResults": {
"workLocation1": {
"inputGeoCoordinates": {
"longitude": 0.0,
"latitude": 0.0
},
"locationTaxes": [],
"transactionError": {
"errorCode": "SLS-ERR-ADR-IID-010",
"errorMessage": "Unable to verify address."
},
"addressResults": {
"inputAddress": {
"streetAddress1": "1 Dawes Ave",
"streetAddress2": "",
"city": "Syosset",
"state": "NY",
"zipCode": "11791"
},
"isVerified": false,
"addressResultMessages": {},
"addressErrorMessages": {
"AE10": {
"shortDescription": "Premise Number Invalid",
"longDescription": "The premise (house or building) number for the address is not valid."
}
},
"isGeocoded": false,
"addressTypeCode": "S",
"addressTypeDescription": "Street"
}
}
},
"processingError": {
"errorCode": "PRP-ERR-BTH-IID-012",
"errorMessage": "Unable to process both home and work location input data."
}
},
"transactionDetails": {
"timestamp": "2022-03-08T15:35:08.665",
"serviceVersion": "Address Service: 0.9.1, Address Data Build: 17401 (2022-02-15). Geo Data Build: 17260 (2021-10-15). ; Location service: 0.3.2. ; Payroll Point service: 1.2.99",
"processedTransactions": 0,
"processingTime": 0.157000000
}
}
Geocoordinates are Outside U.S.
If coordinates (latitude/longitude) are provided that are outside the US, the following transaction error is provided:
{
"result": {
"homeResults": {
"inputGeoCoordinates": {
"longitude": 0.0,
"latitude": 0.0
},
"locationTaxes": [],
"transactionError": {
"errorCode": "SLS-ERR-GCO-IID-012",
"errorMessage": "Coordinates are outside of USA."
}
},
"workResults": {
"workLocation1": {
"inputGeoCoordinates": {
"longitude": 0.0,
"latitude": 0.0
},
"locationTaxes": [],
"transactionError": {
"errorCode": "SLS-ERR-GCO-IID-012",
"errorMessage": "Coordinates are outside of USA."
}
}
},
"processingError": {
"errorCode": "PRP-ERR-BTH-IID-012",
"errorMessage": "Unable to process both home and work location input data."
}
},
"transactionDetails": {
"timestamp": "2022-03-08T15:48:19.636",
"serviceVersion": "Location service: 0.3.2. ; Payroll Point service: 1.2.99",
"processedTransactions": 0,
"processingTime": 0.022000000
}
}
Updated 2 months ago
