GuidesAPI ReferenceChangelog
Log In

Tax forms webhook events will notify you when new tax forms data is available for a payroll account or a tax forms job completed.

tax_forms.added

Tax forms data for the payroll account is available. Use account_id in the payload to query the Get Tax Form endpoint to fetch the data.

Payload Schema

Payload ParamTypeDescription
account_idstringUUID of the payroll account.
end_user_idstringThe user identifier you specified when the user initially connected to the payroll account, if provided.
outcomestringThe outcome of the job, either success, error, or pending. If pending you will receive another webhook with outcome as success or error within 24 hours.
error_code (optional)stringOn error, a string describing the error.
error_type (optional)stringOn error, a high level classification of the error.
params (optional)objectParameters of the job, if applicable.
timestampstringISO 8601 timestamp of job completion.
namestringName of the job, which is tax_forms.
link_token_idstringUUID of Link token used to initialize Link, or an undefined link token if triggered by a refresh job (such as from Monitoring). You should use account_id as the main identifier.
addedarrayA list of objects specifying ID, year, and form type of the new tax forms that were added to the payroll account.
deletedarrayA list of objects specifying ID, year, and form type of the old tax forms that were removed from the payroll account.
idstringDeprecated. UUID of the job. You should use account_id as the main identifier.

Sample Webhook Event

{
    "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"
        }]
    }
}