Reviewing Statements

The getStatements query is used to retrieve statement data. It supports a number of search criteria and can return statements of any type. Use the getStatements query to retrieve data unless you need to obtain information that only appears on a particular form, such as mortgage interest on a 1098 or wages on a W-2. In such cases, use the query for the distinct statement object.

This page demonstrates several sample queries which can be used to retrieve statement data. The most up-to-date information about the query, including the parameters it accepts and the payload it returns, is available as part of the introspective GraphQL documentation.

Getting All Statements

The simplest form of the query retrieves all of the statements you have uploaded. Use this form of the query if you wish to retrieve all statements and you have fewer than 100 statements in the database. Such a query takes the following form:

query {
  getStatements {
    errors
    statements {
      pageInfo {
        hasNextPage
      }
      nodes {
        otxId
        uploaderId
        formType
        status
        statementValid
        recipientFirstName
        recipientLastName
        recipientEntityName
        senderName
      }
    }
  }
}

Note

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 code snippets below illustrate running the query. See the documentation on authentication for information about obtaining the credential data passed in the header.

cURL (Linux, Mac)

# 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 {
          getStatements {
            errors
            statements {
              pageInfo {
                hasNextPage
              }
              nodes {
                otxId
                uploaderId
                formType
                status
                statementValid
                recipientFirstName
                recipientLastName
                recipientEntityName
                senderName
              }
            }
          }
        }
      "
    }
END_DATA

cURL (Windows)

:: 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 { ^
          getStatements { ^
            errors ^
            statements { ^
              pageInfo { ^
                hasNextPage ^
              } ^
              nodes { ^
                otxId ^
                uploaderId ^
                formType ^
                status ^
                statementValid ^
                recipientFirstName ^
                recipientLastName ^
                recipientEntityName ^
                senderName ^
              } ^
            } ^
          } ^
        } ^
     \" }"

Javascript

// 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 {
      getStatements {
        errors
        statements {
          pageInfo {
            hasNextPage
          }
          nodes {
            otxId
            uploaderId
            formType
            status
            statementValid
            recipientFirstName
            recipientLastName
            recipientEntityName
            senderName
          }
        }
      }
    }
  `

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

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

PHP

<?php
// Tested with php-cli version 8.0.5.
$query =<<<'END_DATA'
  query {
    getStatements {
      errors
      statements {
        pageInfo {
          hasNextPage
        }
        nodes {
          otxId
          uploaderId
          formType
          status
          statementValid
          recipientFirstName
          recipientLastName
          recipientEntityName
          senderName
        }
      }
    }
  }
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";
}
?>

Python

# 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 {
        getStatements {
          errors
          statements {
            pageInfo {
              hasNextPage
            }
            nodes {
              otxId
              uploaderId
              formType
              status
              statementValid
              recipientFirstName
              recipientLastName
              recipientEntityName
              senderName
            }
          }
        }
      }
    """
)

result = client.execute(query)
print(result)

Ruby

# 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 {
    getStatements {
      errors
      statements {
        pageInfo {
          hasNextPage
        }
        nodes {
          otxId
          uploaderId
          formType
          status
          statementValid
          recipientFirstName
          recipientLastName
          recipientEntityName
          senderName
        }
      }
    }
  }
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

Getting Statements Conditionally

The getStatements query accepts several parameters so you can retrieve statements that meet only certain conditions. These parameters are:

Parameter	Description	Sample Value
otxIds	A list of OtterTax IDs to select.	["a948985e-d69e-4755-a388-f30f88438137", "2117c481-e7fe-4868-ab05-e74dd9717dfc"]
uploaderIds	A list of uploader IDs to select.	["yZSpCJlhJs", "kVRTlBB27m"]
formType	The form type to select.	Fw2
validOnly	If true, select only statements that are valid.	true
invalidOnly	If true, select only statements that are invalid.	true
status	The numeric statement status to select.	110
taxYear	The tax year to select.	2020
tag	Select all statements whose tags include the supplied value.	"review group 3"
recipientName	Select all statements where any part of the recipient name matches the supplied value.	"Alice Jones"
senderName	Select all statements where any part of the sender name matches the supplied value.	"Empire Savings Bank"

Note

Selection criteria are joined using AND. Supplying both otxIds and uploaderIds parameters, for example, means that only statements having a matching OTX ID and a matching uploader ID will be returned.

Sample Conditional Query

The following query selects only invalid statements of type 1098 that include the tag "review group 3."

query {
  getStatements(formType: F1098,
                tag: "review group 3",
                invalidOnly: true) {
    errors
    statements {
      pageInfo {
        hasNextPage
      }
      nodes {
        otxId
        uploaderId
        formType
        status
        statementValid
        recipientFirstName
        recipientLastName
        recipientEntityName
        senderName
      }
    }
  }
}

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

cURL (Linux, Mac)

# 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 {
          getStatements(formType: F1098,
                        tag: \"review group 3\",
                        invalidOnly: true) {
            errors
            statements {
              pageInfo {
                hasNextPage
              }
              nodes {
                otxId
                uploaderId
                formType
                status
                statementValid
                recipientFirstName
                recipientLastName
                recipientEntityName
                senderName
              }
            }
          }
        }
      "
    }
END_DATA

cURL (Windows)

:: 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 { ^
          getStatements(formType: F1098, ^
                        tag: \\\"review group 3\\\", ^
                        invalidOnly: true) { ^
            errors ^
            statements { ^
              pageInfo { ^
                hasNextPage ^
              } ^
              nodes { ^
                otxId ^
                uploaderId ^
                formType ^
                status ^
                statementValid ^
                recipientFirstName ^
                recipientLastName ^
                recipientEntityName ^
                senderName ^
              } ^
            } ^
          } ^
        } ^
     \" }"

Javascript

// 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 {
      getStatements(formType: F1098,
                    tag: "review group 3",
                    invalidOnly: true) {
        errors
        statements {
          pageInfo {
            hasNextPage
          }
          nodes {
            otxId
            uploaderId
            formType
            status
            statementValid
            recipientFirstName
            recipientLastName
            recipientEntityName
            senderName
          }
        }
      }
    }
  `

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

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

PHP

<?php
// Tested with php-cli version 8.0.5.
$query =<<<'END_DATA'
  query {
    getStatements(formType: F1098,
                  tag: "review group 3",
                  invalidOnly: true) {
      errors
      statements {
        pageInfo {
          hasNextPage
        }
        nodes {
          otxId
          uploaderId
          formType
          status
          statementValid
          recipientFirstName
          recipientLastName
          recipientEntityName
          senderName
        }
      }
    }
  }
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";
}
?>

Python

# 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 {
        getStatements(formType: F1098,
                      tag: "review group 3",
                      invalidOnly: true) {
          errors
          statements {
            pageInfo {
              hasNextPage
            }
            nodes {
              otxId
              uploaderId
              formType
              status
              statementValid
              recipientFirstName
              recipientLastName
              recipientEntityName
              senderName
            }
          }
        }
      }
    """
)

result = client.execute(query)
print(result)

Ruby

# 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 {
    getStatements(formType: F1098,
                  tag: "review group 3",
                  invalidOnly: true) {
      errors
      statements {
        pageInfo {
          hasNextPage
        }
        nodes {
          otxId
          uploaderId
          formType
          status
          statementValid
          recipientFirstName
          recipientLastName
          recipientEntityName
          senderName
        }
      }
    }
  }
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