Universal CRM API

Read and write data in your users' CRMs

Xkit's Universal CRM API enables your app to interact with data in your user's CRM in a consistent way, regardless of which CRM they use or what customizations they have applied.

CRM configurations are as unique as the businesses they power, so user-driven configuration is a must for CRM integrations.

The Universal CRM API allows your app to:

  • Read data from the user's CRM in a consistent format
  • Get notified of changes to data in the user's CRM
  • Add and change data in the user's CRM in a consistent way

The Universal CRM API allows your users to:

  • Configure the objects and fields that best map to what your app needs
  • Control what data is exposed to your app
  • Manage how changes happen to their data

Authenticating with the API

To authenticate with the Universal CRM API, you'll need a set of API keys. API keys issued by Xkit come in pairs:

  • a publishable key, which acts as a username and can be stored in cleartext
  • a secret key, which acts as a password and should be protected as such

Generating an API Key

To get an API Key set, you need to generate it in the Xkit Developer Portal.

Click on Generate API Key in the API Keys section on the settings page. Copy the publishable key and secret key shown.

Generating an API Key set

It's important to note that the secret API key will be shown to you once, and cannot be retrieved by Xkit again after that, so be sure to keep it safe.

You can also revoke API Keys. Look at the guide on Rotating API Keys.

Using the API Key

Xkit API endpoints are secured via HTTP Basic Authentication over HTTPS.

To prepare the credentials, construct a string as XKIT_PUBLISHABLE_KEY:XKIT_SECRET_KEY, and then encode it using base64.

When you make a call to an API endpoint, pass an Authorization header with the value Basic <credentials>.

As an example, let's take your publishable key to be foo and your secret key to be bar. When we base64 encode foo:bar, we get Zm9vOmJhcg==. Here's what an API call would look like with those credentials:

GET /api/v1/crm/.../ HTTP/1.1
Host: app.xkit.co
Authorization: Basic Zm9vOmJhcg==

Below, within examples that represent interactions with the API, you will find Authorization: Basic <credentials>, which represent this concept.

Using connection IDs

When a user calls linkCRM and successfully maps data from their CRM for you to access, the linkCRM method will resolve the returned promise with the ID of the CRM connection. If you are passing the context ID for the connectionID option as seen in the usage examples for CRM Link, then the connection ID returned will be the same as the context ID passed.

You will need the connection ID later when calling the CRM API. We recommend storing this ID in your database against the context, i.e. the entity for whom the CRM is being linked.

Your application might allow an entity to link multiple instances of the same CRM, or multiple CRMs. In that case, we suggest storing the connection IDs along with any additional data (such as the name of the CRM, type of connection, etc.) in a fashion that helps you decide which connection ID to pick when making one or more calls to the CRM API.

Below, within examples that show interactions with the API, you will find <connectionID> in the request URL, which will represent such a connection ID.

It is possible for a connection to enter an invalid state. For example, a user could disconnect a CRM instance, or the connection could expire or error out. We recommend subscribing to connection events so that your application can appropriately update the connection IDs stored and avoid making requests to the CRM API for invalid connections.

CRM Objects

CRM Objects are objects that already exist in your users' CRM and are relevant to your application.

You can think of these as your app's view of a generic CRM, which your user will then map to their actual CRM.

Here's an example of a user mapping a CRM object to an actual object in their CRM:

Selecting an object in CRM Link

An example CRM Object for an e-signature SaaS App would be an "Opportunity", which might be linked to an Opportunity, a Deal, or some other object based on the specific user's CRM.

For each CRM Object, you'll define fields that you want to read from the CRM, and events that you can invoke to find and change data in the CRM.

Create in Developer Portal

While logged into the Xkit Developer Portal, click on "CRM Objects" in the menu.

Click "Add CRM Object" and add the requested information. Creating a CRM Object in the Xkit Developer Portal

  • Slug: the name of your CRM Object as it appears in the Xkit API, e.g. opportunity
  • Name: the name of the CRM Object as it appears to users during mapping, e.g. Opportunity
  • Description: a description of the CRM Object to help your users determine the right object in their CRM to map to it, e.g,: "Acme associates documents with Opportunities or Deals in your CRM and pre-populates document templates based on data available in the Opportunity"

After you've installed CRM Link, add an empty configuration object to the objects property of the options object of linkCRM of the format: { fields: {}, events: {} }.

For our example with an opportunity CRM object, that looks like this:

await linkCRM('example.xkit.co', token, {
  connectionID: 'context-id',
  objects: {
    opportunity: {
      fields: {},
      events: {}
    }
  }
})

In the upcoming sections, we'll add fields and events.

Up next

Universal CRM API - Reading data

Read data from your users' CRMs

Read more ▶

Ready to build your CRM app?

Integrate every CRM with one build, request access to get started.