TaxBandits API

# FormW9

If you are making payments to anyone other than the employees on your payroll, you will need to file a Form 1099 for this individual. The Form 1099 you must file will vary depending on the type of payments you make. For example, if you are paying an independent contractor for their services, you should file Form 1099-NEC.

Regardless of which Form 1099 you are required to file, as a payer you must collect a Form W-9 (Request for Taxpayer Identification Number and Certification) from your payee before reporting these payments to the IRS.

TIN Matching

You can choose TIN Matching service when requesting a Form W-9 from the recipient. Once the recipient completed the Form W-9, TaxBandits will validate the Recipient Name and TIN given in the Form W-9 against the IRS records.

If the Recipient Name and TIN combination does not match with the IRS records, you can request a new Form W-9 from the recipient.

Note: TIN Matching prevents you from entering the wrong TINs on the 1099s. Therefore, it will help you avoid hefty penalties and expenses from filing invalid 1099 Forms.

The TaxBandits application and API is equipped to handle the many situations you may face when working with individuals and vendors outside your organization. Let’s discuss the complete solution that TaxBandits offers for requesting, presenting, and acquiring a signed W-9 from your recipients.

  • Request a W-9 URL to be Embedded in your Website or Native App

TaxBandits will supply the W9 URL uniquely for each request, this URL can then be embedded into your web page or native app.

The RequestByURL endpoint is used to get the URL. This request takes in a unique Payee Reference for the recipient such as vendor id, contractor number or a random number or even an email address (This will be used to identify the recipient for future references) along with the BusinessId (or Business TIN)

Refer to the Business endpoint to learn more about creating a business and retrieving the BusinessID in TaxBandits.

You can customize the logo, callback redirection URLs in the request.

If the TIN Matching service is set ‘TRUE’ in the request. TaxBandits will validate the recipient name and TIN given by the recipient against the IRS database.

  • Request W-9 by Email

You can request the Form W-9 from your recipients using the RequestByEmail endpoint This API accepts the Name, Payee Reference (optional, such as vendor id or contractor number) and Email Address of the recipients. After initial validation, the backend process generates a unique link for each recipient and sends emails to each of the recipients. This email contains a link to complete their W-9 in a customizable secured portal.

In both cases described above, once the recipient completes and signs the Form W-9, you will be notified via Webhook. The Webhook payload will have the W-9 recipient data such as the Name, Address and EIN/SSN along with the link to download the completed Form W-9.

Refer Form W-9 webhook to find out more about the webhook set up and sample payload.

In addition to the WebHook, the list of recipients and W9s will also be available in TaxBandits application for future use as well.

Note: If the TIN Matching service is set ‘TRUE’ in the request. TaxBandits will validate the recipient name, TIN and TINType given by the recipient against the IRS database.

# Delete

This method can be used to delete a particular W-9s request or a submission. If there are multiple W-9 requested in a submission, all the W-9 records under the submission will be deleted.

DELETE FormW9/Delete
1

Request Body

Field Type Description
SubmissionId Guid Unique Identifier for a Submission.
PayeeRef String Unique identifier of a recipient.
Either PayeeRef or Email is required
Size Range: 1-50
Email String Email Address of the recipient.
Size Range: 1-50

Response Body

Field Type Description
FormW9Records Object Details of the W-9s requested for delete
    SubmissionId Guid Unique identifier of a submission
    PayeeRef String Unique identifier of the recipient
    Email String Email Address of the recipient.
    W9Status String Status of the W-9
    StatusTs String Timestamp of the W-9 Status
Errors Object Shows detailed error information.

Scenario 1 : Delete a recipient with SubmissionId

FormW9/Delete?SubmissionId=019c8aec-41fe-4b80-883a-441665dc004a
1

Sample Response 1

