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
Embedding is performed in 2 steps:
- Fetch an
integration_tokenfor a specific end-customer. You identify the end-customer using theexternal_idwhich 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.
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
}
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.2/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.
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>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>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>Get data
From your backend, 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 CONNECTIONIt'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.