SaaS companies can embed Peliqan widgets into their own product, in order to offer a wide range of connectors inside their own SaaS platform. The embedding is seamless and offers your end-customers a user-friendly UI to add connections to other platforms that they use, right from within your SaaS platform.

Once your customer added a connection, data is automatically synced to Peliqan and you can access the data through Peliqan's unified API, without the need to communicate directly to hundreds of different APIs. Instead, with a single integration, you can enable integrations between your SaaS platform and hundreds of other SaaS platforms such as ERP, CRM, Accounting, HRM & ATS, PIM, eCommerce etc.

Embedding requires two types of integration:

Front-end integration: embed JS code in your UI
Back-end integration: use Peliqan APIs to fetch data from your end-customers

1. Front-end integration (embedding in your UI)

Front-end embedding is performed in 2 steps:

Fetch an integration_token for a specific end-customer. You identify the end-customer using the external_id which is your unique id for the customer.
Add JS code into your product that renders e.g. a button "Add connection". When the button is clicked, a JS function is invoked that opens a modal, in which the user can choose and add a connection.

1.1 Embedding step 1: fetch an `integration_token`

Make a server-side API call to fetch a short-lived (30 min) integration_token for a specific end-customer using your unique customer ID (external_id in Peliqan):

POST https://app.eu.peliqan.io/api/partner/sub-account/integrate/

Note: the trailing slash at the end of the URL is required !

Authorization: JWT <partner_token>

Request Payload

{
    "external_id": user.id,  # unique entity ID
    "first_name": user.first_name,
    "last_name": user.last_name,
    "email": user.email,
    "company_name": user.organization.name, # your user's organization name
}

1.2 Embedding step 2: add the Peliqan widget in your own UI

Add inside the <head> tag of your UI:

<script type="module" src="https://peliqan.io/embed/v1.3/peliqan-integration.js"></script>

Add a button for users to add connections (integrations):

<div id="peliqan-integration-button">Add connection</div>

Add the following script in your page:

