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/stripereturns 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.