API Quickstart

This walkthrough creates a mailbox, uploads a document for extraction, waits for processing, and reads the extracted rows — all with curl. You need a client ID and secret first.

1. Get a token

TOKEN=$(curl -s -X POST https://app.docstosheets.com/connect/token \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  | jq -r .access_token)

2. Create a mailbox

A mailbox defines the extraction columns (“config”) applied to every document it receives.

curl -s -X POST https://app.docstosheets.com/api/mailboxes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoices",
    "config": {
      "fields": [
        { "key": "invoiceNumber", "type": "text", "required": true },
        { "key": "vendor", "type": "text", "required": false },
        { "key": "total", "type": "currency", "required": false }
      ],
      "groups": []
    }
  }'

The response includes the mailbox id (used below) and its inbound email address.

3. Upload a document

Uploads are multipart/form-data; PDFs and common image formats are supported (10 MB request limit).

curl -s -X POST "https://app.docstosheets.com/api/mailboxes/$MAILBOX_ID/uploads" \
  -H "Authorization: Bearer $TOKEN" \
  -F "[email protected]" \
  -F "clientReferenceId=my-batch-42"

The response lists the created documents with their id and initial status.

4. Wait for processing

Extraction runs asynchronously. Poll the document list until the status is extracted (or failed):

curl -s "https://app.docstosheets.com/api/documents?mailboxId=$MAILBOX_ID&page=1&pageSize=20" \
  -H "Authorization: Bearer $TOKEN"

Processing typically takes a few seconds to a minute per document. Poll at a modest interval (for example every 5–10 seconds).

5. Read the extracted rows

Rows are the flat, spreadsheet-shaped projection of the extracted data:

curl -s "https://app.docstosheets.com/api/mailboxes/$MAILBOX_ID/rows" \
  -H "Authorization: Bearer $TOKEN"

To inspect or correct individual extractions, use the Extractions endpoints instead.

Next steps

• Browse the full API Reference for every endpoint, parameter, and response schema.
• Documents can also arrive by email — each mailbox has an inbound address (see Email Mailboxes & Ingestion); the API then serves the extracted results regardless of how documents arrived.