Quick Start for Other Languages¶
You can use virtually any language you like to work with GraphQL. The specification itself is language agnostic, but many languages have toolkits or libraries that make it easier to work with GraphQL. The GraphQL Foundation's website provides a list of languages and related tools.
This quick start guide illustrates how to add two new 1099-NEC statements to the OtterTax API and download PDF versions of the statements. The code snippets below use the bash interpreter on Linux, but you should be able to adapt the steps below to suit your particular language.
Before starting, you should create an account on the sanbdbox and have your username and password handy.
Confirming your registration¶
After registering an account in the sandbox or the production system, you need to confirm your registration. This can either be done using your chosen programming language or from the command line using a tool like cURL. The sample code below illustrates using cURL on a Linux system running bash. Run the code after substituting your confirmation token and password where indicated.
# 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' \
-d @- <<END_DATA
{
"query":"
mutation {
confirmRegistration(
confirmationToken: \"YOUR CONFIRMATION TOKEN\"
password: \"YOUR SECURE PASSWORD\"
) {
message
}
}
"
}
END_DATA
Obtaining an Authentication Token¶
The API requires authentication for running queries and mutations and looks for authentication information in the request headers. The sample code demonstrates how to retrieve an authentication token. Either run the program as it is or adapt it to your preferred language. In either case, substitute your email address and password where indicated. Save the output as we will use it in the next steps.
# Terminate lines with \ character to allow command to span multiple lines.
# Escape quotation marks in data stream with single backslashes.
# Tested using the bash interpreter on Linux.
curl 'https://sandbox.ottertax.com/v2/auth/sign_in' \
-i \
-X POST \
-H 'content-type: application/json' \
-d "{ \"email\": \"YOUR LOGIN EMAIL\", \"password\": \"YOUR PASSWORD\" }"
# Output contains values for access-token, client, and uid
Authenticating to the API¶
In order to run queries and mutations in the API, you will need to provide three header values: access-token, client, and uid. Be sure to include these values in your headers on all subsequent calls to the AI. The code snippets that follow use the -H option of cURL to supply the necessary headers.
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.
# 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":"
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: \"14123\"
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: \"14124\"
wagesTipsOtherComp: \"44021.96\"
}
]
) {
errors
statements {
recordNumber
statement {
federalTaxWithheld
otxId
uploaderId
recipientFirstName
recipientLastName
socialSecurityTaxWithheld
socialSecurityWages
tags
wagesTipsOtherComp
}
messages
}
}
}
"
}
END_DATA
Downloading PDFs¶
The API sends PDFs as streams of base 64 encoded data so downloading them using a bash script is not possible, so the bash script below outputs the PDF without decoding it. Sample code for converting the data stream to a binary PDF file can be found here.
# 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(
uploaderIds: [
\"14123\"
\"14124\"
]
) {
errors
statements {
nodes {
otxId
uploaderId
pdf
}
}
}
}
"
}
END_DATA
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.