Technical Implementation
This guide explains how to access Tax forms. For an overview of concepts in the Pinwheel system that are referenced in this doc, review the Platform Overview.
Step 1: Subscribe to the webhook events
Pinwheel sends webhook events to alert you when up-to-date Taxes data is available for a user or Monitoring has detected a change to a user's information.
Register a webhook endpoint using the POST /v1/webhooks with tax_forms.added specified in the enabled_events. See Webhooks for additional configuration details and instructions on authenticating webhook events.
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",
]
}
A 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. For details on the webhook payload, see Tax Forms Webhook Events.
Note: The end_user_id is your internal reference to the end user. See User Model for more information.
Step 2: Connect an account
To initialize Link you will need to generate a short-lived Link token. Link tokens are single-use and expire after 15 minutes. Link tokens define your user experience and tell Pinwheel what jobs you need us to complete.
Launch Link so a user can connect a new account. To launch Link, your server side code will create a single-use, short-lived Link Token using the POST /v1/link_tokens endpoint.
You should pass tax_forms into the required_jobs when creating the Link Token to indicate that tax forms are required.
Visit the Implementation Guide to see additional customization parameters for Link.
POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
"org_name": "YOUR APP NAME",
"end_user_id": "my_user_12345",
"required_jobs": ["tax_forms"]
}
You'll pass the token from the response to one of the Link SDKs to launch a Link session inside your application.
Development Tip
Test this flow without writing any code using the Test Console to create a Link Token and launch a Link session in the Developer Dashboard.
Step 3: Retrieve the tax form(s)
To retrieve a tax form, you must first get the tax form ID. You can obtain this ID either via the tax_forms.added webhooks, or via the Tax Forms LIST endpoint.
Once you have the tax form ID, you can call the Tax Forms GET endpoint to retrieve the tax form. There are 2 options for retrieving tax forms: document only or document + parsed data. The default is document only and provides a download_url which you can use to download the PDF document. Document + parsed data provides the PDF document in addition to using optical character recognition (OCR) to convert the document into machine-encoded text that is appended to the default response. The parsed data makes it faster to process the document without having to manually review or apply OCR after retrieving the document.
Add the with_parsed_data=true query parameter to retrieve the tax form with parsed data. If parsed data is requested, but we are unable to provide the parsed data, the request will fail and can optionally be retried with query param with_parsed_data=false to retrieve the document only.
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
GET /v1/accounts/449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65/tax_forms/b0e92f7b-c0b2-4418-a34d-3f316ca45c84?with_parsed_data=true
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": "b0e92f7b-c0b2-4418-a34d-3f316ca45c84",
"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": "8b15fc92-4221-44bd-bac1-1121641ccffd",
"download_url": [tax forms download URL],
"download_url_expiration": "2022-07-18T17:47:52.782334+00:00"
},
"parsed_data": null,
"warnings": null
}
}
{
"data": {
"id": "b0e92f7b-c0b2-4418-a34d-3f316ca45c84",
"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": "8b15fc92-4221-44bd-bac1-1121641ccffd",
"download_url": [tax forms download URL],
"download_url_expiration": "2022-07-18T17:47:52.782334+00:00"
},
"parsed_data": {
"box_a": "XXX-XX-1234",
"box_b": "123456789",
"box_c": {
"name": "SAMPLE COMPANY INC",
"address": {
"raw": "123 MAIN ST, ANYWHERE, CA 123456 1234",
"line1": "123 MAIN ST",
"line2": null,
"city": "ANYWHERE",
"state": "CA",
"postal_code": "123456",
"country": "US"
}
},
"box_d": "000011 R#/123",
"box_e": "JOHN SMITH",
"box_f": {
"raw": "1234 S MAPLE ST, ANYWHERE, CA 123456",
"line1": "1234 S MAPLE ST",
"line2": null,
"city": "ANYWHERE",
"state": "CA",
"postal_code": "123456",
"country": "US"
},
"box_1": 2350000,
"box_2": 150000,
"box_3": 2350000,
"box_4": 145700,
"box_5": 2350000,
"box_6": 34057,
"box_7": null,
"box_8": null,
"box_9": null,
"box_10": null,
"box_11": null,
"box_12": [
{
"code": "W",
"amount": 50000
},
{
"code": "DD",
"amount": 2100
}
],
"box_13": {
"statutory_employee": false,
"retirement_plan": false,
"third_party_sick_pay": false
},
"box_14": null,
"box_15_to_20": [
{
"box_15_state": "CA",
"box_15_employer_state_id": "12345678901ABC",
"box_16": 2350000,
"box_17": 80000,
"box_18": null,
"box_19": null,
"box_20": null
}
]
},
"warnings": null
}
}
Interested in integrating tax forms into your workflow? Reach out to [email protected] for access today!
Updated over 1 year ago