TAXPAYERS Method POST

The TAXPAYERS method is used to retrieve consent from the taxpayer to view their tax data. It is desinged to keep the taxpayer in your flow. You collect the dinformation below, from the individual or business signer, and POST it to this method. The response will contain a link that you can eiter iFrame or redirect to which will be the TaxStatus consent wizard. Any data needed you did not collect will be asked for in the wizard. if you have already collected all the data the IRS needs to greant consent, then the taxpayer will go straght to viewing the IRS language (requeired), agree to it, and digitally sign. The wizard can accomadate individuals and buainesses.

To get an idea of how it looks, you can visit our demo here. If you shrink it down to iFrame size, you can see how it changes for your iFrame. This consent wizard can be branded to your company colors and logo.

Here is a breif descriptiong of how it works:

  • Your onboarding flow will gather the necessary info from the taxpayer (name, address, TIN, etc.).
  • You then POST this information to this method.
  • The response will have the URL(s) you will need to send, redirect to, or iFrame in, however you wish to design it. See details of this response belwo.
  • Taxpayer will see the TaxStatus wizard, braned to your needs, which will help them complete the consent process.
  • Once taxpayer signs, the wizard can redirect back to and endpoint provied by you in the onbaardeing process.

Note: TaxStatus will work with you to make sure you are up and running quickly. You will be provided with a sub domain and all keys needed for this process.

Finally, if you don't wish to have an iFrame or a flow inside your application, check out the Request method. This method allows you have TaxStatus gather consent from the taxpayer.

Request Path

Submit all taxpayers 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.

/Taxpayers Request application/json

Your organization can simply post all the captured consent details to the TAXPAYERS method, to allow TaxStatus to gain consent on your behave, and get authorization from the IRS. This will also speed up the process to obtain tax data.

Request Body

