Events

Events represent activity that has occurred within Chart or within third-party tax providers. Your app can sync the data via either the events API or webhooks.

Event objects

All event objects share a similar structure.

Attribute	Description
event	A string that distinguishes the event type.
id	Unique identifier for the event.
data	Event payload.
created_at	Timestamp of when the event occurred.

Events emitted when end users (taxpayers) interact with Chart Connect widget.

Widget failed event

{
    "event": "widget.failed",
    "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
    "data": {
        "error": {
            "code": "provider_timeout",
            "message": "Provider timed out."
        }
    },
    "created_at": "2021-08-17T03:29:59.397Z"
}

Client Link events

Events emitted when end users (taxpayers) interact with the no-code client links.

Client link opened event

{
    "event": "client_link.opened",
    "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
    "data": {
        "url": "https://dashboard.trychartapi.com/c/test"
    },
    "created_at": "2021-08-17T03:29:59.397Z"
}

Client link closed event

{
    "event": "client_link.closed",
    "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
    "data": {
        "url": "https://dashboard.trychartapi.com/c/test"
    },
    "created_at": "2021-08-17T03:29:59.397Z"
}

Client link failed event

{
    "event": "client_link.failed",
    "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
    "data": {
        "error": {
            "code": "provider_timeout",
            "message": "Provider timed out."
        }
    },
    "created_at": "2021-08-17T03:29:59.397Z"
}

Client link succeeded event

{
    "event": "client_link.succeeded",
    "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
    "data": {
        "provider_id": "turbotax"
    },
    "created_at": "2021-08-17T03:29:59.397Z"
}

Taxpayer events

These events are emitted to identify the specific actions a taxpayer has taken in Chart’s user interface and also to identify events related to a taxpayer that is not user-initiated such as when a taxpayer is deleted from Chart’s database.

Taxpayer provider selected event

{
    "event": "taxpayer.provider_selected",
    "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
    "data": {
        "provider_id": "turbotax"
    },
    "created_at": "2021-08-17T03:29:59.397Z"
}

Taxpayer provider connected event

{
    "event": "taxpayer.provider_connected",
    "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
    "data": {
        "provider_id": "turbotax"
    },
    "created_at": "2021-08-17T03:29:59.397Z"
}

Taxpayer provider timed out event

{
    "event": "taxpayer.provider_timed_out",
    "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
    "data": {
        "provider_id": "turbotax"
    },
    "created_at": "2021-08-17T03:29:59.397Z"
}

Taxpayer disconnected event

{
    "event": "taxpayer.disconnected",
    "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
    "data": {
        "taxpayer_id": "tx_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
        "name": "John Doe",
        "provider_id": "turbotax"
    },
    "created_at": "2021-08-17T03:29:59.397Z"
}

Tax Record events

Tax record created event

{
    "event": "tax_record.created",
    "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
    "data": {
        "access_token": "access_token",
        "record_id": "record_id",
        "tax_year": 2021,
        "provider_id": "turbotax"
    },
    "created_at": "2021-08-17T03:29:59.397Z"
}

IRS Form events

IRS Form flow is the only non-realtime provider. On average, it takes 2-3 days for the IRS to process the form and give authorization to Chart to pull the taxpayers’ data. The events below reflext the stages of the IRS Form flow.

IRS Form consent received event

{
    "event": "irs_form.consent_received",
    "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
    "data": {
        "taxpayer_id": "tx_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
        "form": {
            "isPersonal": true,
            "personalInfo": {
                "firstName": "John",
                "lastName": "Doe",
                "email": "john.doe@example.com",
                "ssn": "123456789"
            },
            "businessInfo": {
                "name": "Test, Inc.",
                "taxId": "123456789",
                "type": "S-Corporation",
                "phone": "1112223344",
                "title": "CEO"
            },
            "address": {
                "street": "123 Main St",
                "other": "Apt 1",
                "city": "San Francisco",
                "state": "CA",
                "zip": "94101"
            }
        }
    },
    "created_at": "2021-08-17T03:29:59.397Z"
}

IRS Form submitted event

{
    "event": "irs_form.submitted",
    "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
    "data": {
        "taxpayer_id": "tx_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
        "form": {
            "isPersonal": true,
            "personalInfo": {
                "firstName": "John",
                "lastName": "Doe",
                "email": "john.doe@example.com",
                "ssn": "123456789"
            },
            "businessInfo": {
                "name": "Test, Inc.",
                "taxId": "123456789",
                "type": "S-Corporation",
                "phone": "1112223344",
                "title": "CEO"
            },
            "address": {
                "street": "123 Main St",
                "other": "Apt 1",
                "city": "San Francisco",
                "state": "CA",
                "zip": "94101"
            }
        }
    },
    "created_at": "2021-08-17T03:29:59.397Z"
}

IRS Form accepted event

{
    "event": "irs_form.accepted",
    "id": "ev_2bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
    "data": {
        "taxpayer_id": "tx_2bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
        "tin": "123456789",
        "first_name": "John",
        "last_name": "Doe",
        "business_name": "Test, Inc.",
        "is_business": true
    },
    "created_at": "2021-08-18T03:29:59.397Z"
}

IRS Form rejected event

{
    "event": "irs_form.rejected",
    "id": "ev_3bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
    "data": {
        "taxpayer_id": "tx_3bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5",
        "rejection_reason": "Invalid SSN"
    },
    "created_at": "2021-08-19T03:29:59.397Z"
}

How Chart Works

Implementation Guide

Developer Resources

Event objects

Widget events

Client Link events

Taxpayer events

Tax Record events

IRS Form events

How Chart Works

Implementation Guide

Developer Resources

​Event objects

​Widget events

​Client Link events

​Taxpayer events

​Tax Record events

​IRS Form events

Event objects

Widget events

Client Link events

Taxpayer events

Tax Record events

IRS Form events