GetbeelDocs

Connections

Connect mailboxes and Stripe, scan for supplier invoices and review the documents collected.

Getbeel collects supplier invoices from email (Gmail, Outlook, IMAP or a forwarding address) and turns Stripe invoices into fatture. The API exposes the same connections as Settings → Email and the fatture emesse page.

Scopes: connections:read to read, connections:write to connect, scan and sync; received_invoices:write to approve collected documents. Reading works with any key; changes need a live key (403 livemode_required otherwise). Each document read with AI is paid from the prepaid balance (402 insufficient_balance when it does not cover it).

List connections

curl https://www.getbeel.com/api/v1/connections \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

Each connection has provider (gmail, outlook, imap, forwarding, stripe), active and health.status: healthy, reconnect_required (connect it again), error or unknown.

Connect a mailbox

Gmail and Outlook use OAuth, which a person has to approve. The API returns a link:

curl -X POST https://www.getbeel.com/api/v1/connections/email \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "gmail" }'

Open url in a browser signed in to Getbeel as a member of the team (it asks you to sign in otherwise), approve access, and you land back in the app. The mailbox then appears in GET /connections.

IMAP connects directly: Getbeel tests the login (port 993, TLS) and saves the password encrypted. Use an app password.

curl -X POST https://www.getbeel.com/api/v1/connections/email \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "imap", "email": "fatture@example.it", "password": "app-password", "host": "imap.example.it" }'

New mailboxes count toward the plan's mailbox limit (402 when it is reached).

Scan a mailbox

curl -X POST https://www.getbeel.com/api/v1/connections/$CONNECTION_ID/scan \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "2026-10-01", "to": "2026-10-31" }'

At most a year per request. The scan runs in the background (202); every invoice found fires received_invoice.created and appears in GET /received-invoices?source=email.

Forwarding address

GET /forwarding-address returns the address to forward supplier invoices to, or null until it is set up in the app (it needs the email routing add-on). Forwarded invoices have source: forwarded.

Review collected documents

Collected documents are the received invoices with a source (email, forwarded, manual, bank_transaction). The ones waiting for a person have status: pending_review:

curl "https://www.getbeel.com/api/v1/received-invoices?status=pending_review" \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

curl -X POST https://www.getbeel.com/api/v1/received-invoices/$INVOICE_ID/approve \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

approve sets verified, reject sets rejected. Documents still being read, missing-document placeholders and exported ones cannot be reviewed (409).

Stripe

  • POST /connections/stripe returns a link to Stripe Connect; after approving you land on the fatture emesse page.
  • POST /connections/stripe/sync (optional { "from", "to" }, default the last 30 days) imports Stripe invoices as fatture emesse. It needs the SDI add-on and quota; if the connection has automatic sending on, the invoices also go to SDI.

With an AI assistant

The MCP server has list_connections, connect_mailbox (returns the link), scan_mailbox, list_collected_documents and approve_collected_document. IMAP passwords never go through the assistant: connect IMAP in the app or with the API.

On this page