The CONSENT method is used to provide consent from the taxpayer. Your company will need to collect this information from the taxpayer. You will need to provide specific
text to the taxpayer to accept, before you call the CONSENT method.
During your consent process, you will need to show your customer IRS approved language for them to accept. At the time of acceptance, you will need to
collect the IP addrss of the customer, their user agent, date and time stamp of when they checked the checkbox, and the URL where they viewed the consent languaage.
If you choose to use Consent to keep the entire process in your flow, you will need to have an iFrame from TaxStatus to show the IRS approved language you must provide taxpayer
to be compliant with the IRS. You can view a sample consent language here. Since this language can change from time to time,
TaxStatus will maintain the text and host it so your iFrame can retrieve it. This text can have business rules around it so you can add language specific to your company
and offering.
Here is a breif descriptiong of how it works:
/Consent Request
application/json
Your organization can simply post all the captured consent details to the CONSENT method, so no additional contact with the customer is necessary. This will also speed up the process to obtain tax data.
Request Body
Below are the attributes for the Consent method.
Attributes
-
companyId*
The company Id of the company this call is on behalf of. If the call is not on behalf of another company, then the registered company Id
TaxStatus assigned during the registration process (used in the euid field in the header.
-
tin*
9-digit tax id (no spaces or hypens) of the individual or company
-
isCompany*
Zero (0) if tin is an SSN or one (1) if tin is an EIN
-
businessName
(For businesses only) Name of business. Required if business
-
title
(For businesses only) Title of director authorized to provide consent.
-
fIrstName*
First name of taxpayer or business director
-
lastName*
Last name of taxpayer or business director. Required if business.
-
street*
Street address of business or personal residence
-
city*
City for business or personal residence
-
state*
2-Digit state abbreviation for business or personal residence
-
zip*
5-Digit zip code for business or personal residence
-
country
Country code if taxpayer does not live in the US
-
province
Provice code if taxpayer does not live in the US
-
mobile*
Mobile phone for individual or appropriate party if a business. If mobile number is not available, you may provide a landline or work number.
-
email*
Email address for individual or appropriate party if a business
-
dob
Taxpayer's date of birth
-
loanNumber
The loan number for which this taxpayer is applying, if applicable
-
coveragePast
The amount of time, in years, to go back into the taxpayers past. If zero or not included, a 4506c form will be sent to the IRS.
-
coverageForward
The amount of time, in years, to ask the consent to remain in the future. Maximun is 3. If zero or not included, a 4506c form will be sent to the IRS.
-
callback
Webhook that, if provided, will be used to callback company once taxpayer is in the system. The JSON sent will be the same as the Individual or Business calls, whichever is appropriate. Unless transcript information was provided. In that case, the transcripts (see Transcript call) will be sent in the callback.
See the Walkthrough page, when authenticated, to test your callback URL. Note: The callback will only POST to an HTTPS endpoint. If the callback is
to an HTTP endpoint the callback will redirect to HTTPS.
-
eSignIp*
IP address of the individual providing consent
-
eSignDate*
Date and time the consent was captured
-
eSignUa*
The User Agent of the browser at the time the consent was given
-
eSignUrl*
The URL of the web site where consent was given
-
needPDF
If provided, along with a callback endpoint and transcript information, a boolean as to whether the transcripts, sent in the callback, need to be PDF instead of the standard HTML.
-
transcripts
An optional array indicationg which transcripts need to be ordered, if known. Otherwise do not include transcripts section.
-
transcriptType*
One of the transcript types (ACTR, WAID, RECA, RETR)
-
transcriptForm*
The form type to be ordered (1040,940,941,INCOME,etc.)
-
transcriptPeriod*
The tax year and month concatinated together i.e. - 201812
Example: Individual consent call
{
"companyId": "enco45100",
"tin": "222222222",
"isCompany": 0,
"businessName": "",
"firstName": "Sammy",
"lastName": "Smith",
"title": "",
"street": "9877 W. Maple St.",
"city": "Houston",
"state": "TX",
"zip": "10234",
"mobile": "2185555555",
"email":"sammy@gmail.com",
"dob":"03/15/1991",
"loanNumber": "2345-JUYHT",
"coveragePast":10,
"coverageForward":3,
"callback" : "https://anywhere.com/mycallback",
"eSignIp": "64.123.12.56",
"eSignDate": "06-23-2021 10:15:12",
"eSignUa": "mozilla-char-chorme v7.90e",
"eSignUrl": "https://companysitethatcollectedconsent.com",
"needPDF": false,
"transcripts": [{
"transcriptForm": "1040",
"transcriptType": "RETR",
"transcriptPeriod": ["202012", "201912", "201812"]
},
{
"transcriptForm": "INCOME",
"transcriptType": "WAID",
"transcriptPeriod": ["202012", "201912", "201812"]
}
]}
Example: Business consent call
{
"companyId": "enco45100",
"tin": "555555555",
"isCompany": 1,
"businessName": "ACME Inc.",
"firstName": "Jane",
"lastName": "Doe",
"title": "CEO",
"street": "123 Elm St",
"city": "Los Angeles",
"state": "CA",
"zip": "90049",
"mobile": "3105555555",
"email": "jane.doe@acme.com",
"coveragePast": 10,
"coverageForward": 3,
"eSignIp": "64.123.87.103",
"eSignDate": "10-23-2020 13:45:12",
"eSignUa": "mozilla-char-chorme v7.90e",
"eSignUrl": "https://thesitewhereconsentwasgiven.com",
"needPDF": true,
"transcripts": [{
"transcriptForm": "1120",
"transcriptType": "RETR",
"transcriptPeriod": ["202012", "201912", "201812"]
},
{
"transcriptForm": "940",
"transcriptType": "RETR",
"transcriptPeriod": ["202012", "201912", "201812"]
}
]}
Example: Individual consent without transcripts section
{
"companyId": "enco45100",
"tin": "222222222",
"isCompany": 0,
"businessName": "",
"firstName": "Sammy",
"lastName": "Smith",
"title": "",
"street": "9877 W. Maple St.",
"city": "Houston",
"state": "TX",
"zip": "10234",
"mobile": "2185555555",
"email":"sammy@gmail.com",
"dob":"03/15/1991",
"loanNumber": "2345-JUYHT",
"coveragePast":10,
"coverageForward":3,
"callback" : "https://anywhere.com/mycallback",
"eSignIp": "64.123.12.56",
"eSignDate": "06-23-2021 10:15:12",
"eSignUa": "mozilla-char-chorme v7.90e",
"eSignUrl": "https://companysitethatcollectedconsent.com"
}