Skip to content

Checking the Status of Submitted Statements

After you submit your statements to the IRS or the Social Security Administration, may wish to monitor them to be sure they've been accepted. The submissionStatus and the submissionStatusDescription fields on the statement are available for this purpose.

Note

Statements are not submitted to the tax authority immediately but are prepared in batches. When checking the submissionStatus, also check the status which indicates whether the submission is still being prepared.

The sample code below illustrates retrieving statements' submission status in several different languages with the following query:

query {
  getStatements (
    otxIds: [
      "a5e724cd-ad1c-4a90-928d-e5e8bcc97e15"
      "8c522b06-79e5-4276-b58c-f83e1265ee05"
      "26180e66-83d4-4a00-b0a6-828eb9a05a76"
      "64ffc7a2-e52a-4e4f-ab8e-58d64fb7e561"
    ]
  ) {
    errors
    statements {
      pageInfo {
        hasNextPage
      }
      nodes {
        otxId
        uploaderId
        status
        statusDescription
        submissionStatus
        submissionStatusDescription
      }
    }
  }
}

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 {
          getStatements (
            otxIds: [
              \"a5e724cd-ad1c-4a90-928d-e5e8bcc97e15\"
              \"8c522b06-79e5-4276-b58c-f83e1265ee05\"
              \"26180e66-83d4-4a00-b0a6-828eb9a05a76\"
              \"64ffc7a2-e52a-4e4f-ab8e-58d64fb7e561\"
            ]
          ) {
            errors
            statements {
              pageInfo {
                hasNextPage
              }
              nodes {
                otxId
                uploaderId
                status
                statusDescription
                submissionStatus
                submissionStatusDescription
              }
            }
          }
        }
      "
    }
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 { ^
          getStatements ( ^
            otxIds: [ ^
              \\\"a5e724cd-ad1c-4a90-928d-e5e8bcc97e15\\\" ^
              \\\"8c522b06-79e5-4276-b58c-f83e1265ee05\\\" ^
              \\\"26180e66-83d4-4a00-b0a6-828eb9a05a76\\\" ^
              \\\"64ffc7a2-e52a-4e4f-ab8e-58d64fb7e561\\\" ^
            ] ^
          ) { ^
            errors ^
            statements { ^
              pageInfo { ^
                hasNextPage ^
              } ^
              nodes { ^
                otxId ^
                uploaderId ^
                status ^
                statusDescription ^
                submissionStatus ^
                submissionStatusDescription ^
              } ^
            } ^
          } ^
        } ^
     \" }"
// 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 (
        otxIds: [
          "a5e724cd-ad1c-4a90-928d-e5e8bcc97e15"
          "8c522b06-79e5-4276-b58c-f83e1265ee05"
          "26180e66-83d4-4a00-b0a6-828eb9a05a76"
          "64ffc7a2-e52a-4e4f-ab8e-58d64fb7e561"
        ]
      ) {
        errors
        statements {
          pageInfo {
            hasNextPage
          }
          nodes {
            otxId
            uploaderId
            status
            statusDescription
            submissionStatus
            submissionStatusDescription
          }
        }
      }
    }
  `

  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 {
    getStatements (
      otxIds: [
        "a5e724cd-ad1c-4a90-928d-e5e8bcc97e15"
        "8c522b06-79e5-4276-b58c-f83e1265ee05"
        "26180e66-83d4-4a00-b0a6-828eb9a05a76"
        "64ffc7a2-e52a-4e4f-ab8e-58d64fb7e561"
      ]
    ) {
      errors
      statements {
        pageInfo {
          hasNextPage
        }
        nodes {
          otxId
          uploaderId
          status
          statusDescription
          submissionStatus
          submissionStatusDescription
        }
      }
    }
  }
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 {
        getStatements (
          otxIds: [
            "a5e724cd-ad1c-4a90-928d-e5e8bcc97e15"
            "8c522b06-79e5-4276-b58c-f83e1265ee05"
            "26180e66-83d4-4a00-b0a6-828eb9a05a76"
            "64ffc7a2-e52a-4e4f-ab8e-58d64fb7e561"
          ]
        ) {
          errors
          statements {
            pageInfo {
              hasNextPage
            }
            nodes {
              otxId
              uploaderId
              status
              statusDescription
              submissionStatus
              submissionStatusDescription
            }
          }
        }
      }
    """
)

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 {
    getStatements (
      otxIds: [
        "a5e724cd-ad1c-4a90-928d-e5e8bcc97e15"
        "8c522b06-79e5-4276-b58c-f83e1265ee05"
        "26180e66-83d4-4a00-b0a6-828eb9a05a76"
        "64ffc7a2-e52a-4e4f-ab8e-58d64fb7e561"
      ]
    ) {
      errors
      statements {
        pageInfo {
          hasNextPage
        }
        nodes {
          otxId
          uploaderId
          status
          statusDescription
          submissionStatus
          submissionStatusDescription
        }
      }
    }
  }
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