PHP Quick Start¶
This quick start guide illustrates how to add two new 1099-NEC 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 PHP. 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.
<?php
// Tested with php-cli version 8.0.5.
$query =<<<'END_DATA'
mutation {
confirmRegistration(
confirmationToken: "YOUR CONFIRMATION TOKEN",
password: "YOUR SECURE PASSWORD"
) {
message
}
}
END_DATA;
$payload = array ('query' => $query);
$options = array(
'http' => array(
'method' => 'POST',
'content' => json_encode( $payload ),
'header'=> "Content-Type: application/json\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";
}
?>
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.
<?php
// Tested with php-cli version 8.0.5.
$data = array( 'email' => 'YOUR LOGIN EMAIL',
'password' => 'YOUR PASSWORD' );
$options = array(
'http' => array(
'method' => 'POST',
'content' => json_encode( $data ),
'header'=> "Content-Type: application/json\r\n"
)
);
$context = stream_context_create( $options );
$response = get_headers( 'https://sandbox.ottertax.com/v2/auth/sign_in',
1, $context );
if( $response === FALSE ) {
print "Call to server failed.\n";
} else {
print "access-token: ${response['access-token']}\n";
print "client: ${response['client']}\n";
print "uid: ${response['uid']}\n";
}
?>
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.
<?php
// Tested with php-cli version 8.0.5.
$query =<<<'END_DATA'
mutation {
addF1099necStatements(
statements: [
{
nonemployeeComp: "10318.62"
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"
senderPhoneNumber: "2125557318"
senderState: "NY"
senderTin: "104123456"
senderZipCode: "10282"
tags: ["group 7", "New York"]
uploaderId: "14113"
}
{
nonemployeeComp: "6370.97"
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"
senderPhoneNumber: "2125557318"
senderState: "NY"
senderTin: "104123456"
senderZipCode: "10282"
tags: ["group 7", "New York", "send for review"]
uploaderId: "14114"
}
]
) {
errors
statements {
recordNumber
statement {
otxId
uploaderId
recipientFirstName
recipientLastName
tags
}
messages
}
}
}
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";
}
?>
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.
<?php
// Tested with php-cli version 8.0.5.
$query =<<<'END_DATA'
query {
getStatements(
uploaderIds: [
"14113"
"14114"
]
) {
errors
statements {
nodes {
otxId
uploaderId
pdf
}
}
}
}
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 {
$json = json_decode( $response, true );
$statements = $json['data']['getStatements']['statements']['nodes'];
$statements_directory = './statements';
foreach( $statements as $statement ) {
$file_name = "{$statements_directory}/{$statement['otxId']}.pdf";
$pdf_file = fopen( $file_name, 'w' );
fwrite( $pdf_file, base64_decode( $statement['pdf'] ) );
fclose( $pdf_file );
}
}
?>
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.