> ## Documentation Index
> Fetch the complete documentation index at: https://docs.borga.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Accounting Link API — connect accounting providers

> Connect and manage accounting provider integrations to automatically sync invoices, apply VAT codes, and map revenue to general ledger accounts.

Accounting Link connects your Borga account to your accounting software so that invoices, credit notes, and payments sync automatically. Borga supports both OAuth-based providers (which redirect users through an authorization flow) and form-based providers (where you supply credentials directly). Once connected, you can map VAT codes and GL accounts to control how transactions are posted.

<Tip>
  For a step-by-step walkthrough of setting up an accounting integration, see the [Accounting Link setup guide](/guides/accounting-link).
</Tip>

***

## List providers

`GET /v1/accounting_link/providers`

Returns a list of available accounting providers and their connection methods.

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.borga.is/v1/accounting_link/providers \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

### Response fields

<ResponseField name="data" type="object[]" required>
  Array of provider objects.

  <Expandable title="provider fields">
    <ResponseField name="id" type="string" required>
      Provider identifier (e.g. `xero`, `quickbooks`, `dynamics`).
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Display name of the provider.
    </ResponseField>

    <ResponseField name="auth_type" type="string" required>
      Authentication method: `oauth` or `form`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "xero",
        "name": "Xero",
        "auth_type": "oauth"
      },
      {
        "id": "dynamics",
        "name": "Microsoft Dynamics",
        "auth_type": "form"
      }
    ]
  }
  ```
</ResponseExample>

***

## Start a connection

`POST /v1/accounting_link/connect`

Initiates a connection to an accounting provider. For OAuth providers, the response includes a `redirect_url` — send the user there to authorize the connection. For form-based providers, use [complete a connection](#complete-a-connection) instead.

### Request parameters

<ParamField body="provider" type="string" required>
  The provider ID to connect to (e.g. `xero`, `quickbooks`).
</ParamField>

<ParamField body="mode" type="string">
  The mode to connect in. One of `test` or `live`. Defaults to `live`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.borga.is/v1/accounting_link/connect \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx" \
    --header "Content-Type: application/json" \
    --data '{
      "provider": "xero",
      "mode": "live"
    }'
  ```
</RequestExample>

### Response fields

<ResponseField name="redirect_url" type="string">
  The OAuth authorization URL to redirect the user to. Present for OAuth providers only.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "redirect_url": "https://login.xero.com/identity/connect/authorize?..."
  }
  ```
</ResponseExample>

***

## Complete a connection

`POST /v1/accounting_link/complete`

Completes a form-based provider connection by submitting credentials directly. Not applicable to OAuth providers.

### Request parameters

<ParamField body="provider" type="string" required>
  The provider ID to connect to.
</ParamField>

<ParamField body="credentials" type="object" required>
  Provider-specific credential fields. Refer to your accounting provider's API documentation for the required fields.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.borga.is/v1/accounting_link/complete \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx" \
    --header "Content-Type: application/json" \
    --data '{
      "provider": "dynamics",
      "credentials": {
        "client_id": "...",
        "client_secret": "...",
        "tenant_id": "..."
      }
    }'
  ```
</RequestExample>

### Response fields

Returns the created `AccountingLink` object. See [get current link](#get-current-link) for the full field reference.

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "alink_01hx9z3k2mfq7nbvd4cw8ej5rt",
    "provider": "dynamics",
    "status": "active",
    "mode": "live",
    "created_at": "2026-04-29T10:15:00Z"
  }
  ```
</ResponseExample>

***

## OAuth callback

`GET /v1/accounting_link/callback/{provider}`

OAuth providers redirect to this endpoint after the user authorizes access. Borga handles the token exchange automatically — you do not need to call this endpoint directly. It is documented here for reference if you need to configure a redirect URI in your OAuth provider's settings.

### Path parameters

<ParamField path="provider" type="string" required>
  The provider completing the OAuth flow (e.g. `xero`).
</ParamField>

***

## Get current link

`GET /v1/accounting_link`

Returns the current accounting provider connection for your merchant account.

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.borga.is/v1/accounting_link \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

### Response fields

<ResponseField name="id" type="string" required>
  Unique accounting link identifier.
</ResponseField>

<ResponseField name="provider" type="string" required>
  Connected provider ID.
</ResponseField>

<ResponseField name="status" type="string" required>
  Connection status. One of `active`, `disconnected`, or `error`.
</ResponseField>

<ResponseField name="mode" type="string" required>
  Connection mode: `test` or `live`.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of when the connection was established.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "alink_01hx9z3k2mfq7nbvd4cw8ej5rt",
    "provider": "xero",
    "status": "active",
    "mode": "live",
    "created_at": "2026-04-29T10:15:00Z"
  }
  ```
