The Peliqan Partner API (Embed API) is used by SaaS software companies and ISVs to embed data solutions running on the Peliqan platform into their own web UI. The Embed API (Partner API) is used to automate the provisioning and hydration of end-customer tenants on Peliqan.io.

Naming conventions

Partner: SaaS company or ISV
End-customer: the customer of the Partner
Partner account: the Peliqan.io account to which the Partner logs in
End-customer account: a Peliqan account for the End-customer (created through the Embed API)

Service models

Peliqan.io support two service models:

Full-service: the Professional Services team or Customer Success team of the Partner takes care of setting up data solutions for end-customers. They can use the Peliqan platform to setup end-customer accounts, activate solutions and/or build out custom solutions. —> typically no need for the Embed API.
Self-service: End-customers of the Partner need to activate data solutions in a self-service manner —> need for Embed API.

Embedding methods

Peliqan.io support 2 embedding methods:

Server-side: Partner uses a non-expiring JWT token to use the Peliqan Embed API.
Client-side: Partner uses an expiring JWT tokens per tenant (end-customer account).

CORS for client-side embedding

Peliqan.io will add a CORS header in the API responses, for the domain name that you provided in your Partner account. Example: Access-Control-Allow-Origin: acme.com

Authentication

Use the JWT token from your Partner account, to create new end-customer accounts and to fetch a JWT token per end-customer tenant. All other API calls (adding a connection inside a sub account etc.) will happen with the JWT token of the sub account.

Create end-customer account

API endpoints to manage end-customer accounts:

POST, PUT, GET, DELETE /api/subaccount

Authorization: JWT <partner_token>

Example body payload:

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@woodsolutions.com",
  "language": "en",
  "company_name": "Wood Solutions Ltd",
  "external_id": "wood_123"          # required, your unique customer id
}

Get JWT token for end-customer account

API endpoint:

GET /api/subaccount/{subaccount_id}/token

Or using the external_id:

GET /api/subaccount/token?external_id=wood_123

Authorization: JWT <partner_token>

This will return a short lived JWT token that can be used in client-side implementations (in JS).

For server-side implementations, a non-expiring JWT can be requested:

GET /api/subaccount/{subaccount_id/token?expire=false

GET /api/subaccount/token?external_id=wood_123&expire=false

Get connector definition

GET /api/servertypes

Authorization: JWT <partner_token>

The response includes the “connect form” for each connector. This is needed to know which params are required to add a connection, e.g. for Hubspot or Pipedrive.

Add a connection

Get the “connect form” first (see above), and include the required connection fields when creating a new connection on behalve of an end-customer. A connection is called a “server” in the API.

API endpoint:

POST /api/servers

Authorization: JWT <end_customer_token>

Connector with API key or login/password as credentials

Body (assuming the required fields for the connect form are “login” and “password”):

{
   "servertype_id": 123,  # e.g. Pipedrive
   "login": "xxx",
   "password": "xxx"
}

Connector with oAuth2 flow

Initiate oAuth flow

For connectors that use an oAuth flow, the response will contain a redirect URL.

Example redirect URL provided to the partner:

{
  "id": 12345,  # id of the connection, see below, needed to fetch status
  "oauth_url": "https://api.some_crm.com/oauth2/authorize?..."
}

The redirect URL (oauth_url) needs to be opened from the Partner UI, in a new browser tab or window, so that the end-customer can complete the oAuth flow. Make sure to provide a "Powered by Peliqan" message prior to the oAuth flow, because the user will be asked to allow Peliqan to access their data (unless you have configured a private oAuth app).

Continue after redirect

From the Partner UI, you need to listen to the window on close event, and when this event occurs, make an API call to Peliqan to check if the connection was added successfully:

GET /api/server/<connection_id>

Authorization: JWT <end_customer_token>

List connections

GET /api/servers

Authorization: JWT <end_customer_token>

Get status of a connection

GET /api/server/<connection_id>

Authorization: JWT <end_customer_token>

Get logs of a connection

GET /api/server/<connection_id>/logs

Authorization: JWT <end_customer_token>

Create a query table in an end-customer account

POST /table

Authorization: JWT <end_customer_token>

Click here for the full API documentation.

Add a scheduled Python script in an end-customer account

POST /interface

Authorization: JWT <end_customer_token>

{
  "name": "Sync script",
  "raw_code": "...",       # copy this from a template
  "schedule": 3600
}