Skip to content

Reviewing W-2 Statements

Two queries are available for reviewing W-2 statements, getStatements and getFw2Statements. The getStatements query is the more flexible of the two, so you should use it whenever possible and only use getFw2Statements when you need to review information that only appears on Form W-2 (for example, wages, tips, and other compensation or Social Security wages). More information about the distinction between the generic and distinct statement objects is included in the overview of the API design philosophy.

The getStatements Query

The getStatements query accepts more search parameters than getFw2Statements, and it allows for retrieval of multiple statement types simultaneously. You should use the getStatements query where possible in order to take advantage of the increased flexibility it provides. See the getStatements documentation for more information.

The getFw2Statements Query

Use the getFw2Statements query when you need to retrieve information that only appears on Form W-2, for example wages, tips, and other compensation or Social Security wages.

The getFw2Statements query accepts only two arguments, both of which are optional: an array of OTX IDs and an array of uploader IDs. The search logic combines these two criteria. If you supply both parameters, only statements with matching OTX IDs and matching uploader IDs are returned. Generally speaking, you should supply only one parameter or the other. Since each parameter is unique across all statements, the query returns at most one statement for each value in the list. If you wish to search for statements using different criteria, use the getStatements query which supports additional search parameters.

Note

The getFw2Statements query returns at most 100 statements. When querying statements, always check the hasNextPage field of the pageInfo object to ensure you have retrieved all matching statements. If your query does not return all statements, page through the result set by making additional queries.

The sample code below demonstrates using the getFw2Statements query and retrieving a subset of fields. Full and up-to-date documentation is available as part of the introspective GraphQL documentation.

Retrieving All W-2 Statements

The query below retrieves all W-2 statements.

query {
  getFw2Statements {
    errors
    statements {
      pageInfo {
        hasNextPage
      }
      nodes {
        otxId
        uploaderId
        recipientFirstName
        recipientLastName
        wagesTipsOtherComp
        federalTaxWithheld
        socialSecurityWages
        socialSecurityTaxWithheld
      }
    }
  }
}

The code snippets below illustrate running the query. See the documentation on authentication for information about obtaining the credential data passed in the header.

# Terminate lines with \ character to allow command to span multiple lines.
# Use here document for data stream.
# Tested using the bash interpreter on Linux.
curl 'https://sandbox.ottertax.com/v2/graphql' \
  -i \
  -X POST \
  -H 'content-type:  application/json' \
  -H 'access-token:  YOUR ACCESS TOKEN' \
  -H 'client:        YOUR CLIENT ID' \
  -H 'uid:           YOUR UID' \
  -d @- <<END_DATA
    { 
      "query":"
        query {
          getFw2Statements {
            errors
            statements {
              pageInfo {
                hasNextPage
              }
              nodes {
                otxId
                uploaderId
                recipientFirstName
                recipientLastName
                wagesTipsOtherComp
                federalTaxWithheld
                socialSecurityWages
                socialSecurityTaxWithheld
              }
            }
          }
        }
      "
    }
END_DATA
:: Terminate lines with ^ character to allow command to span multiple lines.
:: Precede quotation marks in data stream with backslashes.
:: Tested using a command prompt on Windows 10.
curl "https://sandbox.ottertax.com/v2/graphql" ^
  -i ^
  -X POST ^
  -H "content-type: application/json" ^
  -H "access-token: YOUR ACCESS TOKEN" ^
  -H "client:       YOUR CLIENT ID" ^
  -H "uid:          YOUR UID" ^
  -d "{ \"query\":\" ^
        query { ^
          getFw2Statements { ^
            errors ^
            statements { ^
              pageInfo { ^
                hasNextPage ^
              } ^
              nodes { ^
                otxId ^
                uploaderId ^
                recipientFirstName ^
                recipientLastName ^
                wagesTipsOtherComp ^
                federalTaxWithheld ^
                socialSecurityWages ^
                socialSecurityTaxWithheld ^
              } ^
            } ^
          } ^
        } ^
     \" }"