</ResponseExample>

***

## Disconnect

`DELETE /v1/accounting_link`

Disconnects the current accounting provider. Borga will stop syncing invoices and payments immediately. Existing records in your accounting software are not affected.

<RequestExample>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url https://api.borga.is/v1/accounting_link \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

### Response fields

Returns an empty body with a `204 No Content` status on success.

<ResponseExample>
  ```json 204 theme={null}
  {}
  ```
</ResponseExample>

***

## Get chart of accounts

`GET /v1/accounting_link/chart_of_accounts`

Returns the chart of accounts from your connected accounting provider. Use the GL account codes returned here when configuring default accounts in [update settings](#update-settings).

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.borga.is/v1/accounting_link/chart_of_accounts \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

### Response fields

<ResponseField name="data" type="object[]" required>
  Array of GL account objects from your accounting provider.

  <Expandable title="account fields">
    <ResponseField name="code" type="string" required>
      GL account code.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      GL account name.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      Account type (e.g. `revenue`, `liability`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "code": "4000",
        "name": "Sales Revenue",
        "type": "revenue"
      },
      {
        "code": "2200",
        "name": "VAT Payable",
        "type": "liability"
      }
    ]
  }
  ```
</ResponseExample>

***

## Get VAT codes

`GET /v1/accounting_link/vat_codes`

Returns the VAT codes available in your connected accounting provider. Use these when configuring VAT mappings in [update settings](#update-settings).

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.borga.is/v1/accounting_link/vat_codes \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

### Response fields

<ResponseField name="data" type="object[]" required>
  Array of VAT code objects.

  <Expandable title="VAT code fields">
    <ResponseField name="code" type="string" required>
      VAT code identifier.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Display name.
    </ResponseField>

    <ResponseField name="rate" type="number" required>
      VAT rate as a percentage (e.g. `24` for 24%).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "code": "IS24",
        "name": "Standard Rate 24%",
        "rate": 24
      },
      {
        "code": "IS11",
        "name": "Reduced Rate 11%",
        "rate": 11
      }
    ]
  }
  ```
</ResponseExample>

***

## Update settings

`POST /v1/accounting_link/settings`

Updates the accounting sync configuration for your connection. Use this to map VAT codes from Borga to your provider, and to set the default GL account for revenue posting.

### Request parameters

<ParamField body="default_gl_account" type="string">
  GL account code to use as the default revenue account when posting invoices.
</ParamField>

<ParamField body="vat_code_mapping" type="object">
  A map of Borga VAT rate identifiers to provider VAT code strings. For example, `{ "standard": "IS24", "reduced": "IS11" }`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.borga.is/v1/accounting_link/settings \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx" \
    --header "Content-Type: application/json" \
    --data '{
      "default_gl_account": "4000",
      "vat_code_mapping": {
        "standard": "IS24",
        "reduced": "IS11"
      }
    }'
  ```
</RequestExample>

### Response fields

<ResponseField name="default_gl_account" type="string">
  The configured default GL account code.
</ResponseField>

<ResponseField name="vat_code_mapping" type="object">
  The configured VAT code mapping.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "default_gl_account": "4000",
    "vat_code_mapping": {
      "standard": "IS24",
      "reduced": "IS11"
    }
  }
  ```
</ResponseExample>