{
 "FormW9Records": [
   {
     "SubmissionId": "019c8aec-41fe-4b80-883a-441665dc004a",
     "PayeeRef": "Pe123451234",
     "Email": "steve@abcinc.com",
     "W9Status": "DELETED",
     "StatusTs": "2021-02-22 04:24:09 -05:00"
   }
 ],
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12

Scenario 2: Delete a recipient with PayeeRef

FormW9/Delete?PayeeRef=Pe123451234
1

Sample Response 2

{
   "FormW9Records": [
       {
           "SubmissionId": "58c06235-d278-4d4e-9f0e-cca9d21f38df",
           "PayeeRef": "Pe123451234",
           "Email": "steve@abcinc.com",
           "W9Status": "DELETED",
           "StatusTs": "2021-04-09 13:48:30 -04:00"
       },
       {
           "SubmissionId": "af0835ad-b26c-4a94-8d56-6e8f4cd36cb1",
           "PayeeRef": "Pe123451234",
           "Email": "steve@abcinc.com",
           "W9Status": "DELETED",
           "StatusTs": "2021-04-09 13:48:30 -04:00"
       }
   ],
   "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Scenario 3: Delete a recipient with Email

FormW9/Delete?Email=steve@abcinc.com
1

Sample Response 3

{
 "FormW9Records": [
   {
     "SubmissionId": "019c8aec-41fe-4b80-883a-441665dc004a",
     "PayeeRef": "Pe123451234",
     "Email": "steve@abcinc.com",
     "W9Status": "DELETED",
     "StatusTs": "2021-02-22 04:24:09 -05:00"
   }
 ],
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12

Scenario 4: Delete a recipient with SubmissionId [Invalid]

FormW9/Delete?SubmissionId=019c8aec-41fe-4b80-883a-441665dc0033&Email=steve@abcinc.com
1

Sample Response 4 : Since the Requester information was not given, the system will look up for W-9s under default business and return the result.

{
   "FormW9Records": null,
   "Errors": [
       {
           "Id": "F00-100146",
           "Name": "Submission Id",
           "Message": "Submission Id is invalid"
       }
   ]
}
1
2
3
4
5
6
7
8
9
10

# Get

This method will return the completed W-9 of a particular recipient. The response will have the W-9 information such as the Name, Address and EIN/SSN along with the link to download the completed Form W-9.

Key Points

  • Only W-9s with the ‘completed’ and ‘completed and TIN matching Inprogress’ status can be retrieved using the Get method. If the status of the W-9 is other than ‘completed’ and ‘completed and TIN matching Inprogress’, it will not be returned.
  • If you do not supply the BusinessId in the request, then the W-9 that matches the Email or PayeeRef linked to the default business will be retrieved.
  • If there are multiple W-9s for the same Email or PayeeRef, the last completed W-9 will be retrieved.

GET FormW9/Get
1

Request Body

Field Type Description
PayeeRef String Unique identifier of a recipient. Either PayeeRef or Email is required
Size Range: 1-50
Email String Email Address of the recipient.
Size Range: 1-50
BusinessId Guid Optional Unique Business Identifier. If you do not supply the BusinessId in the request, the BusinessId of the default business will be mapped.
TIN String Optional Taxpayer Identification Number. Use this as an alternate for BusinessId. Values: EIN, SSN
Size Range: 9-11

Response Body

Field Type Description
SubmissionId Guid Unique identifier of a submission.
Requester Object Requester information.
    BusinessId Guid A unique identifier of the business.
    BusinessNm String Requester Name. If the requester is a Business, then the Business Name will be returned. If the requester is an Individual, then the Payer’s full name will be returned.
    TINType String TIN Type of the Requester.
    TIN String Taxpayer Identification Number of the requester.
PayeeRef String Unique identifier of the recipient
RecipientId Guid An unique ID generated by TaxBandits after the return is created and will be returned in the Response. You can use this id for your future reference to update.
W9Status String Status of the W-9
StatusTs String Timestamp of the W-9 Status
TINMatching Object TIN Matching information.
    Status String TIN Matching status.
    StatusTs String Timestamp of the TIN Matching Status.
    Errors String Shows the detailed error message.
FormW9RequestType String Form W-9 requested Type. URL_API - Form W-9 was requested using the API method RequestByURL. Email_API - Form W-9 was requested using the API method RequestByEmail. Email_UI - Form W-9 was requested from the TaxBandits UI application.
PdfUrl String URL to download the completed W-9
Email String Email Address of the recipient. This is the email to which the W-9 request was sent. The value will be null if the Form W-9 was requested using the API method RequestByURL
FormData Object Form W-9 data of the recipient
    Line1Nm string Name as shown on the income tax return
    Line2Nm string Business name/disregarded entity name, if different from Line1 Name
    TINType string TIN type of the recipient. Either EIN or SSN
    TIN string Recipient’s TIN
    Address Object Recipient’s complete address
        Address1 string Recipient’s Address 1 (number, street)
        Address2 string Recipient’s Address 2 (apt. or suite no.)
        City string Recipient’s City
        State string Recipient’s State
        ZipCd string Recipient’s Zip Code
    FederalTaxClassification string U.S. Federal Tax Classification of the person whose name is entered on Line 1
    ExemptPayeeCd string This code identifies the recipient is exempt from backup withholding
    ExemptFromFATCA string This code identifies recipients that are exempt from reporting under FATCA.

Sample Request 1 : Get W-9 data of a recipient with PayeeRef and BusinessId

FormW9/Get?PayeeRef=Pe123451234&BusinessId=7B82B242-1223-4029-9251-C0446298F620
1

Sample Response 1

{
 "SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
 "StatusTs": "2021-02-19 14:36:28 -05:00",
 "TINMatching": {
   "Status": "ORDER_CREATED",
   "StatusTs": "2021-06-10 07:16:01 -04:00",
   "Errors": null
 },
 "FormW9RequestType": "URL_API",
 "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
 "Email": "steve@abcinc.com",
 "FormData": {
   "Line1Nm": "ABC Inc",
   "Line2Nm": null,
   "TINType": "EIN",
   "TIN": "11-1111111",
   "Address": {
     "Address1": "123 E. Main St",
     "Address2": "Suite 400",
     "City": "Rock Hill",
     "State": "SC",
     "ZipCd": "29730"
   },
   "FederalTaxClassification": "C Corporation",
   "ExemptPayeeCd": "5",
   "ExemptFromFATCA": "E"
 },
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

Sample Request 2 : Get W-9 data of a recipient with Email and BusinessId.

FormW9/Get?Email=steve@abcinc.com&BusinessId=7B82B242-1223-4029-9251-C0446298F620
1

Sample Response 2

{
 "SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "W9Status": "COMPLETED",
 "StatusTs": "2021-02-19 14:36:28 -05:00",
 "TINMatching": null,
 "FormW9RequestType": "URL_API",
 "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
 "Email": "steve@abcinc.com",
 "FormData": {
   "Line1Nm": "ABC Inc",
   "Line2Nm": null,
   "TINType": "EIN",
   "TIN": "11-1111111",
   "Address": {
     "Address1": "123 E. Main St",
     "Address2": "Suite 400",
     "City": "Rock Hill",
     "State": "SC",
     "ZipCd": "29730"
   },
   "FederalTaxClassification": "C Corporation",
   "ExemptPayeeCd": "5",
   "ExemptFromFATCA": "E"
 },
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

Sample Request 3 : Get W-9 data of a recipient with PayeeRef and TIN.

FormW9/Get?PayeeRef=Pe123451234&TIN=22-2222222
1

Sample Response 3

{
 "SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
 "StatusTs": "2021-02-19 14:36:28 -05:00",
 "TINMatching": {
   "Status": "ORDER_CREATED",
   "StatusTs": "2021-06-10 07:16:01 -04:00",
   "Errors": null
 },
 "FormW9RequestType": "URL_API",
 "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
 "Email": "steve@abcinc.com",
 "FormData": {
   "Line1Nm": "ABC Inc",
   "Line2Nm": null,
   "TINType": "EIN",
   "TIN": "11-1111111",
   "Address": {
     "Address1": "123 E. Main St",
     "Address2": "Suite 400",
     "City": "Rock Hill",
     "State": "SC",
     "ZipCd": "29730"
   },
   "FederalTaxClassification": "C Corporation",
   "ExemptPayeeCd": "5",
   "ExemptFromFATCA": "E"
 },
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

Sample Request 4 : Get W-9 data of a recipient with PayeeRef.

FormW9/Get?PayeeRef=Pe123451234
1

Sample Response 4

{
 "SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
 "StatusTs": "2021-02-19 14:36:28 -05:00",
 "TINMatching": {
   "Status": "ORDER_CREATED",
   "StatusTs": "2021-06-10 07:16:01 -04:00",
   "Errors": null
 },
 "FormW9RequestType": "URL_API",
 "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
 "Email": "steve@abcinc.com",
 "FormData": {
   "Line1Nm": "ABC Inc",
   "Line2Nm": null,
   "TINType": "EIN",
   "TIN": "11-1111111",
   "Address": {
     "Address1": "123 E. Main St",
     "Address2": "Suite 400",
     "City": "Rock Hill",
     "State": "SC",
     "ZipCd": "29730"
   },
   "FederalTaxClassification": "C Corporation",
   "ExemptPayeeCd": "5",
   "ExemptFromFATCA": "E"
 },
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

Sample Request 5 : Get W-9 data of a recipient with PayeeRef [Which is not completed].

FormW9/Get?PayeeRef=Pe123451234
1

Sample Response 5

{
 "SubmissionId": "00000000-0000-0000-0000-000000000000",
 "Requester": null,
 "PayeeRef": null,
 "W9Status": null,
 "StatusTs": null,
 "TINMatching": null,
 "FormW9RequestType": null,
 "PdfUrl": null,
 "Email": null,
 "FormData": null,
 "Errors": [
   {
     "Id": "F08-100014",
     "Name": "No Records",
     "Message": "No completed W-9s were found for the given Request"
   }
 ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# List

Use this method to list the W-9s under a particular business. The W-9s can be filtered based on the W-9 Status and Date Range.

GET FormW9/List
1

Request Body

Field Type Description
BusinessId Guid Optional Unique identifier of a business. If you do not supply the BusinessId in the request, the BusinessId of the default business will be mapped.
TIN String Optional TIN of the business. If you do not have the BusinessId, you can use the TIN to refer the business
Size Range: 9-11
W9Status String Optional Status of the W-9
Allowed values: "Sent", "Order_Created", "Scheduled", "URL_Generated", "Opened", "Completed", "Completed_and_TINMatching_Inprogress", "Invalid", "Delivered", "Bounced", "ALL"
Page int Optional Page number that needs to be listed in the Response. If the value is not given, then the page will be defaulted to 1.
PageSize int Optional Number of W-9 records to be listed in each page. If the value is not given, then the page size will be defaulted to 100.
FromDate String Optional List the W-9 records between the date range.
ToDate String Optional List the W-9 records between the date range.

Response Body

Field Type Description
Requester Object Requester information.
    BusinessId Guid A unique identifier of the business.
    BusinessNm String Requester Name. If the requester is a Business, then the Business Name will be returned. If the requester is an Individual, then the Payer’s full name will be returned.
    TINType String TIN Type of the Requester.
    TIN String Taxpayer Identification Number of the requester.
FormW9Records Object List of W-9 Records
    SubmissionId Guid Submission ID of the original W-9 Request
    PayeeRef String Unique identifier of the recipient
    Line1Nm String Recipient Name as given on the Form W-9 Line 1.
    W9Status String Status of the W-9
    StatusTs String Timestamp of the W-9 Status.
    TINMatching Object TIN Matching information.
        Status String TIN Matching status.
        StatusTs String Timestamp of the TIN Matching Status.
        Errors String Shows the detailed error message.
    PdfUrl String URL to download the completed W-9
    Email String Email Address of the recipient. This is the email to which the W-9 request was sent. The value will be null if the Form W-9 was requested using the API method RequestByURL
    FormW9RequestType String Form W-9 requested Type. URL_API - Form W-9 was requested using the API method RequestByURL. Email_API - Form W-9 was requested using the API method RequestByEmail. Email_UI - Form W-9 was requested from the TaxBandits UI application.
TotalRecords Int Number of records available for the business
TotalPages Int Total pages available for the business
Page Int Requested Page Number
PageSize Int Requested Page Size
Errors Object Shows detailed error information.

Sample Request 1 : List with all valid parameters

FormW9/List?BusinessId=387f41d7-b238-455b-b9d7-48f7d48889f5&TIN=124563758&W9Status=Completed&Page=1&PageSize=10&FromDate=03/05/2020&ToDate=03/07/2020
1

Sample Response 1

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "FormW9Records": [
   {
     "SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
     "PayeeRef": "Pe123451234",
     "Line1Nm": "ABC Inc",
     "W9Status": "COMPLETED",
     "StatusTs": "2021-02-19 14:36:28 -05:00",
     "TINMatching": {
       "Status": "SUCCESS",
       "StatusTs": "2021-06-10 07:16:01 -04:00",
       "Errors": null
     },
     "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
     "Email": "abc@abcinc.com",
     "FormW9RequestType": "URL_API"
   },
   {
     "SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
     "PayeeRef": "Pe543221234",
     "Line1Nm": "Seve Smith",
     "W9Status": "COMPLETED",
     "StatusTs": "2021-02-19 14:36:28 -05:00",
     "TINMatching": {
       "Status": "SUCCESS",
       "StatusTs": "2021-06-10 07:16:01 -04:00",
       "Errors": null
     },
     "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
     "Email": "steve@abcinc.com",
     "FormW9RequestType": "Email_API"
   }
 ],
 "TotalRecords": 2,
 "TotalPages": 1,
 "Page": 1,
 "PageSize": 10,
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

Sample Request 2 : List with BusinessID

FormW9/List?BusinessId=387f41d7-b238-455b-b9d7-48f7d48889f5
1

Sample Response 2

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "FormW9Records": [
   {
     "SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
     "PayeeRef": "Pe123451234",
     "Line1Nm": "ABC Inc",
     "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "StatusTs": "2021-02-19 14:36:28 -05:00",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-06-10 07:16:01 -04:00",
       "Errors": null
     },
     "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
     "Email": "abc@abcinc.com",
     "FormW9RequestType": "URL_API"
   },
   {
     "SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
     "PayeeRef": "Pe543221234",
     "Line1Nm": "Seve Smith",
     "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-06-10 07:16:01 -04:00",
       "Errors": null
     },
     "StatusTs": "2021-02-19 14:36:28 -05:00",
     "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
     "Email": "steve@abcinc.com",
     "FormW9RequestType": "Email_API"
   }
 ],
 "TotalRecords": 2,
 "TotalPages": 1,
 "Page": 1,
 "PageSize": 10,
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

Sample Request 3 : List with TIN

FormW9/List?TIN=124563758
1

Sample Response 3

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "FormW9Records": [
   {
     "SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
     "PayeeRef": "Pe123451234",
     "Line1Nm": "ABC Inc",
     "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-06-10 07:16:01 -04:00",
       "Errors": null
     },
     "StatusTs": "2021-02-19 14:36:28 -05:00",
     "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
     "Email": "abc@abcinc.com",
     "FormW9RequestType": "URL_API"
   },
   {
     "SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
     "PayeeRef": "Pe543221234",
     "Line1Nm": "Seve Smith",
     "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "StatusTs": "2021-02-19 14:36:28 -05:00",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-06-10 07:16:01 -04:00",
       "Errors": null
     },
     "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
     "Email": "steve@abcinc.com",
     "FormW9RequestType": "Email_API"
   }
 ],
 "TotalRecords": 2,
 "TotalPages": 1,
 "Page": 1,
 "PageSize": 10,
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

Sample Request 4 : List without BusinessID or TIN

FormW9/List?W9Status=COMPLETED_AND_TIN_MATCH_INPROGRESS&Page=1&PageSize=10&FromDate=03/05/2020&ToDate=03/07/2020
1

Sample Response 4 : Since the Requester information was not given, the system will look up for W-9s under default business and return the result.

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "FormW9Records": [
   {
     "SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
     "PayeeRef": "Pe123451234",
     "Line1Nm": "ABC Inc",
     "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "StatusTs": "2021-02-19 14:36:28 -05:00",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-06-10 07:16:01 -04:00",
       "Errors": null
     },
     "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
     "Email": "abc@abcinc.com",
     "FormW9RequestType": "URL_API"
   },
   {
     "SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
     "PayeeRef": "Pe543221234",
     "Line1Nm": "Seve Smith",
     "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "StatusTs": "2021-02-19 14:36:28 -05:00",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-06-10 07:16:01 -04:00",
       "Errors": null
     },
     "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
     "Email": "steve@abcinc.com",
     "FormW9RequestType": "Email_API"
   }
 ],
 "TotalRecords": 2,
 "TotalPages": 1,
 "Page": 1,
 "PageSize": 10,
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

Sample Request 5 : List with Invalid Status

FormW9/List?W9Status=Invalid
1

Sample Response 4 : Since the Requester information was not given, the system will look up for W-9s under default business and return the result.

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "FormW9Records": [
   {
     "SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
     "PayeeRef": "Pe123451234",
     "Line1Nm": "ABC Inc",
     "W9Status": "INVALID",
     "StatusTs": "2021-02-19 14:36:28 -05:00",
     "TINMatching": {
       "Status": "FAILED",
       "StatusTs": "2021-06-10 07:16:01 -04:00",
       "Errors": [
      {
        "Id": "ERR-TINMATCH-007",
        "Name": "TIN",
        "Message": "SSN should contain 9 digits"
      },
      {
        "Id": "ERR-TINMATCH-029",
        "Name": "TIN",
        "Message": "SSN should be in proper format"
      }
    ]
     },
     "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
     "Email": "abc@abcinc.com",
     "FormW9RequestType": "URL_API"
   }
 ],
 "TotalRecords": 1,
 "TotalPages": 1,
 "Page": 1,
 "PageSize": 1,
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# RequestByEmail

This endpoint sends a unique url to the recipients to complete their form W-9. The endpoint needs the name and the recipient’s email address to generate the unique url. The recipients will receive an email with the link to complete their W-9 in a secured portal. Once the recipients complete the Form w-9, you will receive a webhook notification for the W-9 data.

How does it work?

  1. Like any other TaxBandits API Endpoint, the first step is to call the Auth method to get the access token. This access token must be supplied in the request header as the ‘Bearer‘ token. Refer OAuth 2.0 Authentication for more information on JWT authentication and how to integrate with the subsequent requests.
  2. The second step is to call the API endpoint with the following values:
    • Access Token in the header (Will be supplied by TaxBandits or generated using TaxBandits OAuth authentication API)
    • Requester (BusinessId or TIN. Optional value to save the W-9 against a particular Business)
    • Payee Reference (Unique information that identifies the Recipient. Optional)
    • Name (Recipient Name)
    • Email (Recipient Email)

Note: When using this endpoint, the client can send W-9 requests to multiple recipients in a single submission

  1. TaxBandits will send the W-9 request emails to the recipients. The email will have the link to complete the Form W-9.

  2. The recipient will complete and sign Form W-9 in a secured portal. The secured portal can be whitelabeled with the client's URL, logo and theme.

  3. Once the recipient completes and signs the Form W-9, the client will be notified via Webhook. The Webhook payload will have the W-9 data such as the Name, Address and EIN/SSN along with the link to download the completed Form W-9.

  4. If IsTINMatching is set as ‘TRUE’ TaxBandits will validate the recipient TIN against the IRS database.

Refer to Form W-9 webhook to learn more about webhook set up and sample payload.

POST FormW9/RequestByEmail
1

Request Body

Field Type Description
SubmissionManifest object SubmissionManifest provides brief information about submission and the services opted.
    IsTINMatching Boolean TIN Matching service will be enabled when the value is set as True. Once the recipient signs the Form W-9, TaxBandits will validate the recipient’s Name, TIN and TINType with the IRS.
Requester object Business you want the W-9s to be created under. If you do not supply the requester information, then the W-9s will be created against the default business (First business created in your account)
    BusinessId Guid Optional Unique Business Identifier. This ID is generated by TaxBandits after you create a business in your account using the Business endpoint.
    TIN String Optional Taxpayer Identification Number. Use this as an alternate for BusinessId. Values: EIN, SSN
Size Range: 9-11
Recipients object[] Collection of Recipient's Name and Email
    PayeeRef String Optional An unique identifier for each recipient completing the Form W-9. This identifier will be used in future references of the recipient in the API.
Size Range: 1-50
    Name string Name of the recipient
Size Range: 1-80
    Email string Email Address of the recipient. This is the email address to which the W-9 request email will be sent.
Size Range: 1-50

Response Body

Field Type Description
SubmissionId Guid Unique identifier of a submission.
Requester Object Requester information.
    BusinessId Guid A unique identifier of the business.
    BusinessNm String Requester Name. If the requester is a Business, then the Business Name will be returned. If the requester is an Individual, then the Payer’s full name will be returned.
    TINType String TIN Type of the Requester.
    TIN String Taxpayer Identification Number of the requester.
FormW9Records Object Details of Form W-9 requests given in the request.
    SuccessRecords Object Recipients with no error in the request
        PayeeRef String Unique identifier of the recipient.
        Email String Email Address of the recipient to which W-9 request was sent.
        W9Status String Status of the W-9
        StatusTs String Timestamp of the W-9 status
    ErrorRecords Object Details of the recipients with errors
        PayeeRef String An unique identifier of a recipient.
        Email String Email Address of the recipient given in the request
        Errors object[] Collection of errors for the recipient
            Id string Error ID number. This ID is assigned by TaxBandits and it is unique for each error.
            Name string Name of the errored node.
            Message string Shows the error message.
Errors object[] Collection of errors in the request. Some of the errors listed under this object are, You should have at-least one business in your account to request W-9 Insufficient credits in the account

Sample Request 1 : Send W-9 email requests to recipients by giving the BusinessId (Requester) and recipients information.

{
 "SubmissionManifest": {
   "IsTINMatching": true
 },
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "TIN": null
 },
 "Recipients": [
   {
     "PayeeRef": "8987844654654654",
     "Name": "Allen Smith",
     "Email": "allen.smith@abc.com"
   }
 ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Sample Response 1

{
 "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "FormW9Records": {
   "SuccessRecords": [
     {
      "PayeeRef": "8987844654654654",
       "Email": "allen.smith@abc.com",
       "W9Status": "ORDER_CREATED",
       "StatusTs": "2021-03-09 05:21:56 -05:00"
     }
   ],
   "ErrorRecords": null
 },
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Sample Request 2 : Send W-9 email requests to recipients by giving the Business TIN (Requester) and recipients information.

{
 "SubmissionManifest": {
   "IsTINMatching": true
 },
 "Requester": {
   "BusinessId": null,
   "TIN": "22-2222222"
 },
 "Recipients": [
   {
     "PayeeRef": "8987844654654654",
     "Name": "Allen Smith",
     "Email": "allen.smith@abc.com"
   }
 ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Sample Response 2

{
 "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "FormW9Records": {
   "SuccessRecords": [
     {
      "PayeeRef": "8987844654654654",
       "Email": "allen.smith@abc.com",
       "W9Status": "ORDER_CREATED",
       "StatusTs": "2021-03-09 05:21:56 -05:00"
     }
   ],
   "ErrorRecords": null
 },
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Sample Request 3 : Send W-9 email requests to recipients without Requester information (BusinessId or TIN). The recipients will be tied to the default business.

{
 "SubmissionManifest": {
   "IsTINMatching": true
 },
 "Requester": null,
 "Recipients": [
   {
     "PayeeRef": "8987844654654654",
     "Name": "Allen Smith",
     "Email": "allen.smith@abc.com"
   }
 ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13

Sample Response 3

{
 "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "William Enterprises",
   "TINType": "EIN",
   "TIN": "11-1111111"
 },
 "FormW9Records": {
   "SuccessRecords": [
     {
      "PayeeRef": "8987844654654654",
       "Email": "allen.smith@abc.com",
       "W9Status": "ORDER_CREATED",
       "StatusTs": "2021-03-09 05:21:56 -05:00"
     }
   ],
   "ErrorRecords": null
 },
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Sample Request 4 : W-9 request with invalid recipient email address format.

{
 "SubmissionManifest": {
   "IsTINMatching": true
 },
 "Requester": {
   "BusinessId": null,
   "TIN": "22-2222222"
 },
 "Recipients": [
   {
     "PayeeRef": "8987844654654658",
     "Name": "Allen Smith",
     "Email": "allen.smith@abccom"
   }
 ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Sample Response 4 : The order is not created and the invalid email format error is returned.

{
 "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "FormW9Records": {
       "SuccessRecords": null,
       "ErrorRecords": [
           {
               "PayeeRef": "8987844654654658",
               "Email": "allen.smith@abccom",
               "Errors": [
                   {
                       "Id": "F08-100022",
                       "Name": "Email",
                       "Message": "Invalid Email address."
                   }
               ]
           }
       ]
   },
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# RequestByUrl

To complete the Form W-9, TaxBandits will supply the URL that can be opened on its own or embedded into a web page or native app. To get the URL, you will have to send a request to our API with a unique Payee Reference such as vendor id, contractor number or a random number or even an email address (This will be used to identify the recipient for future references) and some business identifier (Business Id or TIN).

The popular use case is where you have a portal for your vendors and you can place a link to collect the W9 information. Each vendor who logs in will get a unique url embedded page to complete their W9.

How does this work?

  1. Like any other TaxBandits API Endpoint, the first step is to call the Auth method to get the access token. This access token must be supplied in the request header as the ‘Bearer‘ token.Refer to OAuth 2.0 Authentication for more information on JWT authentication and how to integrate with the subsequent requests.

  2. The second step is to call the FormW9/RequestByURL API endpoint. If you are trying the embed this link into your web page, this endpoint must be called before you load the page. You will need to supply the following parameters:

    • Access Token in the header (Will be supplied by TaxBandits or generated using TaxBandits OAuth authentication API)
    • Payee Reference (Unique information that identifies the Recipient). The Payee Reference can be anything that uniquely identifies the recipient such as Vendor id, contractor number or a random number or even the recipient email address (This will be used to identify the recipient for future references)
    • Business Identifier (Business Id or TIN) - Business Identifier (Business Id or TIN) - This is used to identify and save the W9 against a particular Business. Refer to the Business endpoint to learn more about creating a Business in TaxBandits and retrieving the Business Id. In TaxBandits, you can uniquely identify a business using either by its TIN or the TBS generated Business Id. You can also define a ‘Default Business’ in the TaxBandits Application and skip sending the Business Identifier along with the request. See below for more examples.
    • Recipient Name and Address (Optional) - If you want to pre-fill the Name and Address of the recipient on the W-9 form, you can send them as a parameter in the request.
    • Business Logo and Callback URLs (Optional) - You can add the business logo on the Form W-9 completion page and also set the callback redirection for recipient form completion/cancel.

  3. TaxBandits will generate an unique URL and will send the link in the response, which must then be embedded into the page for the recipients to click. When clicked, this link will show the Form W-9 with built-in validations. There is also an electronic signature pad that allows the recipient to sign electronically.

  4. Once the recipient completes and signs the Form W-9, you will be notified via Webhook. The Webhook payload will have the W-9 recipient data such as the Name, Address and EIN/SSN along with the link to download the completed Form W-9

  5. If IsTINMatching is set ‘TRUE’, TaxBandits will validate the recipient Name, TIN and TINType against the IRS database. The TIN Matching status of the recipient (Success or Failed) will be posted on the same Webhook URL configured for Form W-9 status change.

If the Name and TIN given by the recipient does not match with the IRS database, the W-9 will become invalid and you have to request a new Form W-9 from the recipient.

Refer Form W-9 webhook to know more about webhook set up and sample payload

POST FormW9/RequestByUrl
1

Request Body

Field Type Description
Requester Object Collects the Requestor identifier. TIN or TBS Business Id or PayerRef. If neither is supplied, the default Business will be assumed as the Requester.
    PayerRef String Optional Unique payer identifier assigned by the client while requesting the payer information using the endpoint Business/RequestByURL.
Size Range: 1-50
    BusinessId Guid Optional TaxBandits Unique Business Identifier. This ID is generated by `TaxBandits after you create a business in your account using the Business endpoint.If you do not supply the BusinessId in the request, then the URL will be generated against the default business (First business created in your account).
    TIN String Optional Taxpayer Identification Number. Use this as an alternative for BusinessId or PayerRef.
Size Range: 9-11
Allowed values: "EIN", "SSN" (Including hyphen)
Recipient Object Collects the recipient's unique identifier and other basic information of the recipient that will be pre-filled on the Form.
    PayeeRef String An unique identifier for each recipient completing the Form W-9. This identifier will be used in future references of the recipient in the API.
Size Range: 1-50
    Name String Optional Recipient Name. This will be pre-filled on the Form.
Size Range: ..50
    Address Object Collects US address details of the recipient.
        Address1 String Optional Recipient US Address 1 (street address or post office box of that locality). This will be pre-filled on the Form.
Size Range: ..35
        Address2 String Optional Recipient US Address 2 (suite or apartment number). This will be pre-filled on the Form.
Size Range: ..35
        City String Optional Recipient US City. This will be pre-filled on the Form.
Size Range: ..27
        State string Optional Recipient US State Code. This will be pre-filled on the Form.
Size Range: 2
Allowed values: "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "FM", "GU", "MH", "MP", "PW", "PR", "VI", "AA", "AE", "AP"
        ZipCd String Optional Recipient Zip Code. In the format 99999 or 99999-9999. This will be pre-filled on the Form.
Size Range: 5-10
    IsTINMatching Boolean Optional TIN Matching will be enabled when the value is set as True. Once the recipient completes Form W-9, TaxBandits will match the Recipient's Name and SSN with the IRS database and notify the client via the webhook with the TIN results.
Allowed values: "true", "false"
    Customization Object Collects the customizations like TIN service, Business Logo and Callback URLs.
        BusinessLogoUrl String Optional Business Logo that will be displayed on the Form completion page.
Size Range: ..150
    RedirectUrls Object Collects the RedirectUrls like ReturnUrl and CancelUrl.
        ReturnUrl String Optional Return Redirection URL. Set the callback URL redirection once the recipient completes filling the Form W-9.
Size Range: ..150
        CancelUrl String Optional Cancel Redirection URL. Set the callback URL when the recipient clicks the cancel button on the Form W-9.
Note: If you do not provide the Cancel Callback Redirection URL, the cancel button will not be shown to the recipient.
Size Range: ..150

Note : You need to supply one of these values - TIN or TBS Business Id or PayerRef. If neither is supplied, the default Business will be assumed.

Response Body

Field Type Description
SubmissionId Guid Unique identifier of a submission.
PayeeRef String Unique identifier of the recipient.
W9Url String URL that can be embedded on the client's website using Iframe or other means.
Errors object Shows error information. This object will list the errors in the request parameters.

Sample Request 1: Request W-9 URL using Payee Reference alone. The URL will be generated for the default business defined in the TaxBandits application for your account.

{
  "Recipient": {
    "PayeeRef": "Pe464522"
  }
}
1
2
3
4
5

Sample Response 1:

{
    "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
    "PayeeRef": "Pe464522",    
    "W9Url": "https://esignw9.taxforall.com?uId=95d1bedb-f6b4-4300-9186-751719050020",
    "Errors": null
}
1
2
3
4
5
6

Sample Request 2: Request W-9 URL using Payee Reference and BusinessId.

{
  "Requester": {
    "BusinessId": "2ec0fee8-6076-4305-95e7-873936ebd1cd"
  },
  "Recipient": {
    "PayeeRef": "Pe464522"
  }
}
1
2
3
4
5
6
7
8

Sample Response 2:

{
    "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
    "PayeeRef": "Pe464522",    
    "W9Url": "https://esignw9.taxforall.com?uId=95d1bedb-f6b4-4300-9186-751719050020",
    "Errors": null
}
1
2
3
4
5
6

Sample Request 3: Request W-9 URL with Payee Reference and Recipient details.

{
  "Requester": null,
  "Recipient": {
    "PayeeRef": "Pe123451234",
    "Name": "John",
    "Address": {
      "Address1": "1751 Kinsey Rd",
      "Address2": "Main St",
      "City": "Dothan",
      "State": "AL",
      "ZipCd": "36303"
    },
    "IsTINMatching": true
  },
  "Customization": null,
  "RedirectUrls": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Sample Response 3:

{
    "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
    "PayeeRef": "Pe464522",    
    "W9Url": "https://esignw9.taxforall.com?uId=95d1bedb-f6b4-4300-9186-751719050020",
    "Errors": null
}
1
2
3
4
5
6

Sample Request 4: Request W-9 URL with Recipient Payer Reference, Payee Reference, Business Logo, Callback redirection URLs and TIN Matching service.

{
  "Requester": {
    "PayerRef": "B12345"
  },
  "Recipient": {
    "PayeeRef": "123456",
    "Name": "John",
    "Address": {
      "Address1": "1751 Kinsey Rd",
      "Address2": "Main St",
      "City": "Dothan",
      "State": "AL",
      "ZipCd": "36303"
    },
    "IsTINMatching": true
  },
  "Customization": {
    "BusinessLogoUrl": "https://example.com"
  },
  "RedirectUrls": {
    "ReturnUrl": "https://example.com",
    "CancelUrl": "https://example.com"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

Sample Response 4:

{
   "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",   
   "PayeeRef": "123456",
   "Url": "https://esignw9.taxforall.com?uId=95d1bedb-f6b4-4300-9186-751719050020",
   "Errors": null
}
1
2
3
4
5
6

# Status

This method will return the status of all the Form W-9s (complete and incomplete) for a particular recipient.

The statuses of the W-9s that were requested using the endpoints RequestByURL, RequestByEmail and TaxBandits application can be retrieved using this method.

W-9 Statuses

  • URL Generated - The W-9 URL is generated by TaxBandits, but the recipient has not opened it. (Not applicable to RequestByEmail method)

  • Order Created - The client requested W-9 using RequestByEmail method and it is not yet processed by TaxBandits. (Not applicable to RequestByURL method)

  • Scheduled - The TaxBandits email service has taken up the W-9 request and the email is scheduled to be sent. (Not applicable to RequestByURL method)

  • Sent - Client sent W-9 request from TaxBandits API and the email has yet to be delivered. (Not applicable to RequestByURL method)

  • Opened - The recipient has opened the Form W-9 and has yet to complete it.

  • Completed - Recipient has completed and signed the Form W-9.

  • Completed_and_Tin_Match_InProgress - Form W-9 has been completed and the TIN Matching process is Inprogress.

  • Delivered - The email with the link to complete the Form W-9 has been delivered to the recipient. (Not applicable to RequestByURL method).

  • Bounced - The email was not delivered. The email given in the request may be invalid. (Not applicable to RequestByURL method).

  • Invalid - TIN given by the recipient does not match with the IRS database and the W-9 has become invalid.

TIN Statuses

  • Order Created - Recipient completed the Form W-9 and a TIN Matching order is created in Taxbandits. The TIN Matching request is yet to be sent to the IRS.

  • Under Process - Our system has batched the TIN Requests and is queued for IRS submission.

  • Sent to Agency - The order has been sent to the IRS for TIN verification and TaxBandits is waiting for the response from the IRS. Usually the IRS takes one business day to complete the TIN verification process.

  • Success - Recipient’s Name and TIN combination matches with the records in the IRS database.

  • Failed - Recipient’s Name and TIN combination does not match with the records in the IRS database.

Key Points

  • If there are multiple W-9s for the same Email or PayeeRef, the statuses of all the W-9s will be listed as an array.

  • If you do not supply the BusinessId in the request, then the status of the W-9 that matches the Email or PayeeRef linked to the default business will be retrieved. 

GET FormW9/Status
1

Request Body

Field Type Description
PayeeRef String Unique identifier of a recipient. Either PayeeRef or Email is required.
Size Range: 1-50
Email String Email Address of the recipient.
Size Range: 1-50
BusinessId Guid Optional Unique Business Identifier. If you do not supply the BusinessId in the request, the BusinessId of the default business will be mapped.
TIN String Optional Taxpayer Identification Number. Use this as an alternate for BusinessId. Values: EIN, SSN
Size Range: 9-11

Response Body

Field Type Description
SubmissionId Guid Unique identifier of a submission.
Requester Object Requester information.
    BusinessId Guid A unique identifier of the business.
    BusinessNm String Requester Name. If the requester is a Business, then the Business Name will be returned. If the requester is an Individual, then the Payer’s full name will be returned.
    TINType String TIN Type of the Requester.
    TIN String Taxpayer Identification Number of the requester.
PayeeRef String Unique identifier of the recipient
Email String Email Address of the recipient. This is the email to which the W-9 request was sent.
TotalRecords Int Number of records available for the Payee Reference
Status Object[] Statuses of the W-9 records for the recipient
    SubmissionId Guid Submission ID of the original W-9 Request
    W9Status String Status of the W-9.
    StatusTs String Timestamp of the W-9 Status
    TINMatching Object TIN Matching information.
        Status String TIN Matching status.
        StatusTs String Timestamp of the TIN Matching Status.
        Errors String Shows the detailed error message.
    FormW9RequestType String Form W-9 requested Type. URL_API - Form W-9 was requested using the API method RequestByURL. Email_API - Form W-9 was requested using the API method RequestByEmail. Email_UI - Form W-9 was requested from the TaxBandits UI application.
Errors Object Shows detailed error information.

Sample Request 1 : Get W-9 status of a recipient with PayeeRef and BusinessId.

FormW9/Status?PayeeRef=Pe123451234&BusinessId=7B82B242-1223-4029-9251-C0446298F620
1

Sample Response 1

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "Email": "steve@abcinc.com",
 "TotalRecords": 1,
 "Status": [
   {
     "SubmissionId": "85dd7845-55b0-4b1d-9f1b-17a6f51c4dea",
     "W9Status": "COMPLETED",
     "StatusTs": "2021-02-22 04:24:09 -05:00",
     "TINMatching": {
       "Status": "SUCCESS",
       "StatusTs": "2021-06-21 08:00:35 -04:00",
       "Errors": null
     },
     "FormW9RequestType": "URL_API"
   }
 ],
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

Sample Request 2 : Get W-9 status of a recipient with Email and BusinessId.

FormW9/Status?Email=steve@abcinc.com&BusinessId=7B82B242-1223-4029-9251-C0446298F620
1

Sample Response 2 : Statuses of the W-9s are listed as an array. This recipient was requested to complete W-9 multiple times using the same PayeeRef.

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "Email": "steve@abcinc.com",
 "TotalRecords": 2,
 "Status": [
   {
     "SubmissionId": "85dd7845-55b0-4b1d-9f1b-17a6f51c4dea",
     "W9Status": "OPENED",
     "StatusTs": "2021-02-22 04:24:09 -05:00",
     "TINMatching": null,
     "FormW9RequestType": "URL_API"
   },
   {
     "SubmissionId": "65c6dc7a-c659-4f42-af26-bcd1ccf07432",
     "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "StatusTs": "2021-02-22 04:24:30 -05:00",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-06-10 07:16:01 -04:00",
       "Errors": null
     },
     "FormW9RequestType": "EMAIL_API"
   }
 ],
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

Sample Request 3 : Get W-9 status of a recipient with PayeeRef and TIN.

FormW9/Status?PayeeRef=Pe123451234&TIN=003313330
1

Sample Response 3

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "Email": "steve@abcinc.com",
 "TotalRecords": 1,
 "Status": [
   {
     "SubmissionId": "85dd7845-55b0-4b1d-9f1b-17a6f51c4dea",
     "W9Status": "OPENED",
     "StatusTs": "2021-02-22 04:24:09 -05:00",
     "TINMatching": null,
     "FormW9RequestType": "URL_API"
   }
 ],
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Sample Request 4 : Get W-9 status of a recipient with PayeeRef and no Requester (BusinessId or TIN) information.

FormW9/Status?PayeeRef=Pe123451234
1

Sample Response 4 : Since the Requester information was not given, the system will look for W-9s under the default business and return the result.

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "Email": "steve@abcinc.com",
 "TotalRecords": 1,
 "Status": [
   {
     "SubmissionId": "85dd7845-55b0-4b1d-9f1b-17a6f51c4dea",
     "W9Status": "OPENED",
     "StatusTs": "2021-02-22 04:24:09 -05:00",
     "TINMatching": null,
     "FormW9RequestType": "URL_API"
   }
 ],
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Sample Request 5 : Get W-9 status of a recipient with invalid Email Address.

FormW9/Status?Email=steve@abcinccom
1

Sample Response 5

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": null,
 "Email": null,
 "TotalRecords": 0,
 "Status": null,
 "Errors": [
   {
     "Id": "F08-100022",
     "Name": "Email",
     "Message": "Invalid Email address."
   }
 ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Sample Request 6 : Get W-9 status of a recipient with PayeeRef [Where two recipients have the same Payee Reference].

FormW9/Status?PayeeRef=Pe123451234
1

Sample Response 6

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "Email": null,
 "TotalRecords": 2,
 "Status": [
   {
     "SubmissionId": "85dd7845-55b0-4b1d-9f1b-17a6f51c4dea",
     "W9Status": "OPENED",
     "StatusTs": "2021-02-22 04:24:09 -05:00",
     "TINMatching": null,
     "FormW9RequestType": "URL_API"
   },
   {
     "SubmissionId": "65c6dc7a-c659-4f42-af26-bcd1ccf07432",
     "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "StatusTs": "2021-02-22 04:24:30 -05:00",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-06-10 07:16:01 -04:00",
       "Errors": null
     },
     "FormW9RequestType": "EMAIL_API"
   }
 ],
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# Webhook Responses

Webhooks are used to notify clients when one of their recipients has completed the W-9. The webhook payload includes W-9 data such as the recipient’s name, address, EIN/SSN, as well as the link to download the completed form.

Go to Webhooks for information on Webhooks in TaxBandits.

Configure the Webhook for W-9 Status

  1. Log in to the developer console.

  2. Then navigate to Settings >> Webhooks.

  3. Click the Add Webhook button and choose the Event Type as Form W-9 Status Change while setting up your Webhook URL.

Webhook Settings

Add Webhook

  1. After entering the Callback URL, click on the Submit button. Ensure that the callback URL is valid because the API will post a sample JSON. The callback URL is expected to return HTTP 200 response code in order to remain active. If the API doesn’t return 200 response code, then the callback URL will go inactive. You can retry posting the sample data to make the callback URL Active.

Response Body

Field Type Description
SubmissionId guid Unique identifier of a submission
Requester object Requester information.
    BusinessId Guid Unique identifier of a business
    BusinessNm String Requester Name. If the requester is a Business, then the Business Name will be returned. If the requester is an Individual, then the Payer’s full name will be returned.
    TINType string TIN Type of the Requester.
    TIN string Taxpayer Identification Number of the requester.
PayeeRef string Unique identifier of the recipient
W9Status string RecordStatus Status of the W-9
StatusTs string Timestamp of the W-9 Status.
TINMatching Object TIN Matching information.
    Status String TIN Matching status.
    StatusTs String Timestamp of the TIN Matching Status.
    StatusMsg String Status message of the TIN Matching.
    Errors String Shows the detailed error message.
FormW9RequestType string Form W-9 requested Type. URL_API - Form W-9 was requested using the API method RequestByURL. Email_API - Form W-9 was requested using the API methodRequestByEmail. Email_UI - Form W-9 was requested from the TaxBandits UI application.
PdfUrl string URL to download the completed W-9.
Email string Email Address of the recipient. This is the email to which the W-9 request was sent. The value will be null if the Form W-9 was requested using the API method RequestByURL
FormData object[] Form W-9 details of the recipient.
    Line1Nm string Name as shown on the income tax return.
    Line2Nm string Business name/disregarded entity name, if different from Line1 Name.
    TINType string TIN type of the recipient. Either EIN or SSN
    TIN string Recipient’s TIN.
    Address object Recipient’s complete address
        Address1 string Recipient’s Address 1 (number, street)
        Address2 string Recipient’s Address 2 (apt. or suite no.)
        City string Recipient’s City
        State string Recipient’s State
        ZipCd string Recipient’s Zip Code
    FederalTaxClassification string U.S. Federal Tax Classification of the person whose name is entered on line 1
    ExemptPayeeCd string This code identifies recipients that are exempt from backup withholding.
    ExemptFromFATCA string This code identifies recipients that are exempt from reporting under FATCA.
    IsBackUpWH Boolean When true, identifies the recipient is subject to backup withholding. The completed Form W-9 PDF will have the item 2 under Part II crossed out. When false, identifies the recipient is not subject to backup withholding.
Errors object[] Shows detailed error information Sample Webhook Response

Scenario 1: The recipient has completed Form W-9 and TIN Matching is Inprogress.

{
 "SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
 "StatusTs": "2021-02-19 14:36:28 -04:00",
 "TINMatching": {
   "Status": "ORDER_CREATED",
   "StatusTs": "2021-06-10 07:16:01 -04:00",
   "StatusMsg": null,
   "Errors": null
 },
 "FormW9RequestType": "URL_API",
 "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
 "Email": "steve@abcinc.com",
 "FormData": {
   "Line1Nm": "ABC Inc",
   "Line2Nm": null,
   "TINType": "EIN",
   "TIN": "11-1111111",
   "Address": {
     "Address1": "123 E. Main St",
     "Address2": "Suite 400",
     "City": "Rock Hill",
     "State": "SC",
     "ZipCd": "29730"
   },
   "FederalTaxClassification": "C Corporation",
   "ExemptPayeeCd": "5",
   "ExemptFromFATCA": "E"
 },
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

Scenario 2: The recipient has completed Form W-9 and TIN Matching is Success

{
 "SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "W9Status": "COMPLETED",
 "StatusTs": "2021-02-19 14:36:28 -04:00",
 "TINMatching": {
   "Status": "Success",
   "StatusTs": "2021-06-10 07:16:01 -04:00",
   "StatusMsg": null,
   "Errors": null
 },
 "FormW9RequestType": "URL_API",
 "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
 "Email": "steve@abcinc.com",
 "FormData": {
   "Line1Nm": "ABC Inc",
   "Line2Nm": null,
   "TINType": "EIN",
   "TIN": "11-1111111",
   "Address": {
     "Address1": "123 E. Main St",
     "Address2": "Suite 400",
     "City": "Rock Hill",
     "State": "SC",
     "ZipCd": "29730"
   },
   "FederalTaxClassification": "C Corporation",
   "ExemptPayeeCd": "5",
   "ExemptFromFATCA": "E"
 },
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

Scenario 3: The recipient has completed Form W-9 and TIN Matching is Failed

{
 "SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "W9Status": "Invalid",
 "StatusTs": "2021-02-19 14:36:28 -04:00",
 "TINMatching": {
   "Status": "Failed",
   "StatusTs": "2021-06-10 07:16:01 -04:00",
   "StatusMsg": null,
   "Errors": null
 },
 "FormW9RequestType": "URL_API",
 "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
 "Email": "steve@abcinc.com",
 "FormData": {
   "Line1Nm": "ABC Inc",
   "Line2Nm": null,
   "TINType": "EIN",
   "TIN": "11-1111111",
   "Address": {
     "Address1": "123 E. Main St",
     "Address2": "Suite 400",
     "City": "Rock Hill",
     "State": "SC",
     "ZipCd": "29730"
   },
   "FederalTaxClassification": "C Corporation",
   "ExemptPayeeCd": "5",
   "ExemptFromFATCA": "E"
 },
 "Errors": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

← NewHireReport →