API requirements to add your Connector onQlik Application Automation for OEM

This article describes what is needed to add a Connector to your SaaS platform onQlik Application Automation for OEM.

See also How Qlik Application Automation for OEM connects to your SaaS platform for alternatives in case your platform does not have an API.

What is a Connector?

Qlik Application Automation for OEM has over 500 Connectors to various cloud applications such as CRM's, marketing automation platforms, databases, etc.

The Connectors are used inside automations (workflows) to build an actual integration. A Connector uses the API of the SaaS application. Each API endpoint becomes a building block inside the automation editor.

If you want to build an integration between your SaaS platform and other platforms, you first have to make sure that a Connector to your SaaS platform is available onQlik Application Automation for OEM.

The Qlik Application Automation for OEM integration team will build the Connector to your platform. All you have to do is provide the API documentation and a test account (e.g. a free trial).

API requirements

Qlik Application Automation for OEM can work with any type of API, e.g. a REST API, a GraphQL API or SOAP Web Services, using JSON or XML. We do not have any specific requirements on how the API should work, but of course, the Connector will be limited to the features offered by your API.

We can work with any type of API documentation: a PDF, a Swagger file, a Postman file, etc.

Authentication

Qlik Application Automation for OEM supports any type of authentication:

• oAuth1 (1-legged, 3-legged)
• oAuth2 (2-legged, 3-legged)
• Custom oAuth flows
• API tokens, JWT web tokens or keys
• Login and password
• etc.

Paging

We prefer API's that support paging when returning a list of items. Qlik Application Automation for OEM supports any type of paging:

• Cursor based
• Paging parameters
• Etc.

Sorting

Some use cases require that data can be retrieved sorted by timestamp created or timestamp the last update.

Timestamps

We prefer to have timestamp created and timestamp last update (e.g. as an epoch unix timestamp) in the response for each object.

Sideloading

Sideloading means that related objects are also returned in the response, e.g. when requesting a list of customers, each customer object would have a property orders with the actual orders of the customer. While sideloading can limit the number of API calls made, we typically do not use this feature in our Connectors.

Error handling

Qlik Application Automation for OEM can handle any type of error messages, we do prefer detailed error messages and correct usage of HTTP response status codes.

CRUD endpoints

We need CRUD (Create, Read, Update, Delete) endpoints for each object type (e.g. Contacts, Companies, etc.).

It's also possible to create a read-only connector in case your SaaS platform is only a source of data and not a destination of data.

Example CRUD endpoints for one object type:

• List: returns a full list
• Search: returns a filtered list based on various search criteria
• Get: returns one record (one object)
• Create: creates a new object
• Update: updates an existing object
• Delete: deletes an object

Get by other fields

In many use cases, it's useful to be able to retrieve a single object not by its id, but by using another unique property.

Examples:

• Get contact by email
• Get company by VAT number
• Get company by domain

Incremental endpoints

For data synchronization, it's very useful to be able to request new and/or updated records since a given timestamp. These API endpoints are implemented in Qlik Application Automation for OEM as Incremental blocks, e.g. List updated contacts incrementally. Such blocks are useful in scheduled integrations to process new data incrementally on each run (e.g. every 5 minutes or every 30 seconds).

Example endpoints:

• Get new contacts created since timestamp X (timestamp_created >= X, where X is a unix epoch timestamp)
• Get new and updated contacts since timestamp X (timestamp_lastupdate >= Y) Note that this can also be accomplished with webhooks, but webhooks do not allow to process historical data (a.k.a. doing full initial sync).

Meta data

We appreciate the ability to request meta data through the API. Examples:

• List object types (useful for platforms that support custom objects)
• List fields of object type (useful for platforms that support custom fields)

Webhooks

Qlik Application Automation for OEM supports incoming webhooks (triggers). Ideally, the API allows to create and manage webhooks so that the creation of webhooks can be automated. Example endpoints:

• Add webhook
• Remove webhook
• List webhooks (from one account)

EventTech API's

Common API endpoints specifically for EventTech integrations:

• CRUD endpoints for all object types (Event, Session, Attendee category, Attendee etc.)
• Incremental endpoint get new & updated registrations since timestamp X
• Check-in an attendee for an event or a session (when syncing from an on-site solution to your API)
• Incremental endpoint get check-ins for event or session since timestamp X (for on-site scanning solutions)

Cloud telephony API's (VoIP, UCaaS etc.)

Below we describe common API endpoints specifically for common use cases for cloud telephony integrations.

Contact sync

• CRUD endpoints for Contacts
• Ability to add Contacts in a Directory, Group or Phonebook (to group them per source).
• Ability to store an external_id for Contacts: this is needed when a direct link needs to be opened to a detail page in a CRM when a call comes in. We will store the id of the CRM in this field.
• Ability to get contact by its external_id.
• Ability to store extra data per Contact (e.g. a field extra_data where we can store a JSON object). This is needed for e.g. dynamic call routing based on data coming from a CRM.

Call logging in a CRM

Webhooks on incoming call and/or API endpoints to list calls (incrementally, meaning where timestamp > x).

Dynamic routing based on external data (CRM data or similar)

• With shadow copy: calls are routed based on Contact data inside the cloud telephony system, see above: field extra_data on Contact (or similar) to store CRM data, e.g. as a JSON object.
• Without shadow copy: real-time lookup in e.g. a CRM on an incoming call. In this scenario, we need a webhook on incoming calls and the ability to update a live call via the API (e.g. update routing of an active call).

Need inspiration for your API?

Are you still building out your API? We recommend having a look at modern API's from platforms such as Hubspot, Eventbrite, and many others, to get an idea of how they implemented their API.

Some articles on how to build a good REST API:

• REST API Tutorial
• Restful API Design - Step By Step Guide
• The Qlik Application Automation for OEM ultimate API checklist: API Checklist