Verix

Developer Hub

Welcome to the Verix developer hub. You'll find comprehensive guides and documentation to help you start working with Verix as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

End-User Authentication

Client-Side Connect Configuration

End-users interact with the Verix Connect module, and through that module, initiate the request to pull their tax return transcripts with all the necessary information needed for authentication. Connect opens up a modal that your app talks to and is integrated using a pure JavaScript approach that you trigger via your own client-side code. Upon successful end-user authentication and creation of a collection of tax_return objects, Connect returns a code, which you can specify callbacks to handle. A standard Connect configuration appears as follows:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <link rel="stylesheet" type="text/css" href="https://app.verixapi.com/connect.css">
    <script src="https://app.verixapi.com/connect.js"></script>
    <script>
      const load = () => {
        const configuration = {
          clientId: "INSERT_PROJECT_CLIENT_ID",
          environment: "sandbox",
          optionalData: {
            name: {
              first: "Ben",
              last: "Smith"
            },
            email: "[email protected]",
            birthdate: {
              month: 11,
              day: 3,
              year: 1964
            },
            mobileNumber: "9394442113",
            socialSecurityNumber: "344675890",
            filingAddress: {
              address: "744 Evergreen Terrace",
              address2: "",
              city: "Springfield",
              state: "OR",
              zip: "97403"
            },
            filingStatus: "Married Filing Jointly"
          }
        };
        const verix = new Verix(configuration);
        verix.launch();
        verix.success(function(results) {
          console.log("User successfully completed connect flow!");
          console.log("Transaction ID: " + results.transactionId);
          console.log("Authorization Code: " + results.code);
          console.log("Expires At: " + new Date(results.expirationAt * 1000));
        });
        verix.cancel(function(results) {
          console.log("User closed modal");
          console.log("Transaction ID: " + results.transactionId);
          console.log("Last page: " + results.lastPage);
          console.log("Last error: " + results.lastError);
        });
      } 
      window.onload = load; 
    </script>
  </head>
  <body>
  </body>
</html>

The Connect configuration contains a few key variables (see above) to be aware of:

Type

Description

client_id (required)

A non-sensitive, public identifier that is unique to your account and is required to use Verix. The clientId is accessible via your developer dashboard.

environment (required)

This variable can be set as sandbox or development or production

optionalData (optional)

Connect collects all of the data fields from end-users but also allows you to prefill any of those fields if you have them already. By entering a value for any of the data fields, such as name, socialSecurityNumber, or address, the end-user will not need to re-enter that information.

Token Exchange

A code is returned in your Connect onSuccess() callback. This code, which expires in five minutes and is valid for one-time use, should be passed to your server. From your server, you can exchange the code for a token, which will allow you to make authenticated calls to the Verix API and access the tax_return objects corresponding to the end-user who generated the initial code. The token is retrieved by making a POST request to the /api/v1/token/create endpoint. An example token exchange request is shown below:

POST /api/v1/tokens/create HTTP/1.1
Host: api.verixapi.com
Content-Type: application/json
{
  "code": "INSERT_CODE_FROM_CONNECT",
  "client_id": "INSERT_PROJECT_CLIENT_ID",
  "client_secret": "INSERT_PROJECT_CLIENT_SECRET"
}
curl https://api.verixapi.com/api/v1/tokens/create -d '{"client_id":"INSERT CLIENT ID", "client_secret":"INSERT CLIENT SECRET", "code":"INSERT CODE"}' -H "Content-Type: application/json"  -X POST

The token is valid for 24 hours, after which it expires and you will no longer have access to the tax_return objects. Your client_id will be exposed in client-side code, but your client_secret should only be exposed in requests to Verix. Moreover, the token should never be shared outside your organization or exposed in any client-side code.

Updated 4 months ago

End-User Authentication


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.