Documentation

API and JavaScript documentation for integrating your software with LnkFi.

API

The LnkFi API offers endpoints to allow you to connect, disconnect, reauthorize, and proxy calls to supported systems.

The API is available at: https://api.lnkfi.com

POST

/v1/connection/authorize

Get an authorization URL for a system to establish a new connection or reauthorize an existing connection. Once a connection is authorized, you will receive a webhook at the address provided with the connection details.

Request

Headers

Content-TypeThe content type of the request. Should always be application/json.
application/json

Parameters

systemThe system you are wanting to connect. Support systems include: xero.
stringrequired
vendor_idYour vendor ID that is provided by LnkFi.
stringrequired
vendor_external_idAn external ID that is used to identify which account or user in your system this connection belongs to.
stringoptional
system_client_idThe client ID for the system selected. This is optional if passing existing_connection_id.
stringrequired
system_client_secretThe client secret for the system selected. This is optional if passing existing_connection_id.
stringrequired
vendor_redirect_urlThe URL that the user will be redirected to after authorizing the connection. This will include ?result=success|canceled|error.
stringrequired
consent_givenRequired to be passed as true. You must display to the end user and obtain consent from them:

I consent to [Your Company Name] and LnkFi using the data I have submitted here (including my user credentials to pull the applicable data from the Third Party Services associated with such user credentials) on my behalf, and to LnkFi providing that applicable data to [Your Company Name]. I agree that I have reviewed any applicable Third Party Service legal terms and have authority to send data to [Your Company Name] via LnkFi.This is optional if passing existing_connection_id.
booleanrequired
existing_connection_idThe ID of an existing connection that is wanting to be reauthorized.
stringoptional

Important

When passing in the system_client_id and system_client_secret, the application will need to whitelist LnkFi's redirect URI: https://link.lnkfi.com/v1/connection/authorize/<system>/complete

Response

Content-Type: application/json

Parameters

authorization_urlThe URL that you will redirect the user to in order to authorize the connection.
string
systemThe system that the connection is for.
string
vendor_idThe vendor ID that is provided by LnkFi.
string
vendor_external_idThe external ID that is used to identify which account or user in your system this connection belongs to.
string
existing_connection_idThe ID of an existing connection that is wanting to be reauthorized.
string

Sample Response

{
  "authorization_url": "https://login.xero.com/....",
  "system": "xero",
  "vendor_id": "vnd_00000000-0000-0000-0000-000000000000",
  "vendor_external_id": "user_1234567890"
}

DELETE

/v1/connection

Disconnects an existing connection. A disconnected connection can be reauthorized at a later time if the ID is passed into the connection endpoint.

Request

Headers

Content-TypeThe content type of the request. Should always be application/json.
application/json
AuthorizationThe authorization header for the request. Include the API Key for the connection.
APIKey <api_key>

Parameters

vendor_idYour vendor ID that is provided by LnkFi.
stringrequired
connection_idThe ID of the connection you are wanting to disconnect.
stringrequired

Response

Content-Type: application/json

Parameters

statusThe status of the connection. This will be "disconnected" if the connection was successfully disconnected.
string

Sample Response

{
  "status": "disconnected"
}

POST

/v1/connection/proxy

Proxies a request to the system's API on behalf of a connection.

Request

Headers

Content-TypeThe content type of the request. Should always be application/json.
application/json
AuthorizationThe authorization header for the request. Include the API Key for the connection.
APIKey <api_key>

Parameters

connection_idThe ID of the connection you are wanting to proxy a request to.
stringrequired
urlThe URL that you are wanting to proxy a request to.
stringrequired
instance_idThe ID of the instance you are wanting to proxy a request to.
stringrequired

Response

Content-Type: application/json

Headers

X-RateLimit-Day-RemainingThe number of requests remaining for the day.
XXX
X-RateLimit-Minute-RemainingThe number of requests remaining for the minute.
XXX

Sample Response

{
  "Id": "242a5822-db78-42d6-8d02-4061997d3f37",
  "Status": "OK",
  "ProviderName": "Reports",
  "DateTimeUTC": "/Date(1726845251839)/",
  "Reports": [
    {
      "ReportID": "BalanceSheet",
      "ReportName": "Balance Sheet",
      "ReportType": "BalanceSheet",
      "ReportTitles": [
        "Balance Sheet",
        "Testing",
        "As at 30 September 2024"
      ],
      "ReportDate": "20 September 2024",
      "UpdatedDateUTC": "/Date(1726845251839)/",
      "Fields": [],
      "Rows": [
        {
          "RowType": "Header",
          "Cells": [
            {
              "Value": ""
            },
            {
              "Value": "30 Sep 2024"
            },
            {
              "Value": "30 Sep 2023"
            }
          ]
        }
      ]
    }
  ]
}

Webhooks

LnkFi's webhooks provide a way to receive notifications when a connection is authorized, disconnected, or reauthorized.

Example Webhook

X-LnkFi-Webhook-Id: owh_00000000-0000-0000-0000-000000000000
X-LnkFi-Webhook-Vendor-Id: vnd_00000000-0000-0000-0000-000000000000
X-LnkFi-Webhook-Signature: xxxxx
User-Agent: LnkFi/1.0.0
Content-Type: application/json

{
  "type": "connection_completed",
  "system": "xero",
  "api_key": "xxxxxxx",
  "instances": [
    {
      "id": "be78c3f7-e85d-4cd7-8ef1-125718a2ef31",
      "display": "Acme"
    }
  ],
  "vendor_id": "vnd_xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "vendor_external_id": "1234567890"
}

Verifying Webhooks

To verify that the webhook is coming from LnkFi, you can use the signature to verify the webhook. The signature is an HMAC-SHA256 hex encoded string using the vendor's webhook secret and the webhook's raw body.

The signature is sent in the X-LnkFi-Webhook-Signature header.

JavaScript Library

LnkFi's JavaScript Library provides pre-built UI that can be used to initiate connections through LnkFi on your company's app.

Authorize a new Connection via Web Component

You can use the provided web component to render the standard modal. data-open controls whether or not the modal is visible. Slots are provided for customization. Supported slots include an accessory to the right of the title for each step.

<script src="https://cdn.lnkfi.com/lnkfi.js"></script>

<lnkfi-modal
  data-open="true"
  data-vendor-id="vnd_00000000-0000-0000-0000-000000000000"
  data-system="xero"
  data-legal-name="Acme, Inc."
  data-redirect-url="http://acme.com/redirect"
  data-vendor-external-id="user_1234567890"
>
  <span slot="step-1-title-accessory"></span>
  <span slot="step-2-title-accessory"></span>
  <span slot="step-3-title-accessory"></span>
</lnkfi-modal>

Authorize a new Connection via Function

If you would rather open the modal via a function call, you can use the following example.

<script src="https://cdn.lnkfi.com/lnkfi.js"></script>

<button
  onclick="window.lnkfi.openWidget({
  vendorId: 'vnd_00000000-0000-0000-0000-000000000000',
  legalName: 'Acme, Inc.',
  system: 'xero',
  redirectUrl: 'http://acme.com/redirect',
  vendorExternalId: 'user_1234567890',
})"
>
  Connect
</button>

Re-Authorize an Existing Connection

<script src="https://cdn.lnkfi.com/lnkfi.js"></script>

<button
  onclick="window.lnkfi.reauthorize({
  vendorId: 'vnd_00000000-0000-0000-0000-000000000000',
  system: 'xero',
  redirectUrl: 'http://acme.com/redirect',
  existingConnectionId: 'con_00000000-0000-0000-0000-000000000000',
})"
>
  Re-Authorize
</button>