Node / TypeScript SDK

@centerfy/sdk is a typed client for every endpoint, with retries, typed errors and an agency client.

Every endpoint page has a Node SDK tab showing the exact call, and SDK methods lists all of them in one place. This page covers setup and the parts that apply everywhere.

Install

npm install @centerfy/sdk

Node.js 18 or newer (uses the global fetch).

Use

import { CenterfyClient } from "@centerfy/sdk";

const centerfy = new CenterfyClient({ apiKey: process.env.CENTERFY_API_KEY! });

const page = await centerfy.contacts.list({ limit: 25 });
const contact = await centerfy.contacts.create({ name: "Jane Doe", email: "[email protected]" });
await centerfy.contacts.addTags(contact.contact.id, { tags: ["lead"] });

Resources are properties on the client named after the API sections (contacts, pipelines, agents, invoices, …). The full list of methods, with the endpoint each one calls, is on SDK methods.

Agency client

Agency endpoints use a separate class so a sub-account key can never call them by mistake:

import { CenterfyAgencyClient } from "@centerfy/sdk";

const agency = new CenterfyAgencyClient({ apiKey: process.env.CENTERFY_AGENCY_API_KEY! });
const subs = await agency.subAccounts.list({ limit: 50 });

It exposes subAccounts, subAccountUsers, subAccountApiKeys and wallet.

Options

Option	Default	Description
apiKey	required	Sent as x-api-key on every request.
baseUrl	https://api.centerfy.ai	Override the API origin.
timeoutMs	30000	Per-attempt timeout.
maxRetries	0	Automatic retries for 429 / 5xx and network failures; honors Retry-After.
defaultHeaders	{}	Extra headers on every request, e.g. X-Webhook-Source.
fetch	global fetch	Custom fetch implementation.

Every method also accepts a final options argument: { signal?, headers?, idempotencyKey? }. idempotencyKey is required by phoneProvisioning.purchase.

Errors

Failed calls throw a subclass of CenterfyError:

Class	Status
CenterfyAuthError	401
CenterfyForbiddenError	403
CenterfyNotFoundError	404
CenterfyValidationError	400 / 422
CenterfyRateLimitError	429 (retryAfterSeconds)
CenterfyServerError	5xx
CenterfyConnectionError	no response (network, timeout, abort)

import { CenterfyNotFoundError, CenterfyRateLimitError } from "@centerfy/sdk";

try {
  await centerfy.contacts.get(id);
} catch (err) {
  if (err instanceof CenterfyNotFoundError) return null;
  if (err instanceof CenterfyRateLimitError) await sleep(err.retryAfterSeconds * 1000);
  throw err;
}

All errors carry status, the parsed error body and the request ({ method, path }) that failed.

Binary and file endpoints

• voices.preview() resolves to an ArrayBuffer of MP3 bytes.
• knowledgeBases.addFile(kbId, blob, fileName) takes a Blob (for example new Blob([fs.readFileSync("faq.pdf")])).