This article describes what is needed to add a Connector to your SaaS platform on Blendr.io.
What is a Connector ?
Blendr.io has over 300 Connectors to various cloud applications such as CRM's, marketing automation platforms, databases etc.
The Connectors are used inside Blends (workflows) to build an actual integration. A Connector uses the API of the SaaS application. Each API endpoint becomes a building block inside the Blend 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 on Blendr.io.
The Blendr.io 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).
Blendr.io 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.
Blendr.io 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
We prefer API's that support paging when returning a list of items.
Blendr.io supports any type of paging:
- Cursor based
- Paging parameters
Some use cases require that data can retrieved sorted by timestamp created or timestamp last update.
We prefer to have "timestamp created" and "timestamp last update" (e.g. as an epoch unix timestamp) in the response for each object.
Side loading 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 side loading can limit the number of API calls made, we typically do not use this feature in our Connectors.
Blendr.io can handle any type of error messages, we do prefer detailed error messages, and correct usage of HTTP response status codes.
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 field
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.
- Get contact by email
- Get company by VAT number
- Get company by domain
For data synchronisation, it's very useful to be able to request new and/or updated records since a given timestamp. These API endpoints are implemented in Blendr.io 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).
- 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 a full initial sync).
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)
Blendr.io supports incoming webhooks (triggers).
Ideally the API allows to create and manage webhooks so that the creation of webhooks can be automated.
- Add webhook
- Remove webhook
- List webhooks (from one account)
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
Below we describe common API endpoints specifically for common use cases for cloud telephony integrations.
- 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 a 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 look up in e.g. a CRM on incoming call. In this scenario we need a webhook on incoming call and the ability to update a live call via the API (e.g. update routing of an active call).
Need inspiration for your API ?
Some articles on how to build a good REST API:
- The Blendr.io ultimate API checklist: https://www.blendr.io/api-checklist/