Consent Method POST

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. Once you are registered with TaxStatus, you will receive this text and how to use it during the on-boarding process.

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.


Request Path

Submit all consent requests to the following path.

Path

You will obtain the API endpoint after you register on your account page.


Headers

Each request must an Oauth2 tokan and your company Id, assigned by TaxStatus, in the header.

Authorization
euid

Query String Parameters

Query string parameters are not supported on this method.


/Consent Request application/json

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.

Below is the IRS approved language you need to provide to the customer and have them accept that they have read and understand the text. You need to log in to see this language. You will replace [ENTERPRISE] with your company name.

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
  • fIrstName* First name of taxpayer or business director
  • lastName* Last name of taxpayer or business director
  • title (For businesses only) Title of director authorized to provide consent.
  • 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
  • email* Email address for individual or appropriate party if a business
  • 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,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", "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": "1040", "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", "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" }

Response Body application/json

The reponse codes for the consent call are standard HTML response codes. The response body will be empty.

Response Codes

HTTP Status Code Description Explanation
200 Accepted/OK The request has been accepted with no issues
400 Bad Request You are missing some required fields or the Json in the body is missing or malformed
403 Forbidden You do not have authorization to make this call. Possibly your comapany Id is invalid or you are calling on behalf of a company with which you dont have authority.