Below are the attributes for the Taxpayers 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.
  • userId Unique identifier (email) of the user that is initiating this request
  • groupId Unique identifier used to group together individuals and buainesses as one transaction over multiple API calls. So if you make a call with and individual and another with the same individual but also a business they need to sign for, use this field and send the same value for both calls. We will thne only have the taxpayer go through one signing event for both themselves and any business they are singing for
  • 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.
  • onSuccess A URL that, if provided, the consent wizard with redirect back to this on completion of signing
  • caseManagement Object used to represent a loan case if needed. You will be able to see these cases set up on the TaxStatus UI.
    • caseURL URL back to you application to tie this case in the TaxStatus application back to your application
    • caseName The name of the loan case
    • caseNumber The unique number for this case
    • caseAssignment Value indicating who is assigned to this case
  • participants This section will contain all the participants for this signing
    • individuals An array of individuals that participate in this transaction, eiter signing or not
      • consentExperienceURL If branding has been set up in TaxStatus for unique consent experiences, then the URL provieded by TaxSatus
      • ssn 9-digit tax id (no spaces or hypens) of the individual (SSN). Required if you wish to retrieve tax records of this individual
      • itin 9-digit tax id (no spaces or hypens) of the individual
      • clientTaxpayerId Unique identifier, greater than 9 characters, that will identify the taxpayer in future calls, instead of using the TIN (SSN). Use this in place of TIN in other calls after getting consent. If using this, LAST4 in any responese will have this value instead of the last 4 of the TIN
      • fIrstName* First name of taxpayer or business director
      • middleName Middle name of taxpayer
      • lastName* Last name of taxpayer or business director. Required if business.
      • requestViaEmail Boolean indicating if collecting tax data for this individual, TaxStatus should send an email to have them sign in the consent process
      • requestViaSMS Boolean indicating if collecting tax data for this individual, TaxStatus should send an SMS text to have them sign in the consent process
      • mobile* Mobile phone for individual. This field is required if collectTaxRecords or RequestViaSMS is true
      • email* Email address for individual or appropriate party if siging for a business. Required if RequestViaEmail is true above
      • caseRole Role of individual, Signer, Guarantor, etc.
      • collectTaxRecords Boolean indicating if TaxStatus needs to collect tax recoreds for this individual
      • kyc Boolean indicating if TaxStatus needs to perform Know Your Customer (KYC) actions to identfy this individual. This process will match a photo Id to a selfie of the individual.
      • address* This section holds the address information of the individual. This section is required if the collectTaxRecords flag is set.
        • addressType Indicate whether this is a domestic or international address. If missing, domestic is assumed.
        • street* Street address personal residence
        • city* City for ersonal residence
        • state* 2-Digit state abbreviation for personal residence
        • zip* 5-Digit zip code for personal residence
        • country Country code if taxpayer does not live in the US
        • province Provice code if taxpayer does not live in the US
      • businesses An array that holds this individuals businesses that they are signing for or have some involvement
        • ein* 9-digit tax id (no spaces or hypens) of the business (EIN).
        • clientTaxpayerId Unique identifier, greater than 9 characters, that will identify the taxpayer in future calls, instead of using the TIN (EIN). Use this in place of TIN in other calls after getting consent. If using this, LAST4 in responese will have this value instead of the last 4 of the TIN
        • businessName* Name of business.
        • title* Title of person authorized to provide consent for this business
        • phone* 10-digit (no parenthesis or dashes) phone number of the business. This field is required if collectTaxRecords is true
        • fiscal Numeric, the fiscal year end month of the business
        • caseRole Role of individual, Signer, Guarantor, Borrower, etc.
        • collectTaxRecords Boolean indicating if TaxStatus needs to collect tax recoreds for this business
        • kyb Boolean indicating if TaxStatus needs to perform Know Your Business (KYB) actions to identfy this individual
        • address* This section holds the address information of the business. This section is required if the collectTaxRecords flag is set.
          • addressType Indicate whether this is a domestic or international address. If missing, domestic is assumed.
          • street* Street address of the business
          • city* City of the business
          • state* 2-Digit state abbreviation of the business
          • zip* 5-Digit zip code of the business
          • country Country code if the business is not located in the US
          • province Provice code if the business does not reside in the US

    If you are getting consent from a business you will need to get the official title of the taxpayer signing for the business. Here a list of the IRS accepted titles based on the company type or forms they file (Title is on the right side of the dash):

    • Form 1065 - Partner
    • Form 1065 - Limited Partner
    • Form 990 - Director
    • Corp/S-Corp/LLC - Chief Accounting Officer
    • Corp/S-Corp/LLC - Chief Executive Officer
    • Corp/S-Corp/LLC - Chief Operations Officer
    • Corp/S-Corp/LLC - Chief Financial Officer
    • Corp/S-Corp/LLC - President
    • Corp/S-Corp/LLC - Vice President
    • Corp/S-Corp/LLC - Treasurer
    • Corp/S-Corp/LLC - Assistant Treasurer
    • Corp/S-Corp/LLC - 1% Shareholder
    • Corp/S-Corp/LLC - Shareholder
    • Corp/S-Corp/LLC - Controller
    • Corp/S-Corp/LLC - Managing Member
    • Sole Proprietor - Owner
    • Sole Proprietor - Sole Proprietor
    • Trust - Executor
    • Trust - Beneficiary
    • Trust - Trustee
    • Trust - Administrator

    The following are examples of what thess call may look like.

    Example: Taxpayers call with two taxpayers, one with two businesses. the other individual is a guarantor

    { "companyId": "enco45100", "userId": "user@yourcompany.com", "groupId": "Xuey45R3M", "callback":"https://anywhere.com/tax", "onSuccess":"https://anywhere.com/yourthankyoupage", "caseManagement": { "caseURL": "https://yourcompany.com/id=Xuey45R3M", "caseName": "XA1 Loan", "caseNumber": "XA1-0071", "caseAssignment": "Johnson" }, "participants": { "individuals": [ { "consentExperienceURL": "https://test.app.tax/brand", "ssn": "222222222", "clientTaxpayerId":"ertdauyy7654fasd", "firstName": "Sammy", "middleName": "", "lastName": "Smith", "email": "sam@someplace.com", "mobile": "5553105555", "caseRole": "Signer", "collectTaxRecords": true, "kyc": true, "requestViaEmail": true, "requestViaSMS": true, "address": { "addressType": "domestic", "street": "123 Ramblin St", "city": "Miami", "state": "FL", "zip": "30214", "province": "", "country": "US" }, "businesses": [ { "ein": "555555555", "clientTaxpayerId":"fghrt543RDS2347", "businessName": "Acme Inc", "phone": "5554441201", "title": "Chief Operations Officer", "fiscal": 5, "caseRole": "Borrower", "kyb": true, "collectTaxRecords": true, "address": { "addressType": "domestic", "street": "7865 S Holden Ave", "city": "Ackrin", "state": "OH", "zip": "65894", "province": "", "country": "US" } }, { "ein": "886666666", "clientTaxpayerId":"fghrt0945RF34", "businessName": "We Groom Dogs", "phone": "5552221024", "title": "Treasurer", "fiscal": 12, "caseRole": "Signer", "kyb": true, "collectTaxRecords": true, "address": { "addressType": "domestic", "street": "45 NE First St", "city": "123 E Main ST", "state": "FL", "zip": "30258", "province": "", "country": "US" } }] }, { "consentExperienceURL": "", "ssn": "555221111", "clientTaxpayerId":"lkiujh67543ESX435", "firstName": "Herman", "middleName": "", "lastName": "Fluering", "email": "herman@someplace.com", "mobile": "5554444444", "caseRole": "Guarantor", "collectTaxRecords": true, "kyc": true, "requestViaEmail": true, "requestViaSMS": true, "address": { "addressType": "domestic", "street": "564 Robinson St", "city": "Miami", "state": "FL", "zip": "30214", "province": "", "country": "US" } }] } }

    Example: Taxpayers call with an ivdividaul singing for a buainess

    { "companyId": "enco45100", "groupId": "Xuey45R3M", "callback":"https://anywhere.com/tax", "participants": { "individuals": [ { "consentExperienceURL": "https://test.app.tax/brand", "ssn": "222222222", "firstName": "Sammy", "middleName": "", "lastName": "Smith", "email": "sam@someplace.com", "mobile": "5553105555", "caseRole": "Signer", "collectTaxRecords": true, "kyc": true, "requestViaEmail": true, "requestViaSMS": true, "address": { "addressType": "domestic", "street": "123 Ramblin St", "city": "Miami", "state": "FL", "zip": "30214", "province": "", "country": "US" }, "businesses": [ { "ein": "555555555", "businessName": "Acme Inc", "phone": "5554441201", "title": "Chief Operations Officer", "fiscal": 5, "caseRole": "Borrower", "kyb": true, "collectTaxRecords": true, "address": { "addressType": "domestic", "street": "7865 S Holden Ave", "city": "Ackrin", "state": "OH", "zip": "65894", "province": "", "country": "US" } }] }] } }

    Example: Taxpayers call individual only

    { "companyId": "enco45100", "groupId": "Xuey45R3M", "callback":"https://anywhere.com/tax", "participants": { "individuals": [ { "consentExperienceURL": "", "ssn": "222222222", "firstName": "Sammy", "middleName": "", "lastName": "Smith", "email": "sam@someplace.com", "mobile": "5553105555", "caseRole": "Signer", "collectTaxRecords": true, "kyc": true, "requestViaEmail": true, "requestViaSMS": true, "address": { "addressType": "domestic", "street": "123 Ramblin St", "city": "Miami", "state": "FL", "zip": "30214", "province": "", "country": "US" } }] } }

    Response Body application/json

    Attributes

    • CaseLink If you are also using the TaxStatus application, this is a deep link to the case that was set up above
    • ConsetLinks An array of taxpayers from the request above.
      • Last4 The 4 digits of the individual's Taxpayer Identification Number (TIN) if provied
      • FirstName The first name of the individual from the reqeust above
      • LastName The last name of he individual from the request above
      • ConsentLink The URL the individual can be redirected to, in an iFrame or new tab, or sent in an email/SMS message which will navigate to the start of their signing experience. In test mode, the consent wizard is not hooked up to any data submitted. It is only to allow you to get an idea of what the signing experience is like. In production, this can be branded to your needs.

    Example response body for the taxpayers method with a single individual

    { "CaseLink" : "https://app.taxstatus.net/case.aspx?cid=zvx9vnl1e0ba", "ConsentLinks": [ { "Last4": "2222", "FirstName":"Sammy",' "LastName":"Smith", "ConsentLink":"https://test.app.tax?req=OPjuy65Tf4" } ] }

    Example response body for the taxpayers method with more than one individual.

    { "CaseLink" : "https://app.taxstatus.net/case.aspx?cid=zvx9vnl1e0ba", "ConsentLinks": [ { "Last4": "2222", "FirstName":"Sammy",' "LastName":"Smith", "ConsentLink":"https://test.app.tax?req=OPjuy65Tf4" }, { "Last4": "3333", "FirstName":"Linda",' "LastName":"Jones", "ConsentLink":"https://test.app.tax?req=kJer43FTf4" } ] }

    Example response body for the taxpayers method if using ClientTaxpayerId instead of TIN

    { "CaseLink" : "https://app.taxstatus.net/case.aspx?cid=zvx9vnl1e0ba", "ConsentLinks": [ { "Last4": "9888aaf7ee5049b0b786", "FirstName":"Sammy",' "LastName":"Smith", "ConsentLink":"https://test.app.tax?req=OPjuy65Tf4" } ] }

    The reponse codes for the laststatus call are standard HTML response codes.

    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.