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 verify 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.

Here 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
  • coveragePast The amount of time, in years, to go back into the taxpayers past.
  • coverageForward The amount of time, in years, to ask the consent to remain in the future. Maximun and default is 3.
  • 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. 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
  • transcripts* An array indicationg which transcripts need to be ordered
    • expedite* Flag indicating if the request needs to be expedited
    • 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
  • wetSignature Base-64 string of the form where a wet signature was aquired

Example: Individual consent captured

{ "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", "coveragePast":"10", "coverageForward":"2", "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", "transcripts": [{ "expedite": false, "transcriptForm": "1040", "transcriptType": "RETR", "transcriptPeriod": ["202012", "201912", "201812"] }, { "expedite": false, "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": "2", "eSignIp": "64.123.87.103", "eSignDate": "10-23-2020 13:45:12", "eSignUa": "mozilla-char-chorme v7.90e", "eSignUrl": "https://thesitewhereconsentwasgiven.com", "transcripts": [{ "expedite":true, "transcriptForm": "1120", "transcriptType": "RETR", "transcriptPeriod": ["202012", "201912", "201812"] }, { "expedite": false, "transcriptForm": "940", "transcriptType": "RETR", "transcriptPeriod": ["202012", "201912", "201812"] } ]}

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.
409 Conflict If any ordered transcripts are set as expedited, then a wet signature is required. In this case, one or more transcripts are set as expedited, but the wetSignature probably is empty.