JavaScript Quick Start

This quick start guide illustrates how to add two new W-2 statements to the OtterTax API and download PDF versions of the statements. Before starting, you should create an account on the sanbdbox and have your username and password handy.

Other Resources

A video tutorial is available on the OtterTax videos page demonstrating how to get started with JavaScript. Our Github page provides full source code for the tutorial.

Confirming your registration

After registering an account in the sandbox or the production system, you need to confirm your registration. Run the code below, substituting your confirmation token and password where indicated. If successful, the API will respond with a message indicating that your registration confirmation succeeded.

// Using graphql-request from
// https://github.com/prisma-labs/graphql-request
// Example tested with node version 14.16.0
import { request, gql } from 'graphql-request'

const query = gql`
mutation {
confirmRegistration( 
  confirmationToken: "YOUR CONFIRMATION TOKEN",
  password: "YOUR SECURE PASSWORD"
) {
    message
  }
}
`

request('https://sandbox.ottertax.com/v2/graphql', query)
.then((data) => console.log(data))

Obtaining an Authentication Token

The API requires authentication for running queries and mutations and looks for authentication information in the request headers. To obtain the necessary header data, run the program below, substituting your email address and password where indicated. Save the output as we will use it in the next steps.

// If using node, be sure to install and require node-fetch.
// Example tested with node version 14.16.0
const fetch = require("node-fetch");

const data = { email:    "YOUR LOGIN EMAIL",
                password: "YOUR PASSWORD" };
fetch( "https://sandbox.ottertax.com/v2/auth/sign_in",
      { method: "POST",
        headers: {"content-type": "application/json"},
        body: JSON.stringify(data) })
.then(response => {
  const accessToken = response.headers.get('access-token');
  const client = response.headers.get('client');
  const uid = response.headers.get('uid');
  console.log( 'access-token: ', accessToken );
  console.log( 'client:       ', client );
  console.log( 'uid:          ', uid );
})
.catch(err => console.log(err));

Adding Statements

Once you've received your authentication credential, you're ready to add statements. Run the code below to add the two sample statements. Substitute the access token, client ID, and user ID you received in the last step where appropriate.

// Using graphql-request from
// https://github.com/prisma-labs/graphql-request
// Example tested with node version 14.16.0
import { GraphQLClient, gql } from 'graphql-request'

async function main() {
  const endpoint = 'https://sandbox.ottertax.com/v2/graphql'

  const graphQLClient = new GraphQLClient(endpoint, {
    headers: {
      'access-token': 'YOUR ACCESS TOKEN',
      'client':       'YOUR CLIENT ID',
      'uid':          'YOUR UID'
    },
  })
  const query = gql`
    mutation {
      addFw2Statements(
        statements: [
          {
            federalTaxWithheld: "18622.44"
            recipientAddress1: "784 East 77th Street"
            recipientCity: "New York"
            recipientFirstName: "Leif"
            recipientLastName: "Babson"
            recipientState: "NY"
            recipientTin: "200213492"
            recipientZipCode: "10162"
            senderAddress1: "406 Chambers Street"
            senderCity: "New York"
            senderName: "Empire Savings Bank"
            senderState: "NY"
            senderTin: "104123456"
            senderZipCode: "10282"
            socialSecurityTaxWithheld: "4484.17"
            socialSecurityWages: "74714.16"
            tags: ["group 7", "New York"]
            uploaderId: "14117"
            wagesTipsOtherComp: "74714.16"
          }
          {
            federalTaxWithheld: "9685.00"
            recipientAddress1: "617 West 53rd Street"
            recipientAddress2: "Apartment 1022"
            recipientCity: "New York"
            recipientFirstName: "Anjelica"
            recipientLastName: "Heximer"
            recipientState: "NY"
            recipientTin: "200223492"
            recipientZipCode: "10019"
            senderAddress1: "406 Chambers Street"
            senderCity: "New York"
            senderName: "Empire Savings Bank"
            senderState: "NY"
            senderTin: "104123456"
            senderZipCode: "10282"
            socialSecurityTaxWithheld: "2773.38"
            socialSecurityWages: "44021.96"
            tags: ["group 7", "New York", "send for review"]
            uploaderId: "14118"
            wagesTipsOtherComp: "44021.96"
          }
        ]
      ) {
        errors
        statements {
          recordNumber
          statement {
            federalTaxWithheld
            otxId
            uploaderId
            recipientFirstName
            recipientLastName
            socialSecurityTaxWithheld
            socialSecurityWages
            tags
            wagesTipsOtherComp
          }
          messages
        }
      }
    }
  `

  const data = await graphQLClient.request(query)
  console.log(JSON.stringify(data))
}

main().catch((error) => console.error(error))

Downloading PDFs

After you've uploaded statement data, you can download PDF versions of the statements. Use the code below, again substituting the access token, client ID, and user ID you received in the last step where indicated.

// Using graphql-request from
// https://github.com/prisma-labs/graphql-request
// Example tested with node version 14.16.0
import { GraphQLClient, gql } from 'graphql-request'
import fs from 'fs';

async function main() {
  const endpoint = 'https://sandbox.ottertax.com/v2/graphql'

  const graphQLClient = new GraphQLClient(endpoint, {
    headers: {
      'access-token': 'YOUR ACCESS TOKEN',
      'client':       'YOUR CLIENT ID',
      'uid':          'YOUR UID'
    },
  })
  const query = gql`
    query {
      getStatements(
        uploaderIds: [
          "14117"
          "14118"
        ]
      ) {
        errors
        statements {
          nodes {
            otxId
            uploaderId
            pdf
          }
        }
      }
    }
  `

  const data = await graphQLClient.request(query)
  const statements = data.getStatements.statements.nodes
  const statmentsDirectory = './statements'
  statements.forEach((statement) => {
    let filename = `${statmentsDirectory}/${statement.otxId}.pdf`
    let buffer = Buffer.from(statement.pdf, 'base64')
    fs.writeFile(filename, buffer, err => {})
  })
}

main().catch((error) => console.error(error))

Your statements are in a subdirectory called statements.

Where to Go from Here

If you need to make changes to statements after they've been uploaded, you can use the update mutation.

If you're using the production version of the API, you can remove the watermark from statements by finalizing them.

The production system also allows you to submit statements to the IRS to meet your filing requirements.