[Beta] Tax Forms

Introduction

Our Tax Forms product provides an easy way for you to download an end-user's tax forms from the source. We're starting with support for W-2 and 1099 forms with plans to expand support to additional form types. The tax form can be retrieved with or without JSON data depending on your use cases.

Use Cases

  • Tax filing: Reduce friction, user input errors, and document processing with tax forms pulled directly from the source. No need for users to upload their documents or manually input each box.
  • Tax estimation: Use the most recent year's tax form to help users estimate their upcoming tax payments for their 1099 job(s) to avoid IRS penalties.
  • Tax withholdings optimization: Combine tax forms with paystubs data to help users optimize their tax withholdings giving them more money throughout the year rather than a large refund after filing a return.
  • Income & employment verification: Tax forms can be used to verify total earnings, employer/payer details, taxes withheld, and more as part of income & employment verification.

Implementation

Step 1: Subscribe to the webhook event for tax forms

Subscribe to the tax_forms.added webhook using the request below

POST /v1/webhooks
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
  "url": "https://your-domain.com/webhook_endpoint",
  "status": "ACTIVE",
  "enabled_events": [
    "tax_forms.added",
  ]
}

This webhook will be published when tax forms are ready to be downloaded and new data is available. You will receive a single webhook with metadata about each tax form added or deleted in the job.

{
    "event": "tax_forms.added",
    "event_id": "9bb2d0cd-9f54-4829-a6c2-a48b0cd18b6d",
    "payload": {
        "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
        "end_user_id": "01234",
        "link_token_id": "f2b2cc6e-b53c-4175-9319-acfc3f39f9f2",
        "name": "tax_forms",
        "timestamp": "2021-01-12T02:36:01.287148+00:00",
        "outcome": "success",
        "added": [{
            "id": "b0e92f7b-c0b2-4418-a34d-3f316ca45c84",
            "year": 2022,
            "form_type": "W-2"
        }],
        "deleted": [{
            "id": "57043868-6fb3-47e8-a2b7-c993bd023f25",
            "year": 2001,
            "form_type": "1099-K"
        }]
    }
}

Note: The end_user_id is your internal reference to the end user. See User Model for more information.

Step 2: Retrieve the document

There are 2 options for retrieving tax forms: document only or document + JSON data. The default is document only and provides a download_url to retrieve the PDF document. Document + JSON provides the PDF document in addition to using optical character recognition (OCR) to convert the document into machine-encoded text that is presented as JSON. The JSON data makes it faster to process the document without having to manually review or apply OCR after retrieving the document.

For security purposes, the download_url is only active for 15 minutes. As such, we recommend that you download the document as soon as you retrieve the download_url. If the download_url has expired, calling the /tax_forms endpoint again will generate a new, active download_url.

Request

GET /v1/accounts/449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65/tax_forms/b0e92f7b-c0b2-4418-a34d-3f316ca45c84
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET

Response

See the full Tax Forms API reference here.

{
    "data": {
        "id": "cc5a63c8-486e-4323-a9ef-8e0ae3d52eb0",
        "created_at": "2022-07-12T17:32:23.162839-04:00",
        "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
        "form_type": "W-2",
        "year": 2021,
        "document": {
            "id": "b0e92f7b-c0b2-4418-a34d-3f316ca45c84",
            "download_url": [tax forms download URL],
            "download_url_expiration": "2022-07-18T17:47:52.782334+00:00"
        }
    }
}

Interested in integrating tax forms into your workflow? Reach out to [email protected] for access today!


Did this page help you?