// 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`
    query {
      getFw2Statements {
        errors
        statements {
          pageInfo {
            hasNextPage
          }
          nodes {
            otxId
            uploaderId
            recipientFirstName
            recipientLastName
            wagesTipsOtherComp
            federalTaxWithheld
            socialSecurityWages
            socialSecurityTaxWithheld
          }
        }
      }
    }
  `

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

main().catch((error) => console.error(error))
<?php
// Tested with php-cli version 8.0.5.
$query =<<<'END_DATA'
  query {
    getFw2Statements {
      errors
      statements {
        pageInfo {
          hasNextPage
        }
        nodes {
          otxId
          uploaderId
          recipientFirstName
          recipientLastName
          wagesTipsOtherComp
          federalTaxWithheld
          socialSecurityWages
          socialSecurityTaxWithheld
        }
      }
    }
  }
END_DATA;
$payload = array ('query' => $query);
$options = array(
  'http' => array(
    'method'  => 'POST',
    'content' => json_encode( $payload ),
    'header'=>  "Content-Type: application/json\r\n" .
                "access-token: YOUR ACCESS TOKEN\r\n" .
                "client:       YOUR CLIENT ID\r\n" .
                "uid:          YOUR UID\r\n"
    )
);

$context  = stream_context_create( $options );
$response = file_get_contents( 'https://sandbox.ottertax.com/v2/graphql',
                               false, $context );
if( $response === FALSE ) {
  echo "Call to server failed.\n";
} else {
  echo $response . "\n";
}
?>
# Using GQL from
# https://github.com/graphql-python/gql
# Tested using python version 3.8.8
from gql import gql, Client
from gql.transport.aiohttp import AIOHTTPTransport

transport = AIOHTTPTransport(url="https://sandbox.ottertax.com/v2/graphql",
                            headers={ 'access-token': 'YOUR ACCESS TOKEN',
                                      'client':       'YOUR CLIENT ID',
                                      'uid':          'YOUR UID' })
client = Client(transport=transport, fetch_schema_from_transport=True)
query = gql(
    """
      query {
        getFw2Statements {
          errors
          statements {
            pageInfo {
              hasNextPage
            }
            nodes {
              otxId
              uploaderId
              recipientFirstName
              recipientLastName
              wagesTipsOtherComp
              federalTaxWithheld
              socialSecurityWages
              socialSecurityTaxWithheld
            }
          }
        }
      }
    """
)

result = client.execute(query)
print(result)
# If you wish to use a library instead, see
# https://github.com/github/graphql-client
# Tested using ruby 2.7.2.
require( 'net/http' )
require( 'uri' )
require( 'json' )

uri = URI( "https://sandbox.ottertax.com/v2/graphql" )
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_PEER
headers = { 'Content-Type': 'application/json',
            'access-token': 'YOUR ACCESS TOKEN',
            'client':       'YOUR CLIENT ID',
            'uid':          'YOUR UID' }

query = <<-END_DATA
  query {
    getFw2Statements {
      errors
      statements {
        pageInfo {
          hasNextPage
        }
        nodes {
          otxId
          uploaderId
          recipientFirstName
          recipientLastName
          wagesTipsOtherComp
          federalTaxWithheld
          socialSecurityWages
          socialSecurityTaxWithheld
        }
      }
    }
  }
END_DATA
request = Net::HTTP::Post.new(uri.request_uri, headers )
request.body = {query: query}.to_json
response = http.request(request)
if( response.code == '200' )
  payload = JSON.parse( response.body )
  STDOUT.puts( payload )
else
  STDOUT.puts( "Response code was #{response.code}:\n#{response.inspect}" )
end

Retrieving Specific W-2 Statements

The example that follows illustrates the getFw2Statements query to get a specific set of statements. A list of OTX IDs is passed to the query, and only statements with matching OTX IDs are returned. To search by uploader ID, supply a list of uploaderIds instead.

query {
  getFw2Statements(
    otxIds: [
      "2edb5f8e-50bd-4807-b5a4-942ac652d0fe"
      "50814715-0a50-45c9-94c6-0618d9daabd2"
      "b3f4e4d6-eac0-41be-aa29-3e6a18c5ad49"
      "3c874465-29d1-4e15-a414-d0784bc62d5a"
      "a166adbe-8469-46ec-bf17-3104ad3c99e1"
    ]
  ) {
    errors
    statements {
      pageInfo {
        hasNextPage
      }
      nodes {
        otxId
        uploaderId
        recipientFirstName
        recipientLastName
        wagesTipsOtherComp
        federalTaxWithheld
        socialSecurityWages
        socialSecurityTaxWithheld
      }
    }
  }
}

The code snippets below illustrate running the query. See the documentation on authentication for information about obtaining the credential data passed in the header.

# Terminate lines with \ character to allow command to span multiple lines.
# Escape quotation marks in body of mutation or query with backslashes.
# Use here document for data stream.
# Tested using the bash interpreter on Linux.
curl 'https://sandbox.ottertax.com/v2/graphql' \
  -i \
  -X POST \
  -H 'content-type:  application/json' \
  -H 'access-token:  YOUR ACCESS TOKEN' \
  -H 'client:        YOUR CLIENT ID' \
  -H 'uid:           YOUR UID' \
  -d @- <<END_DATA
    { 
      "query":"
        query {
          getFw2Statements(
            otxIds: [
              \"2edb5f8e-50bd-4807-b5a4-942ac652d0fe\"
              \"50814715-0a50-45c9-94c6-0618d9daabd2\"
              \"b3f4e4d6-eac0-41be-aa29-3e6a18c5ad49\"
              \"3c874465-29d1-4e15-a414-d0784bc62d5a\"
              \"a166adbe-8469-46ec-bf17-3104ad3c99e1\"
            ]
          ) {
            errors
            statements {
              pageInfo {
                hasNextPage
              }
              nodes {
                otxId
                uploaderId
                recipientFirstName
                recipientLastName
                wagesTipsOtherComp
                federalTaxWithheld
                socialSecurityWages
                socialSecurityTaxWithheld
              }
            }
          }
        }
      "
    }
END_DATA
:: Terminate lines with ^ character to allow command to span multiple lines.
:: Precede quotation marks in body of mutation or query with triple backslashes.
:: Precede other quotation marks in data stream with single backslashes.
:: Tested using a command prompt on Windows 10.
curl "https://sandbox.ottertax.com/v2/graphql" ^
  -i ^
  -X POST ^
  -H "content-type: application/json" ^
  -H "access-token: YOUR ACCESS TOKEN" ^
  -H "client:       YOUR CLIENT ID" ^
  -H "uid:          YOUR UID" ^
  -d "{ \"query\":\" ^
        query { ^
          getFw2Statements( ^
            otxIds: [ ^
              \\\"2edb5f8e-50bd-4807-b5a4-942ac652d0fe\\\" ^
              \\\"50814715-0a50-45c9-94c6-0618d9daabd2\\\" ^
              \\\"b3f4e4d6-eac0-41be-aa29-3e6a18c5ad49\\\" ^
              \\\"3c874465-29d1-4e15-a414-d0784bc62d5a\\\" ^
              \\\"a166adbe-8469-46ec-bf17-3104ad3c99e1\\\" ^
            ] ^
          ) { ^
            errors ^
            statements { ^
              pageInfo { ^
                hasNextPage ^
              } ^
              nodes { ^
                otxId ^
                uploaderId ^
                recipientFirstName ^
                recipientLastName ^
                wagesTipsOtherComp ^
                federalTaxWithheld ^
                socialSecurityWages ^
                socialSecurityTaxWithheld ^
              } ^
            } ^
          } ^
        } ^
     \" }"
// 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`
    query {
      getFw2Statements(
        otxIds: [
          "2edb5f8e-50bd-4807-b5a4-942ac652d0fe"
          "50814715-0a50-45c9-94c6-0618d9daabd2"
          "b3f4e4d6-eac0-41be-aa29-3e6a18c5ad49"
          "3c874465-29d1-4e15-a414-d0784bc62d5a"
          "a166adbe-8469-46ec-bf17-3104ad3c99e1"
        ]
      ) {
        errors
        statements {
          pageInfo {
            hasNextPage
          }
          nodes {
            otxId
            uploaderId
            recipientFirstName
            recipientLastName
            wagesTipsOtherComp
            federalTaxWithheld
            socialSecurityWages
            socialSecurityTaxWithheld
          }
        }
      }
    }
  `

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

main().catch((error) => console.error(error))
<?php
// Tested with php-cli version 8.0.5.
$query =<<<'END_DATA'
  query {
    getFw2Statements(
      otxIds: [
        "2edb5f8e-50bd-4807-b5a4-942ac652d0fe"
        "50814715-0a50-45c9-94c6-0618d9daabd2"
        "b3f4e4d6-eac0-41be-aa29-3e6a18c5ad49"
        "3c874465-29d1-4e15-a414-d0784bc62d5a"
        "a166adbe-8469-46ec-bf17-3104ad3c99e1"
      ]
    ) {
      errors
      statements {
        pageInfo {
          hasNextPage
        }
        nodes {
          otxId
          uploaderId
          recipientFirstName
          recipientLastName
          wagesTipsOtherComp
          federalTaxWithheld
          socialSecurityWages
          socialSecurityTaxWithheld
        }
      }
    }
  }
END_DATA;
$payload = array ('query' => $query);
$options = array(
  'http' => array(
    'method'  => 'POST',
    'content' => json_encode( $payload ),
    'header'=>  "Content-Type: application/json\r\n" .
                "access-token: YOUR ACCESS TOKEN\r\n" .
                "client:       YOUR CLIENT ID\r\n" .
                "uid:          YOUR UID\r\n"
    )
);

$context  = stream_context_create( $options );
$response = file_get_contents( 'https://sandbox.ottertax.com/v2/graphql',
                               false, $context );
if( $response === FALSE ) {
  echo "Call to server failed.\n";
} else {
  echo $response . "\n";
}
?>
# Using GQL from
# https://github.com/graphql-python/gql
# Tested using python version 3.8.8
from gql import gql, Client
from gql.transport.aiohttp import AIOHTTPTransport

transport = AIOHTTPTransport(url="https://sandbox.ottertax.com/v2/graphql",
                            headers={ 'access-token': 'YOUR ACCESS TOKEN',
                                      'client':       'YOUR CLIENT ID',
                                      'uid':          'YOUR UID' })
client = Client(transport=transport, fetch_schema_from_transport=True)
query = gql(
    """
      query {
        getFw2Statements(
          otxIds: [
            "2edb5f8e-50bd-4807-b5a4-942ac652d0fe"
            "50814715-0a50-45c9-94c6-0618d9daabd2"
            "b3f4e4d6-eac0-41be-aa29-3e6a18c5ad49"
            "3c874465-29d1-4e15-a414-d0784bc62d5a"
            "a166adbe-8469-46ec-bf17-3104ad3c99e1"
          ]
        ) {
          errors
          statements {
            pageInfo {
              hasNextPage
            }
            nodes {
              otxId
              uploaderId
              recipientFirstName
              recipientLastName
              wagesTipsOtherComp
              federalTaxWithheld
              socialSecurityWages
              socialSecurityTaxWithheld
            }
          }
        }
      }
    """
)

result = client.execute(query)
print(result)
# If you wish to use a library instead, see
# https://github.com/github/graphql-client
# Tested using ruby 2.7.2.
require( 'net/http' )
require( 'uri' )
require( 'json' )

uri = URI( "https://sandbox.ottertax.com/v2/graphql" )
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_PEER
headers = { 'Content-Type': 'application/json',
            'access-token': 'YOUR ACCESS TOKEN',
            'client':       'YOUR CLIENT ID',
            'uid':          'YOUR UID' }

query = <<-END_DATA
  query {
    getFw2Statements(
      otxIds: [
        "2edb5f8e-50bd-4807-b5a4-942ac652d0fe"
        "50814715-0a50-45c9-94c6-0618d9daabd2"
        "b3f4e4d6-eac0-41be-aa29-3e6a18c5ad49"
        "3c874465-29d1-4e15-a414-d0784bc62d5a"
        "a166adbe-8469-46ec-bf17-3104ad3c99e1"
      ]
    ) {
      errors
      statements {
        pageInfo {
          hasNextPage
        }
        nodes {
          otxId
          uploaderId
          recipientFirstName
          recipientLastName
          wagesTipsOtherComp
          federalTaxWithheld
          socialSecurityWages
          socialSecurityTaxWithheld
        }
      }
    }
  }
END_DATA
request = Net::HTTP::Post.new(uri.request_uri, headers )
request.body = {query: query}.to_json
response = http.request(request)
if( response.code == '200' )
  payload = JSON.parse( response.body )
  STDOUT.puts( payload )
else
  STDOUT.puts( "Response code was #{response.code}:\n#{response.inspect}" )
end

Downloading PDFs

You may wish to download PDF versions of statements as part of your review process. The PDF is available on both the generic statement object and the distinct W-2 statement object. The PDF is encoded as base 64 text, and the process for decoding it is explained here.