contackd-sync (TS/JS)

TypeScript/JavaScript SDK for pushing and syncing customer data (contacts, leads, prospects, businesses).

Install

npm install contackd-sync

2-Minute Start (Push Customer Details)

import { ContackdClient } from "contackd-sync";

const client = new ContackdClient({
  apiKey: "sk_live_...",
  baseUrl: "https://api.yourapp.com/api/v1", // no trailing slash required
});

// Create/update a customer contact by email
const customer = await client.contacts.upsert({
  email: "[email protected]",
  firstName: "Jane",
  lastName: "Doe",
  phone: "+14155550199",
  tags: ["customer", "vip"],
  custom: {
    customerId: "CUST-1001",
    plan: "pro",
    country: "US",
  },
});

console.log(customer);

Common Customer Push Patterns

1) Push one new customer

await client.contacts.create({
  email: "[email protected]",
  firstName: "New",
  lastName: "Customer",
});

2) Push many customers (bulk upsert)

const result = await client.contacts.bulkUpsert([
  { email: "[email protected]", firstName: "A" },
  { email: "[email protected]", firstName: "B", tags: ["trial"] },
]);

console.log(result.created.length, result.updated.length, result.errors);

3) Read/filter customers

const page1 = await client.contacts.list(1, 50, { email: "[email protected]" });

Sync Businesses Before Their Contacts

Create or update businesses first so contacts can reference the returned CRM business IDs. Business synchronization uses externalBusinessId as its primary natural key and falls back to the normalized business name.

import { ContackdClient } from "contackd-sync";

const client = new ContackdClient({
  apiKey: "sk_live_...",
  baseUrl: "https://api.yourapp.com/api/v1",
});

const businessResult = await client.businesses.bulkUpsert([
  {
    name: "Default Facility",
    externalBusinessId: "bb7d2b66-034a-4333-8573-dce07b9684ed",
    stage: "customer",
    status: "active",
    tags: ["FACILITY"],
    custom: { org_code: "FACILITYBILLS" },
  },
]);
const business = [...businessResult.created, ...businessResult.updated][0];

await client.contacts.bulkUpsert([
  {
    email: "[email protected]",
    firstName: "Resident",
    externalContactId: "resident-1",
    businessId: business.id,
    tags: ["RESIDENT"],
    custom: { role: "resident" },
  },
]);

Callers should merge duplicate source rows before sending them. For a person belonging to multiple estates, keep the complete estate list in custom and use businessId for the single primary CRM relationship.

API Key Setup

Contact [email protected] for the API key and base domain.

Backend Routes Expected by SDK

Given baseUrl = https://api.yourapp.com/api/v1:

• GET /health
• POST /tags
• GET /tags
• GET /tags/{id}
• PUT /tags/{id}
• DELETE /tags/{id}
• POST /contacts|leads|prospects|businesses
• GET /contacts|leads|prospects|businesses/{id}
• PUT /contacts|leads|prospects|businesses/{id}
• DELETE /contacts|leads|prospects|businesses/{id}
• GET /contacts|leads|prospects|businesses
• POST /contacts|leads|prospects|businesses/upsert
• POST /contacts|leads|prospects|businesses/bulk
• POST /contacts|leads|prospects|businesses/bulk/upsert
• POST /contacts|leads|prospects|businesses/bulk/delete