# Create Client Link Source: https://developer.trychart.com/api-reference/client-links/post POST /client-links Create a custom client link. # Download Unsigned Form 8821 Source: https://developer.trychart.com/api-reference/irs-8821-form/unsigned POST /providers/irs/f8821/unsigned Download an unsigned IRS Form 8821. # Upload Signed Form 8821 Source: https://developer.trychart.com/api-reference/irs-8821-form/upload POST /providers/irs/f8821/upload/{documentId} Upload a wet-signed IRS Form 8821 PDF file # Get Access Token Source: https://developer.trychart.com/api-reference/management/access_token GET /auth/tax-payer/{id}/token Get the access token for a taxpayer. In certain cases such as client links, you may not have access to the `access_token` created for the taxpayer. However, all Chart endpoints returning sensitive taxpayer data require an `access_token`. This endpoint allows you to retrieve the `access_token` using your Chart `client_id` and `client_secret`. **Important:** This endpoint should be used sparingly and only when absolutely necessary. Please reach out to Chart support if you need to use this endpoint frequently. # Disconnect Source: https://developer.trychart.com/api-reference/management/disconnect POST /disconnect Disconnect one or more `access_token`s from your application. Deletion is based on both the taxpayer and provider of the `access_token` used to call this endpoint, and will also delete all tokens with the same taxpayer/provider pair. Other tokens for the same taxpayer, but connected to a different provider, require a separate call. We require applications to implement the Disconnect endpoint for billing and security purposes. # Introspect Source: https://developer.trychart.com/api-reference/management/introspect GET /introspect Read account information associated with an `access_token`. # Providers Source: https://developer.trychart.com/api-reference/management/providers GET /providers Return details on all available tax record providers. # Create Access Token Source: https://developer.trychart.com/api-reference/management/token POST /auth/token Exchange authorization code for access token. Exchange the authorization code for an access token # Get Record Source: https://developer.trychart.com/api-reference/records/get GET /records/{id} List details about a given tax record. # Get All Records Source: https://developer.trychart.com/api-reference/records/get_all GET /records Returns all tax records associated with an `access_token`. # Clear Taxpayer Records Source: https://developer.trychart.com/api-reference/taxpayer/clear-records POST /tax-payer/clear-records Clear all tax records associated with a taxpayer. Clear all tax records associated with a taxpayer. This endpoint requires authentication through a valid `access_token` and will remove all tax records for the associated taxpayer without deleting the taxpayer account. # Taxpayer Source: https://developer.trychart.com/api-reference/taxpayer/get GET /tax-payer Retrieve taxpayer information associated with an `access_token`. # Refresh Taxpayer Source: https://developer.trychart.com/api-reference/taxpayer/refresh POST /tax-payer/{id}/refresh Refresh taxpayer data. # Refresh Taxpayer Status Source: https://developer.trychart.com/api-reference/taxpayer/refresh-status GET /tax-payer/{taxpayerId}/refresh/{jobId} Get the status of a refresh job. # API Versioning Source: https://developer.trychart.com/developer/api-versioning We periodically release new, dated versions of the API whenever we make breaking changes. Although we try to only make backward-compatible changes, sometimes we have to make a breaking change to iterate on the API. **We consider the following changes backward compatible:** * Adding new API endpoints * Adding new optional parameters to existing endpoints * Adding new data elements to existing responses * Adding new errors Our current version is **2024-01-01** The `Chart-API-Version` header must be set for every single request to our API. # Changelog Source: https://developer.trychart.com/developer/changelog Track the changes made to Chart API over time. Introducing one-off links for ad hoc tax record collection! Users can now create unique links to send to their end users via email, phone, or other channels. This feature requires no integration, making it perfect for ad hoc collection of tax records. It simplifies the process of gathering tax information without the need for complex setups or technical implementations. Chart is now an official participant of the IRS Transcript Delivery System (TDS)! This integration allows us to electronically submit Tax Information Authorizations using Form 8821. With this capability, we can now provide full coverage for any individual or business taxpayer, streamlining the process of accessing and managing tax information for our users. We've added support for IRS Online Accounts! End users can now log in to their IRS online account directly through Chart, allowing our API to easily retrieve tax transcripts. This streamlines the process of accessing official tax records for individuals and businesses. Our API Docs have a new look! Use our [API Reference](/api-reference) for a deep-dive into the details and structure of our API, and our [Documentation](/) for introductions to our products, implementation guides, and best practices. Professional tax prep software is used for majority of C-corp and enterprise companies. Chart will soon incorporate all of the major cloud-based software, starting with CCH Axcess. End users can now redirect their link to their tax preparer to sync their returns. Major tax preparation software providers for individual returns added to Connect.
Current provider list: # Events Source: https://developer.trychart.com/developer/events Respond to activity that occurs within Chart and third-party providers. 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. | ### Taxpayer events Events emitted when data about a taxpayer changes such as when a taxpayer's status changes, a taxpayer is disconnected from a provider, or a taxpayer's records are synced. ```json Taxpayer status changed event theme={null} { "event": "taxpayer.status_changed", "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5", "data": { "taxpayer_id": "tx_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5", "status": "COMPLETED", "status_description": "Taxpayer completed the onboarding process", "provider_id": "turbotax" }, "created_at": "2021-08-17T03:29:59.397Z" } ``` ```json Taxpayer records synced event theme={null} { "event": "taxpayer.records_synced", "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5", "data": { "taxpayer_id": "tx_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5", "provider_id": "turbotax" "records": [ { "record_id": "record_id", "tax_year": 2021, } ] }, "created_at": "2021-08-17T03:29:59.397Z" } ``` ```json Taxpayer disconnected event theme={null} { "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" } ``` ### Widget events Events emitted when end users (taxpayers) interact with Chart Connect widget. ```json Widget opened event theme={null} { "event": "widget.opened", "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5", "data": {}, "created_at": "2021-08-17T03:29:59.397Z" } ``` ```json Widget closed event theme={null} { "event": "widget.closed", "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5", "data": {}, "created_at": "2021-08-17T03:29:59.397Z" } ``` ```json Widget failed event theme={null} { "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. ```json Client link opened event theme={null} { "event": "client_link.opened", "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5", "data": { "url": "https://dashboard.trychart.com/c/test" }, "created_at": "2021-08-17T03:29:59.397Z" } ``` ```json Client link closed event theme={null} { "event": "client_link.closed", "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5", "data": { "url": "https://dashboard.trychart.com/c/test" }, "created_at": "2021-08-17T03:29:59.397Z" } ``` ```json Client link failed event theme={null} { "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" } ``` ```json Client link succeeded event theme={null} { "event": "client_link.succeeded", "id": "ev_1bxJqfif_-EJjbl9DNwilJCt5D2tC5Q5", "data": { "provider_id": "turbotax" }, "created_at": "2021-08-17T03:29:59.397Z" } ``` # SDKs Source: https://developer.trychart.com/developer/sdk Explore our frontend and backend (_coming soon_) SDK repositories. ## Frontend SDKs Chart's frontend SDKs allow you to [embed Chart Connect](/implementation/connect/set-up-chart-connect#embedded-chart-connect) into your application, enabling you to provide a seamless integration experience for your users. Take a look at our repositories below: If you do not see your language here, reach out to us! # Webhooks Source: https://developer.trychart.com/developer/webhooks A step-by-step guide on how to start syncing data using webhooks. ## What you'll build In this guide, we will walk you through what you will need to set up webhooks: * Create your endpoint to receive webhook events * Register your endpoint with Chart * Process the events received from Chart * Test your endpoint ## 1. Set up your webhook endpoint Create a public endpoint that Chart can send events to. This endpoint should use HTTPS and should accept POST requests with the `chart-signature` header. ```javascript Next.js theme={null} import type { NextApiRequest, NextApiResponse } from "next"; export default (req: NextApiRequest, res: NextApiResponse) => { if (req.method === "POST") { const payload = req.body; const sigHeader = req.headers["chart-signature"]; // Verify the signature and process the event res.status(200).end(); } }; ``` ```javascript Express theme={null} const express = require("express"); const app = express(); app.use(express.json()); app.post("/webhook", (req, res) => { const payload = req.body; const sigHeader = req.headers["chart-signature"]; // Verify the signature and process the event res.sendStatus(200); }); ``` Chart sends the header as Chart-Signature, but many web servers normalize HTTP request headers to their lowercase variants. ## 2. Register your endpoint Set and save the webhook URL in the [Chart Dashboard](https://dashboard.trychart.com), so Chart knows where to deliver the events. Your webhook endpoints should only be configured to receive the ones required by your integration. Receiving all event types can put undue strain on your servers and is not recommended. ## 3. Process the events In order to avoid unnecessary retry requests hitting your webhook handler, we recommend using two concurrent processes for handling events: one for receiving the event, and the other for processing it. ### Respond with HTTP 200 OK On receiving an event, you should respond with an `HTTP 200 OK` to signal to Chart that the event was successfully delivered. Otherwise, Chart will consider the event delivery a failure and retry up to 12 times, with exponential backoff over 3 days. You do not need to signal to Chart whether or not the event was processed successfully. ### Validate the requests Before processing the request payload, verify the request was sent by Chart and not an unknown party. Chart includes a unique signature in each webhook request that it sends, allowing you to verify the authenticity of the request. In order to verify this signature, you must obtain the secret that is generated for you when you set up your webhook endpoint in the Chart dashboard. Ensure that this secret is stored securely on your webhook endpoint server as an environment variable. To implement webhook validation, you'll need to use the following steps: First, extract the timestamp and signature from the header. There are two values to parse from the `Chart-Signature`header, delimited by a `,` character. | Key | Value | | ----------------- | ----------------------------------------------------------------------------------------------- | | issued\_timestamp | The number of milliseconds since the epoch time at which the event was issued, prefixed by `t=` | | signature\_hash | The HMAC SHA256 hashed signature for the request, prefixed by `v1=` | To avoid replay attacks, we suggest validating that the `issued_timestamp` does not differ too much from the current time. Next, construct the expected signature. The expected signature is computed from the concatenation of: 1. `issued_timestamp` 2. The `.` character 3. The request's body as a utf-8 decoded string Hash the string using HMAC SHA256, using the webhook secret as the key. The expected signature will be the hex digest of the hash. Finally, compare signatures to make sure the webhook request is valid. Once you've determined the event request is validly signed, it's safe to use the event payload in your application's business logic. ## 4. Test your endpoint From the dashboard, you can send test webhook events after configuring an endpoint. Go to the webhook endpoint detail page, click on **Send Test Event**. The types of events that you have configured for your endpoint are available for you to send sample payloads. If you would like to test against your local development environment, we recommend using a tool like [ngrok](https://ngrok.com/) to create a secure tunnel to your local machine, and sending test webhooks to the public endpoint generated with ngrok. ## Best practices ### Respond to events immediately To avoid webhook requests potentially stressing your system, Chart strongly recommends that you respond to a webhook request with a 200 OK response as quickly as possible once received. If you process the event before responding, your system may not be able to handle a spike of requests. This may cause requests to timeout and result in missing important updates. A common pattern is to store the request payload on a message queue, respond with a 200 OK response, and use a background worker to process the messages in the queue. ### Recover from failed events If your endpoint fails to respond to a webhook request with a `2xx` response, Chart will automatically retry the event with exponential back-off for up to 3 days in production environments. If for some reason your endpoint is still unable to respond successfully to events during that period, the event will be considered failed, and we will no longer retry sending it. ### Handle out-of-sequence events Chart does not guarantee that events are delivered in the same sequence that they are generated. For example, when a taxpayer going thru Chart Connect UI, you may receive: * `taxpayer.consent_accepted` * `taxpayer.provider_selected` * `taxpayer.provider_connected` Your endpoint should handle cases when these events are delivered out of order. Each event includes the full payload of the objects involved, so you can perform an upsert using the payload data. It is also possible that event data can be stale due to a retry of an older event being delivered after a newer event for the same object. Therefore, we recommend checking the timestamp of the incoming webhook data against the timestamp of the data in your system to ensure you do not overwrite your data with stale data. Each object in the payload includes a `created_at` field and an `updated_at` field. ### Ignore duplicate events It is possible to receive the same event more than once. Chart recommends that you handle webhook events using idempotent operations. One way of doing this is logging the ID of webhook events that you have processed and ignoring subsequent requests with the same ID. ### Obfuscate your endpoint URL A small security measure you can incorporate is to make your webhook endpoint difficult to guess. Including a token comprised of series of random numbers and letters to your endpoint URL can prevent malicious actors from easily guessing your endpoint. For example: [https://api.example.com/webhooks/n0dbga5x…](https://api.example.com/webhooks/n0dbga5x…) is much more difficult to guess than [https://api.example.com/webhooks](https://api.example.com/webhooks) # Create a Chart Developer Account Source: https://developer.trychart.com/implementation/connect/create-dev-account Create your Chart Developer Account, recieve your application credentials, and pilot how Chart works. To get started using the Chart APIs, sign up for a free Chart Developer account to receive application credentials (a `client_id` and `client_secret`) and pilot how Chart works. 1. Go to the [Chart Developer Dashboard](https://dashboard.trychart.com) and sign up for a new account. You'll need to provide your name, company name, email address, and create a password. 2. Upon creating the application, you'll be provided with a `client_id` and `client_secret`. You will use these credentials to authenticate your application to obtain access tokens in order to call the Chart APIs. 3. Set up a secure method for storing your `client_id`, `client_secret`, and future `access_token`s to prevent unauthorized access. Here are some methods to securely store these credentials: - **Environment Variables**: Store your `client_id` and `client_secret` as environment variables within your application. When your application needs to use these credentials, it can access them from the environment variables without exposing them in your source code. - **Secure Database**: [Store the access tokens](/implementation/secure/store) in a secure database with proper encryption and access controls in place. Make sure to use a database that supports encryption at rest and in transit to ensure the security of the stored tokens. - **Secrets Management Solutions**: Utilize a specialized secrets management solution, such as HashiCorp Vault or AWS Secrets Manager. These tools provide additional layers of security, access control, and auditing capabilities to ensure the safe storage of your `client_id`, `client_secret`, and `access_token`. - When storing access tokens, also store any relevant metadata, such as the associated user ID. This will help you maintain data integrity and prevent mixing up tokens across different users. This topic is covered in more detail in [Store Tokens](/implementation/secure/store). 4. (Optional) if you are using the [Chart Connect Redirect Flow](/implementation/connect/set-up-chart-connect#redirect-to-chart-connect), specify any [Redirect URIs](#redirect-uris) for your application. This URL must be hosted on your own server or a trusted domain. Example: `https://your-trusted-domain.com/api/chart/callback` The [Chart Developer Dashboard](https://dashboard.trychart.com) is your centralized place to manage submitted tax records, review request activity, and set up webhook alerts. ## Redirect URIs To authorize with Chart, you'll need to provide one or more redirect URIs. The user will be redirected to the specified URI upon successfully authorizing your application access to their tax system. On redirect, the URI will contain an authorization `code` query parameter that must be exchanged with Chart's authorization server for an access token. Chart's embedded Frontend SDKs don't need to set up a redirect URI. The default redirect URI `https://trychart.com` is already applied. The redirect URIs must match one of the following formats— | Protocol | Format | Examples | | -------- | --------------------------------------- | ----------------------- | | HTTP | A localhost URI with protocol `http://` | `http://localhost:8000` | | HTTPS | A URI with protocol `https://` | `https://example.com` | ## Checkpoint + Next Step After completing this step, you should have registered for a Chart Developer Dashboard account using your unique `client_id` and `client_secret`. You now have everything necessary to [Set Up Chart Connect](/implementation/connect/set-up-chart-connect) to begin connecting to tax providers. # Retrieve Access Token Source: https://developer.trychart.com/implementation/connect/retrieve-access-token In this guide, you'll exchange the authorization code for an access token. Access tokens are required for making API requests to Chart endpoints. Now that you have successfully [integrated Chart Connect](/implementation/connect/set-up-chart-connect) into your application's frontend and obtained an authorization code, you will need to exchange it for an access token. Access tokens are required for making API requests to Chart's various endpoints. In this step, you'll set up a secure server-side process to exchange the authorization code for an access token. 1. **Create a server-side “callback” endpoint**: Set up a secure server-side endpoint in your application to handle the exchange of authorization codes for access tokens. This endpoint should be accessible only by your application's backend to ensure the security of the process. This endpoint will receive the authorization code as a query parameter from your frontend and communicate with Chart's API to obtain the access token. Example: `https://example.com/api/chart/callback`. > You can reuse this same endpoint to support a Redirect Chart Connect flow as well. > Just make sure to add the `redirect_uri` to the whitelist in your Chart Developer Dashboard. 2. **Exchange the authorization code for an access token**: In your server-side code, make a POST request to the `/auth/token` endpoint. The request should include the following fields in the request body's JSON payload: * `client_id`: Your unique client ID from the Chart developer dashboard. * `client_secret`: Your unique client secret from the Chart developer dashboard. * `code`: The authorization code obtained from Chart Connect in the [Set Up Chart Connect](/implementation/connect/set-up-chart-connect). * `redirect_uri` (optional): If using the Redirect Chart Connect Flow, include the `redirect_uri`. Not required for the Embedded Flow. This is the same redirect URI you used when setting up Chart Connect. If you using Embedded Flow, do not include `redirect_uri` in the payload. ```shell Token exchange example theme={null} curl https://api.trychart.com/auth/token \ -X POST \ -H "Content-Type: application/json" \ --data-raw '{ "client_id": "", "client_secret": "", "code": "" }' ``` **Optional Header for Async Processing** You can add the optional `x-chart-async: "true"` header to prevent network timeouts during long document parsing operations: ```shell Token exchange with async header theme={null} curl https://api.trychart.com/auth/token \ -X POST \ -H "Content-Type: application/json" \ -H "x-chart-async: true" \ --data-raw '{ "client_id": "", "client_secret": "", "code": "" }' ``` We recommend adding the `x-chart-async: "true"` header to avoid network timeouts when parsing takes longer than expected. **Important Caveat**: When using the `x-chart-async: "true"` header, the token exchange will return immediately after pulling documents from the provider, without waiting for parsing to complete. This means there's no longer a guarantee that tax records are fully parsed when the API call ends. You must wait for the `taxpayer_status` to change to `COMPLETED` through webhooks before you can reliably access the parsed JSON data of the retrieved documents. 3. **Handle the response**: Chart's `/auth/token` endpoint will respond with a JSON object containing an `access_token` if the request is successful. Parse the JSON response body and extract the `access_token`. ```javascript theme={null} { "taxpayer_id": "ac3a2af9-ce03-46c4-9142-81abe789c64d", "provider_id": "turbotax", "access_token": "7e965183-9332-423c-9259-3edafb332ad2" } ``` 4. **Securely store the access token**: It is critical to store access tokens securely, as they grant access to sensitive user data. Implement a secure storage solution to store access tokens, treating them with the same level of security as passwords. Do not log or expose access tokens to your frontend application. Storing access tokens is covered in more depth in Store Tokens. 5. **Handle errors**: If the `/auth/token` endpoint returns an error, your server-side code should handle it gracefully. Common error scenarios include invalid or expired authorization codes, incorrect client IDs or secrets, or mismatched redirect URIs. Display a helpful error message to the user or retry the authentication flow as needed. ## Checkpoint + Next Step After completing this step, your application will be able to exchange authorization codes for access tokens securely and automatically. You are ready to use the access token to make API requests to Chart's various endpoints. # Set Up Chart Connect Source: https://developer.trychart.com/implementation/connect/set-up-chart-connect In this guide, you'll integrate Chart Connect into your application's frontend. Now that your application is [registered with Chart](/implementation/connect/create-dev-account), it's time to integrate Chart Connect into your application's frontend. Chart Connect is the user-facing authentication flow that allows your users to securely input their tax system credentials to establish a connection with their provider. This prerequisite step is crucial before obtaining access tokens to make API requests. Chart Connect is configurable with the following parameters: | Parameter | Required | Description | | -------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `client_id` | true | Your `client_id`, a unique identifier for your application. | | `redirect_uri` | redirect only | The URI your user is redirected to after successfully granting your application access to their system. This value must match one of your application's configured [redirect URIs](/implementation/connect/create-dev-account#redirect-uris). | | `state` | optional | An optional value included as a query parameter in the response back to your application. This value is often used to identify a user and/or prevent cross-site request forgery. | Chart provides two options to setup Chart Connect: [Redirect](#redirect-to-chart-connect) or [Embedded](#embedded-chart-connect). ## Implementing Chart Connect in your application 1. **Choose your preferred flow**: Chart provides several Frontend SDKs for easy integration. Select the SDK that best suits your application's technology stack. Otherwise, you can use the Redirect flow. * [React SDK](https://github.com/getcharteditor/react-connect): If you're using React as your frontend framework, use the React SDK. Import the Chart Connect component and include it in your application. You can find examples and usage instructions in the SDK documentation or continue to follow this tutorial. * `npm install --save @chartapi/react-connect` * `yarn add @chartapi/react-connect` * JavaScript SDK: If you're using a different frontend framework or vanilla JavaScript, use the pure JavaScript SDK. Include the Chart Connect library in your application, either by adding a script tag to your HTML file or by importing it as a module. * `` > Since Chart Connect is an iFrame that requires interactivity, > the HTML page that is loading Chart Connect must be served from a server. > If the page is hosted statically, Chart Connect will not work properly. * [Redirect Flow](#redirect-to-chart-connect): The redirect flow is helpful in instances where you do not have a user interface (such as a link in an email) or you prefer to redirect in order to not host the authorization experience yourself. 2. **Configure Chart Connect**: Every flow requires you to configure Chart Connect with your unique `client_id`. You can find this `client_id` in your [Chart Developer Dashboard](https://dashboard.trychart.com). ## Redirect to Chart Connect In this method of integrating Chart Connect, your application redirects your user's browser to Chart Connect hosted by Chart on `https://connect.trychart.com`. After a successful connection, Chart Connect will redirect your user back to a URI you specified (`redirect_uri`) with a short-lived authorization `code`. Set the `redirect_uri` parameter to the URL where users will be redirected after completing the authentication flow. The `redirect_uri` must be set in the [Chart Developer Dashboard](https://dashboard.trychart.com). Otherwise, the request will fail. ```shell theme={null} https://connect.trychart.com? client_id= &redirect_uri=https://example.com ``` The redirect authorization flow consists of four steps: 1. **Open Chart Connect** — Your application redirects your user's browser to Chart Connect to initiate the authorization flow. 2. **Obtain consent** — Chart Connect prompts your user to log in to their tax system and grant your application access to the permissions you are requesting. 3. **Retrieve the authorization code** — If your user successfully connects and grants your application access to their system, Chart Connect will redirect their browser to a specified `redirect_uri` with a short-lived authorization `code`. 4. **Exchange the code for an access token** — Before sending API requests, your application will exchange the short-lived code for a long-lived `access_token` that represents your application's access to your user's tax system. ## Embedded Chart Connect The Chart-provided SDK embeds the Chart Connect screen into your application. The user will remain entirely on your application throughout the process. When the `onSuccess` event is called by the SDK, simply pass the `code` to your internal callback endpoint as a query parameter. > NOTE: You should not include a `redirect_uri` if using the embedded flow. > Because the entire flow is already self-contained in your app, no redirect is necessary. ```jsx React theme={null} import React, { useState } from "react"; import { useChartConnect } from "@chartapi/react-connect"; const App = () => { const [code, setCode] = useState(null); const onSuccess = ({ code }) => setCode(code); const onError = ({ errorMessage }) => console.error(errorMessage); const onClose = () => console.log("User exited Chart Connect"); // 1. Initialize Chart Connect const { open } = useChartConnect({ clientId: "", state: "", // optional onSuccess, onError, onClose, }); // ... }; ``` ```html JavaScript theme={null} ``` **Implement the authentication flow**: Add a button or a link in your application that triggers the Chart Connect flow. Users will click this button or link to start the authentication process. ```jsx React theme={null} const App = () => { // ... // 2. Display Chart Connect return ( ); }; ``` ```html JavaScript theme={null} ``` **Listen for events**: Chart Connect emits events that your application should listen for to handle the different stages of the authentication process. The two most important events are `onSuccess` and `onError`. 1. `onSuccess`: This event is triggered when the user completes the authentication process. It returns an authorization `code` that you will use to obtain an `access_token` in the next step. Pass this authorization `code` securely and temporarily to the access token exchange function. 2. `onError`: This event is triggered if there's an issue during the authentication process. Your application should handle this error gracefully, either by displaying an error message to the user or retrying the authentication flow. 3. `onClose`: This event is triggered when a user exits the Chart Connect model, either by closing the modal or clicking outside the modal. ## Checkpoint + Next Step After completing this step, you will have successfully integrated Chart Connect into your application's frontend. This will enable users to authenticate with their tax systems, providing your application with the necessary authorization to [obtain an access token](/implementation/connect/retrieve-access-token) in the next step. ## Learn more * Chart SDKs # Chart API Implementation Guide Source: https://developer.trychart.com/implementation/guide In this integration guide, you will sign up for a Chart Account, set up Chart Connect, integrate the Chart API, and go into production. Chart's developer-friendly Unified Tax API makes implementation simple and straightforward. 1. [Sign up for a free account](/implementation/connect/create-dev-account) to receive credentials and pilot how Chart works. 2. [Integrate Chart Connect](/implementation/connect/set-up-chart-connect) into your frontend. (Chart Connect is the user inferface that allows your customers to safely and securely grant your application access to their tax systems.) You can opt to [redirect to Chart Connect](/implementation/connect/set-up-chart-connect#redirect-to-chart-connect) or [embed it directly](/implementation/connect/set-up-chart-connect#embedded-chart-connect) into your application. 3. Integrate the Chart API into your application's backend. 4. [Secure](/implementation/secure) your application to maintain a smooth user experience that is both efficient and protected while using Chart. 5. Once your integration has been tested thoroughly, go live with all of your customers. **Ready to get started? [Create An Account](https://auth.trychart.com/sign-up)** ## Frontend + Backend In a full implementation, Chart requires both a frontend and a backend application to exist. The frontend application coordinates connecting to tax systems, and the backend server securely manages the requests and responses to and from Chart APIs. ### Frontend User Interface Before being able to pull data from a tax provider through Chart, your customer needs to consent to the data being transferred. Without consent, Chart is not authorized to pull the data on behalf of the customer. Chart Connect is our user-facing product to help you obtain customer consent, and it is a prerequisite step before calling Chart APIs. There are two ways to integrate Chart Connect into your application's frontend user interface. 1. Your application can [embed Chart Connect](/implementation/connect/set-up-chart-connect#embedded-chart-connect) using our various [frontend SDKs](/developer/sdk). Embedding Chart Connect allows your customer to remain on your application's domain during the entire connection process. 2. Your application can [redirect to Chart Connect](/implementation/connect/set-up-chart-connect#redirect-to-chart-connect) from the customer's browser. In this case, Chart Connect is securely hosted by Chart on `https://connect.trychart.com` instead of your application. After completion, they will be redirected to a URI that you specify. ### Backend Security Chart takes security seriously, so we require a backend server to manage all requests and responses to and from Chart APIs. Once the connection has been created via Chart Connect, you can obtain an `access_token` which will be used to call the Chart APIs. We require a backend for several reasons: 1. Since the data from tax data providers is sensitive, making API requests from the backend and storing that data on the backend reduces the likelihood of this data being exposed to malicious persons. 2. Exchanging the authorization code for an access\_token should always take place in your backend to ensure your `client_secret` and `access_token` are never publicly exposed. 3. Likewise, your backend should always [store the access token](/implementation/secure/store) in a secure database and should never return the access token to the frontend application. **Ready to get started? [Create An Account](https://auth.trychart.com/sign-up)** # Store Tokens Source: https://developer.trychart.com/implementation/secure/store Explore our best practices for storing access tokens securely. Chart requires developers to store tokens on the backend server for improved security controls. To reduce the likelihood of unitentional exposure of taxpayer access tokens or other private information, you'll need to ensure all access tokens are stored securely. Chart access tokens are “keys” to sensitive information. You should treat access tokens with the same level of security as you would passwords. ## Secure storage best practices Storing tokens securely should be done on the backend (server-side) of your application, not on the frontend (client-side). A frontend application is more susceptible to potential security threats such as Cross-Site Scripting (XSS) attacks or unauthorized access if the client is compromised. Therefore, **Chart requires developers to store tokens securely on the backend server** where you have better control over access and security. No application is 100% secure, but there are ways to reduce the potential of an exposure (and its impact) by following a few best practices: 1. Store tokens on the backend of your application. 2. Encrypt the access token before storing it. 3. Use environment variables or a secure configuration management system to store static sensitive information that needs to be referenced like `client_secret`. 4. Never store access tokens in code files or easily accessible directories with human access. 5. Ensure that tokens are not exposed in URLs, logs, or error messages. 6. Keep all server-side components, libraries, and frameworks up-to-date with security patches to mitigate potential vulnerabilities. Determine the best method for securely storing access tokens in your application's backend. Reference the sections below if you need additional help. ## Encryption To add an extra layer of security, you can encrypt the access token before storing it. Select a strong symmetric encryption algorithm, such as AES-256. Avoid using weak algorithms like DES, as they are susceptible to brute-force attacks due to its small key size (56 bits). ## Never expose access tokens Ensure that tokens are not exposed in URLs, log files, or error messages. Regularly review logs for any exposure. Ensure your frontend application never receives the access token to avoid incidental exposure. Your frontend, client-side application should only receive tax data, never the token itself. # What is Chart? Source: https://developer.trychart.com/overview/chart-overview Integrate with the Chart API to easily collect verified federal and state tax records in real time. Chart is a Unified Tax Collection API that enables you to build a single integration with Chart and instantly sync access customers' tax records in a structured format. Once Chart is integrated into your application, you can access your customers' tax transcripts, full tax returns and the documents they filed to tax agencies. Chart works by allowing your customers (tax payers) to connect their tax record systems (IRS online account, state tax agency websites, tax prep tools, etc.) to your application. This connection process is facilitated through **Chart Connect**, our tax payer-facing user interface which provides an elegant and secure authorization flow where your customers (tax payers) select their provider, and authorize access to their tax record systems. Upon a successful connection, Chart will issue an access token to your application which is used to make API requests to Chart API endpoints. ## Chart Connect Tax payers connect their data to your application in 3 easy steps, facilitated through **Chart Connect**. * **Prioritize privacy**: Chart Connect discloses data privacy practices right from the start, so your customers know where and how their data is used. Chart only shares data that has been approved. * **Select a provider**: Once the user approves, they select their tax record system from Chart's list of providers. * **Authenticate access**: The user is prompted to log into their account (via credentials or API key if available), granting your application access to their tax record data. # Connect a Taxpayer Source: https://developer.trychart.com/overview/connect Chart Connect is an embedded onboarding flow that enables tax payers to connect their tax record system in 30 seconds. In order to recieve data from any tax record system, you'll first need to connect a tax payer. Chart Connect is an embedded onboarding flow that enables tax payers to connect their data in 30 seconds through the following steps. Tax payers access Chart Connect from within your application. We suggest launching Chart Connect during the tax payer onboarding process. * **Read privacy disclosures** - Chart Connect discloses data privacy practices right from the start, so your customers know where and how their data is used. * **Select a provider** - Once the user approves, they select their tax record system from Chart's list of providers. * **Authenticate access** - The user is prompted to log into their account (via credentials or API key if available), granting your application access to their tax record data. That's it! Upon successful authentication, Chart Connect closes and redirects back to your application. Once the connection is established, you will recieve a Chart access token and can call the Chart API. At this point you can assure your users that the connection has been set up successfully, and redirect them to other tasks. # Quickstart Source: https://developer.trychart.com/overview/quickstart This API Quickstart guide will help you send your first request to Chart, the unified API for tax records. To get started, sign up for a free account [here](https://auth.trychart.com/sign-up). After registration, you will have access to a sandbox application `client_id` and `client_secret` to build and test how Chart works using simulated data. This `client_id` and `client_secret` will only work for the sandbox provider. If you would like to test real providers with live data, you must request developer keys from [developers@trychart.com](mailto:developers@trychart.com).