<script type="text/javascript">
  // Wait for the document to be fully loaded
	document.onreadystatechange = () => {
    if (document.readyState === 'complete') {
      const token = "xxx" // Peliqan integration_token for current end-customer (fetch server-side)
	    const base_url = "https://yourwhitelabel.peliqan.io" //replace with your Peliqan whitelabel URL
	    const baseUrl = new URL(base_url)
	    
	    // Instantiate the Peliqan integration
	    // initialize must be called before openIntegration in order to set the required properties
	    Peliqan.initialize({
	      integrationToken: token, 
	      baseUrl:`${baseUrl.protocol}//${baseUrl.hostname}`,
	      onConnected: handleOnConnected, // Optional call-back function, after a successful connection is made
	      loaderHtml: '' // Optional custom loader HTML element that will override the default loading element
	    })
    }
  }
  
  // Event listener for a button click
  const button = document.getElementById('peliqan-integration-button')
  button.addEventListener('click', async function () {
	  // Open the Peliqan integration modal where user can select & add a connection
    // This modal will list all available connectors in Peliqan.
    Peliqan.openIntegration()
  }
</script>

Note that your end-customer will automatically be provisioned (on Peliqan with a new sub-account, linked to your Peliqan partner account) the first time you invoke the Peliqan integration with a token for that specific end-customer.

1.3 Customised list of available connectors

You can optionally provide a list of connectors that should be shown to the user when the modal opens by passing an array of connector names to the availableConnectors property.

The list should be a sub set of connectors available in Peliqan.

<script>
	// Event listener for a button click
  const button = document.getElementById('peliqan-integration-button')
  button.addEventListener('click', async function () {
    Peliqan.openIntegration({
	    // A list of available connectors that the user can select from.
	    // The list is specific to this instance of the modal.
	    availableConnectors: ['exact online', 'zoho invoice', 'slack'],
	  })
  }
</script>

1.4 Pre-select a connector

You can optionally set a connector that should be auto selected when the modal opens. This can be done by providing a connector name to the selectedConnector property.

The user will be shown a connection form where they can fill in the connection details.

<script>
 // Event listener for a third button
  const button = document.getElementById('peliqan-integration-button')
  button.addEventListener('click', async function () {
    Peliqan.openIntegration({
	    // A connection form will be shown for this selected connector. 
	    // The user will not be able to select a different connector.
	    // The selection is specific to this instance of the modal.
	    selectedConnector: 'exact online', 
	  })
  }
</script>

1.5 Callback function

You can optionally implement a call-back function in JS that Peliqan will invoke once a user successfully added a connection. This allows you to e.g. handle the new connection in your front-end. Example:

<script type="text/javascript">
	const handleOnConnected = (responseData) => {
     console.log(responseData)
}
</script>

‣

Example responseData (click to expand)

2. Back-end integration (fetch data from end-customers)

From your back-end, you can make API calls to Peliqan to e.g. retrieve data from end-customer connections, or to activate data integrations (data syncs).

One scenario is to request a list of active customers on Peliqan, for each request the active connections, and for each connection fetch new data:

1. LIST CUSTOMERS AND FOR EACH CUSTOMER:
		2. LIST CONNECTIONS FROM CUSTOMER AND FOR EACH CONNECTION:
				3. GET DATA FROM CONNECTION

It's also possible retrieve data using SQL queries to the Peliqan data warehouse, using a database connection per end-customer.

API authorization

There are 2 types of tokens:

partner token
sub-account tokens

You need to fetch a sub-account token, in order to fetch data for a specific customer or to interact with a sub-account on Peliqan. Fetch a long-lived (non-expiring) JWT token for one end-customer:

GET https//api.eu.peliqan.io/api/partner/sub-account/identity/?external_id=123
Authorization: JWT <partner_token>

Fetch active customers on Peliqan

Each end-customer has a Sub account under your Partner account in Peliqan. List all your sub-accounts:

GET https://app.eu.peliqan.io/api/partner/sub-accounts
Authorization: JWT <partner_token>

Fetch a list of databases from a customer

By default your end-customer will have one data warehouse in Peliqan. Data warehouses and databases are called “applications” in the Peliqan API:

GET https://app.eu.peliqan.io/api/applications/?exclude_tables=1
Authorization: JWT <sub_account_token>

Read data

List tables:

GET https://app.eu.peliqan.io/api/database/tables/database/{database_id}/
Authorization: JWT <sub_account_token>

Read rows (data) from table:

GET https://app.eu.peliqan.io/api/database/rows/table/{table_id}/?user_field_names=True
Authorization: JWT <sub_account_token>

Real-time versus Scheduled data reading

In a real-time scenario, you invoke logic on your backend, from the JS call-back function described above. This allows you to e.g. fetch data from your customer, immediately after a connection was added.
In a scheduled scenario, you make API calls to Peliqan on e.g. an hourly or daily basis, to fetch data from your customers.

3. Additional methods for front-end embedding

These additional functions are available after you have initialized the Peliqan SDK using Peliqan.initialize(). All functions require a sub-account identity token (mentioned above in API Authorisation section). You can then pass the returned JWT token as identityToken to the SDK methods below. You will typically add buttons in your UI, with the below functions as event handlers.

`syncServer`

Triggers the run of a pipeline for a given connection (server).

Example

await Peliqan.syncServer({
  identityToken: subAccountToken,
  serverId: 123
})

Returns

{
  server_id: string,
  health_status: string,
  run_data: [
    {
      pipeline_run_id: number,
      task_id: string
    }
  ],
  task_id: string,
  detail: string,
  syncing: boolean
}

`getServerHealthStatus`

Fetch health information for a specific connection (server).

Example

const status = await Peliqan.getServerHealthStatus({
  identityToken: subAccountToken,
  serverId: 123
})

Returns

{
  id: number,
  name: string,
  health_status: 'OK' | 'HEALTHY' | 'ERROR' | 'CHECKING' | 'AUTHORIZING' | 'CONFIG_SELECT' | 'DISABLED' | 'RE_ENABLED' | 'RE_AUTHORISED' | 'RE_AUTHORISING' | 'COMPLETED_WITH_ERRORS'
}

`getServerSyncRunStatus`

Check whether a “run pipeline” job is currently running for a given connection (server).

Poll this when showing a “Syncing…” indicator or progress UI.

Example

const { running } = await Peliqan.getServerSyncRunStatus({
  identityToken: subAccountToken,
  serverId: 123
})

Returns

{ running: boolean }

`reAuthoriseServer`

Use this if you wish to re-authorise any oAuth connection .

This function opens the required authorization URL in a new browser tab.

If the Peliqan back-end returns an auth_uri, it is automatically opened in a new browser tab.

Example

await Peliqan.reAuthoriseServer({
  identityToken: subAccountToken,
  serverId: 123
})

`manualRefreshSaltEdge`

Special helper for SaltEdge banking connections that require manual refresh (trigger SaltEdge to fetch new banking transactions).

This requests the SaltEdge Refresh URL and opens it in a new tab.

Example

await Peliqan.manualRefreshSaltEdge({
  identityToken: subAccountToken,
  serverId: 123
})

Embedding

1. Front-end integration (embedding in your UI)

1.1 Embedding step 1: fetch an integration_token

1.2 Embedding step 2: add the Peliqan widget in your own UI

1.3 Customised list of available connectors

1.4 Pre-select a connector

1.5 Callback function

2. Back-end integration (fetch data from end-customers)

API authorization

Fetch active customers on Peliqan

Fetch a list of databases from a customer

Read data

Real-time versus Scheduled data reading

3. Additional methods for front-end embedding

syncServer

getServerHealthStatus

getServerSyncRunStatus

reAuthoriseServer

manualRefreshSaltEdge

1.1 Embedding step 1: fetch an `integration_token`

`syncServer`

`getServerHealthStatus`

`getServerSyncRunStatus`

`reAuthoriseServer`

`manualRefreshSaltEdge`