RequestDraftPdfUrl
The response of the API request will return the Draft PDF for review purpose. This method can be used to retrieve PDF for a single record/form. The PDF will be returned in the response for the Forms that are not yet Transmitted in TaxBandits.
This method will only provide the Copy A of the Form 1099, which will be watermarked with the words "For Review Only."
How it works?
- 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.
- The second step is to call the Create endpoint Form1099NEC/Create to create a return in TaxBandits. Store the RecordId of the 1099 form that is generated by TaxBandits and returned in the Response.
- Next, call the [POST] Form1099NEC/RequestDraftPdfUrl endpoint. You will need to supply the following parameters:
- Access Token in the header as Bearer Token (Generated using TaxBandits OAuth authentication API)
- Form reference (RecordId) - Specify the RecordId for the form you need the Draft PDF form. If you do not have the RecordId, then you request the PDF using the following parameters.
- Business Reference - Use the business reference PayerRef or Businessid or TIN.
- Recipient Reference - Use the recipient reference PayeeRef or RecipientId or TIN.
- Tax Year - Tax year of the form you are requesting the PDF for.
PDF Security
Since the PDFs contain PII (Personally Identifiable Information) data of the recipients, TaxBandits has added an additional security to the PDFs. The PDF links are encrypted and you will have to decrypt it before downloading.
Note: You should have an AWS Amazon Account . If not, create one from here https://aws.amazon.com/.
Decrypt PDF URLs
You need to get the pdf key from AWS S3 Cloud. To get the PDF key pass the following values.
- AWS AccessKey and AWS SecretKey - These keys can be generated in your AWS account.
- Base64Key - This is available in the TaxBandits console site (Sandbox: sandbox.taxbandits.com, Live: console.taxbandits.com). After logging in, navigate to Settings >> API credentials.
- S3 file path - The file path you received in the response of RequestPdfUrls method. Remove the main domain from the file path. In the below example, the file path starts from “pdfs/000d3…..”
- Bucket Name - The bucket name of the AWS S3 file. This is available in the TaxBandits console site (Sandbox: sandbox.taxbandits.com, Live: console.taxbandits.com). After logging in, navigate to Settings >> API credentials.
POST Form1099NEC/RequestDraftPdfUrl
Request Body
| Field | Type | Description |
|---|---|---|
| RecordId | Guid | Optional Specify the RecordId of the return |
| TINMaskType | string | Optional TIN Mask type on the TIN printed on the PDFAllowed values: "MASKED", "UNMASKED" |
| TaxYear | string | Optional Tax Year of the return. Specify only if you do not have the RecordId |
| Business | object | Optional Collects the Business identifier TIN or TBS Business Id or PayerRef. This object information is required only if you do not have the RecordId |
| 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. |
| PayerRef | string | Optional Unique payer identifier assigned by the client.Size Range: 1 to 50 |
| TINType | string | Optional TIN type of the Business TIN. Use this as an alternative for BusinessId or PayerRef.Allowed values: "SSN,EIN" |
| TIN | string | Optional Taxpayer Identification Number. Use this as an alternative for BusinessId or PayerRef.Size Range: 9 to 11 |
| Recipient | object | Optional Collects the recipient's unique identifier. This object information is required only if you do not have the RecordId |
| PayeeRef | string | Optional An unique identifier for each recipient set by the client.Size Range: 1 to 50 |
| RecipientId | Guid | Optional Unique Recipient Identifier generated by TaxBandits |
| TINType | string | Optional TIN type of the Recipient's TIN. Use this as an alternative for RecipientId or PayeeRef.Allowed values: "SSN,EIN" |
| TIN | string | Optional Taxpayer Identification Number. Use this as an alternative for RecipientId or PayeeRef. |
Response Body
| Field | Type | Description |
|---|---|---|
| RecordId | Guid | Unique identifier of the record |
| RecipientId | Guid | Unique Recipient Identifier generated by TaxBandits |
| PayeeRef | string | An unique identifier for each recipient set by the client. |
| DraftPdfUrl | string | URL of the Draft PDF |
| Errors | object[] | Shows detailed error information |
| Id | string | Returns the validation error code |
| Name | string | Name of the validation error |
| Message | string | Description of the validation error |
Request JSON 1: To generate Draft PdfUrl With just the RecordId
{
"TaxYear": null,
"RecordId": "cf0a188b-6661-4b57-b04b-ba9ead52a16e",
"Business": null,
"Recipient": null
}
Response JSON 1: Draft PdfUrl will be generated for the given RecipientId.
{
"RecordId": "cf0a188b-6661-4b57-b04b-ba9ead52a16e",
"RecipientId": "bd2221f7-4be6-4cc7-813c-6346e23b9f63",
"PayeeRef": null,
"DraftPdfUrl":"https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/a570efbd-740f-4ae2-bfe7-26356cd85148/3e99f728-e9d4-4d88-99b6-e00638da7a5b/1099/221556/d/copy_tbs_wm_1up_221556.pdf",
"Error": null
}
Request JSON 2: To generate Draft PdfUrl With No RecordId.
{
"TaxYear": "2021",
"RecordId": null,
"Business": {
"BusinessId": "94B6214D-8DCA-490C-8FC3-602840B439B5",
"PayerRef": null,
"TINType": null,
"TIN": null
},
"Recipient": {
"RecipientId": "6DDFFB5A-565F-402D-8602-7ECD917CEC04",
"PayeeRef": null,
"TINType": null,
"TIN": null
}
}
Response JSON 2: Draft PdfUrl will be generated for the given BusinessID and RecipientId.
{
"RecordId": "cf0a188b-6661-4b57-b04b-ba9ead52a16e",
"RecipientId": "6DDFFB5A-565F-402D-8602-7ECD917CEC04",
"PayeeRef": null,
"DraftPdfUrl":"https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/a570efbd-740f-4ae2-bfe7-26356cd85148/3e99f728-e9d4-4d88-99b6-e00638da7a5b/1099/221556/d/copy_tbs_wm_1up_221556.pdf",
"Error": null
}