CRM SDK: unified CRM API for Node and Python

A unified CRM SDK is a library that gives your application one set of calls for many CRM systems. CRM stands for customer relationship management: the software where a sales team keeps its contacts, companies and deals.

Each CRM has its own API, its own field names, its own login flow and its own limits. A product that integrates with five CRMs would otherwise carry five versions of the same code. A unified layer replaces that with one model of a contact, one model of a deal and one way to read changes.

Two designs exist, and the difference decides where customer data travels.

A hosted API suits a team that wants the integration handled for it. An SDK suits a team that handles sensitive customer data, or one that wants no third party in the middle. This SDK takes the second design.

The repository holds 29 connector specifications. Coverage varies by CRM, because each provider exposes different objects, so a capability matrix states what each connector declares.

A specification differs from a tested integration. Nine connectors are active on a live sandbox, and the others wait for a sandbox account. Self hosted Odoo, EspoCRM, SuiteCRM and Twenty accept a customer host, and the local sandboxes cover Odoo 16 to 20.

The server creates one object and mounts its routes.

import express from 'express';
import { createCrm, createMemoryStores, toNodeListener } from '@ilanoh/crm';
import { authorize, sessionActor } from './crm-policy.js';

export const crm = await createCrm({
  ...createMemoryStores(),
  keys: { k1: process.env.CRM_KEY },
  active_key_id: 'k1',
  redirect_base_url: `${process.env.APP_URL}/crm`,
  return_to_allowlist: [`${process.env.APP_URL}/settings/`],
  base_path: '/crm',
  connectors: ['hubspot'],
  oauth: {
    hubspot: {
      client_id: process.env.HUBSPOT_CLIENT_ID,
      client_secret: process.env.HUBSPOT_CLIENT_SECRET,
    },
  },
  authenticateRequest: sessionActor,
  authorize,
});

const app = express();
app.use(toNodeListener(crm.handlers));

Memory stores suit a test. Production uses the Postgres or Mongo stores, which sit in your own database. Your two functions, authenticateRequest and authorize, plug the SDK into your existing login and permissions. Quickstarts cover Express, Fastify, Django, React and plain HTML.

In the browser, your user clicks a connect button, a web component.

<crm-connect base-path="/crm" lang="en" status-model="contact"></crm-connect>

The component ships with a React wrapper and a headless core, so it can adopt your design.

Reading uses one call for any connector.

const client = crm.connection(connectionId, { principal: job });
const page = await client.list('contact', { limit: 100 });

A page holds items and a next_page_token. The token is signed, bound to its connection and expires after 24 hours at most. A filter the provider cannot apply raises Unsupported before any request, so your code never receives silently unfiltered data.

Writing follows patch rules that hold across every connector.

fillEmpty suits enrichment. It writes only the fields that are empty, so a value entered by a salesperson stays in place, and the result lists what it wrote and what it kept.

A write retries only when the retry cannot apply it twice. When the outcome is unknown, the SDK says so, which keeps duplicates out of a customer's CRM.

A sync has to survive crashes, parallel workers and provider limits. The SDK handles that loop: only one worker syncs a given connection at a time, and a crash resumes where the last committed page ended.

Providers offer very different ways to read changes, and your code calls the same function for all of them. Check the capability matrix before you promise a sync frequency, because some CRMs need a full read while others offer a change feed.

Two runtimes usually drift apart. Here, both read the same connector specifications and must return identical results on the same recorded fixtures, so a Python worker and a Node API can share one table. Django has its own integration.

An MCP server exposes the SDK to AI agents. MCP, the Model Context Protocol, is a standard way for an agent to call tools. Docs mode lets a coding agent read the specifications and add a connector, and app mode lets an agent act on a connected CRM under the permissions of its principal.