Connections

Connections are the read-only links between Trimline and the systems where your vendor data lives: a mailbox for invoices and vendor correspondence, and a finance platform for payment history. You can create a connection through the API to embed onboarding in your own tools, but most teams connect once from the dashboard.

Supported providers

Endpoints

• GET/v1/connectionsList connections
• POST/v1/connectionsStart an authorization
• GET/v1/connections/:idRetrieve
• POST/v1/connections/:id/syncSync now
• DELETE/v1/connections/:idRevoke

The connection object

{
  "id": "con_5Vb1Ns",
  "object": "connection",
  "provider": "gmail",
  "status": "active",
  "account_label": "billing@northwind.example",
  "scopes": ["gmail.readonly.vendor_filtered", "gmail.send"],
  "can_send": true,
  "last_synced_at": "2026-11-09T06:00:12Z",
  "items_synced": 1482,
  "created_at": "2026-10-02T14:15:40Z",
  "livemode": false
}

Create a connection

Returns an authorization_url. Send the user there to grant access with the provider. They return to your redirect_url, and the connection becomes active within a few seconds.

curl -X POST https://api.trimline.tech/v1/connections \
  -H "Authorization: Bearer $TRIMLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "gmail", "redirect_url": "https://internal.northwind.example/trimline/done", "can_send": true }'

{
  "id": "con_5Vb1Ns",
  "object": "connection",
  "provider": "gmail",
  "status": "pending",
  "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=…&state=con_5Vb1Ns…",
  "expires_at": "2026-11-09T11:00:00Z"
}

What we read

For mailboxes, we only process messages from senders we recognize as vendors, plus messages that match billing patterns such as invoices, receipts and renewal notices. Everything else is skipped without being read. Matching messages are processed in memory, and only the extracted facts are kept. The messages themselves are never stored. For finance platforms, we read bills, payments and vendor records, and we never request write access.

Revoke a connection

Revokes our access token with the provider and immediately deletes all data derived from that connection from our live systems. Encrypted backups expire within 7 days. Negotiations that send from a revoked mailbox pause until another mailbox with can_send is connected.