Connections

Finpilo can send validated documents directly to your accounting system. Instead of exporting files manually, the document data is pushed automatically when you send a document. A connection tells Finpilo where to send it and how to sign in.

Connections are managed in one place — the Connections tab in Workspace Settings — and then picked wherever they are needed. Each entity can pick its own connection, and one connection can be marked as the default for the whole workspace.

What a connection is

A connection describes one external system:

• Name — how the connection appears in lists (for example "Accounting system").
• Base URL — the address of the external system.
• Auth — how Finpilo authenticates: No auth, Bearer token, Basic (user:password), or Custom header.
• Secret — the token, password, or header value the system expects.

The secret is stored encrypted. After you save it, Finpilo never shows it again — the connection just shows a Secret set badge. To replace it, enter a new value. When editing, leave the field blank to keep the current secret.

Creating a connection

Admin or Owner role required.

1. Navigate to Workspace Settings → Connections tab.
2. Click New Connection.
3. Enter a Name and the Base URL of the external system.
4. Choose the Auth type. For Custom header, also enter the Header name (for example X-Api-Key).
5. Enter the Secret. For Basic auth, use the format user:password.
6. Click Save.

Use the edit and delete icons on a connection's row to change or remove it later. Deleting a connection stops any sending that relied on it, so point the affected entities at another connection first.

The workspace default

On the Connections tab, the star icon marks a connection as the workspace default — the system documents are sent to when an entity has no connection of its own. The default connection shows a Workspace default badge.

Clicking the star on the current default clears it, leaving the workspace without a default.

Picking a connection for an entity

Admin or Owner role required.

Use an entity-level pick when a specific entity sends to a different system than the rest of the workspace:

1. Navigate to Entity Management and open the entity.
2. Select the Connection tab.
3. Choose a connection from the Connection dropdown. The empty choice, Workspace default, means the entity uses the workspace default connection.
4. Click Save.

How sending uses connections

When you send a validated document (see Document View), Finpilo runs the Send to Accounting workflow. It posts the document data to:

1. The entity's connection, if the entity has picked one.
2. The workspace default connection otherwise.

If neither exists, the document cannot be sent — create a connection first.

When the external system accepts the document, the status changes to Sent. If the system's reply contains an accounting reference, Finpilo stores it in the document's Accounting Reference field. If it returns no reference, nothing is stored — that is fine. The send time and the system's reply are recorded on the document's History tab.

If the send fails, the document moves to Send Failed and the error is recorded in the history. Fix the connection or the document and send again.

Changing what is sent

Admin or Owner role required.

The send itself is an ordinary workflow you can open and adjust:

1. Navigate to Workspace Settings → Workflows tab and open Send to Accounting.
2. The Send HTTP Request step holds the payload — an editable JSON body where {{field}} references insert values from the document at send time. Type @ in the editor to pick a field. The default payload is described in External API.
3. The Update Field step stores the accounting reference returned by your system in the document's Accounting Reference field.

If you used webhooks before

Connections replace the old webhook settings. Your existing webhook configuration — workspace and entity — was moved into Connections automatically, so sending kept working without any reconfiguration. Each webhook URL and API key became a connection, and an entity that had its own webhook now has that connection picked on its Connection tab.