Quick start

Create a test key, upload a sample Form 1065, and retrieve the Tax Return response. Test mode uses sample extraction results at no charge. Use it to test your integration before processing your own documents in live mode.

1. Get a test key

In the dashboard, open Settings, then Sandbox API under API, and press Create sandbox key. In the Create API key dialog, leave the Backend preset selected and press Create key. The key is shown once, on the API key created screen. Copy it now.

The key starts with ss_test_. It routes every call to the sandbox, an isolated workspace that is created and seeded the first time you mint a test key, with three borrowers and five loans. The calls below need borrowers:read, loans:read, documents:write, documents:read and extractions:read. The default preset covers this.

Put the key in your environment:

export SPREADSPACE_API_KEY="ss_test_..."

2. Install

npm i @spreadspace/sdk

Then download the sample file the run uploads:

curl -fsSLO https://spreadspace.app/sandbox-docs/tax_form_1065.pdf

3. Run it

Choose a language and follow the steps in order. The examples form one program and reuse the IDs from each response. The cURL examples require jq.

Construct the client from the environment variable. An ss_test_ key selects the sandbox; the base URL is the same in both modes.

import { SpreadSpace } from '@spreadspace/sdk';
const client = new SpreadSpace({ apiKey: process.env.SPREADSPACE_API_KEY! });

Select a sample borrower, then select one of that borrower’s loans. The examples use the first result from each list; any sample loan will work. Each example prints the loan’s loan_id. Keep it: the Embed integration guide asks for that loan.

const [borrower] = await client.borrowers.list<{ borrower_id: string; name: string }>().toArray();
const [loan] = await client.loans
  .list<{ loan_id: string; name: string | null }>({ borrowerId: borrower.borrower_id })
  .toArray();
console.log(borrower.name, loan.name);
console.log('loan_id:', loan.loan_id);

Upload the sample and wait for completion. The SDK handles the upload URL, file transfer, and confirmation. In test mode, sample_document selects the sample result; this example uses tax-1065-2024. The confirmation response includes "sample": true, and the job status includes the extracted document ID.

const job = await client.documents.upload('./tax_form_1065.pdf', {
  loanId: loan.loan_id,
  sampleDocument: 'tax-1065-2024',
});
const status = await job.wait();   // polls to COMPLETED or FAILED
const [documentId] = status.extracted_document_ids as string[];

Read the Tax Return by document id and print the filer and one income line. The typed read returns the Tax Return object as its published schema states it: form names the return and data carries its lines, grouped the way the form prints them. A Form 1065 has a header and an income group; the check on form narrows the object to that shape.

const taxReturn = await client.extractions.getTaxReturn(borrower.borrower_id, documentId);
if (taxReturn.form !== '1065') throw new Error(`expected a Form 1065, got ${taxReturn.form}`);
console.log(taxReturn.form);                                // 1065
console.log(taxReturn.data.header.entity_name);             // Greenfield Construction LLC
console.log(taxReturn.data.income.line_1a_gross_receipts);  // 9200000.00

What you got

You read a Tax Return object: form names the return, data carries the form’s lines grouped as printed (header, income, deductions, the schedules), k1_partners holds the attached Schedule K-1s, statements the supporting statements, and metadata the document context. Every field is on The Tax Return object. Test mode returns premade extractions at no charge: an upload through an ss_test_ key always answers with one of the sample documents, so you can exercise the whole loop before a single page is parsed.

Where next

Resources

• OpenAPI spec: the public contract as one JSON document.
• Postman: the collection and the test-mode environment.
• Status probe: GET https://api.spreadspace.app/health returns 200 with the body Healthy.
• Changelog: what changed on the wire.
• Agent index: every page of this site as Markdown, for a coding agent.