Apideck TypeScript SDK Skill

Overview

The Apideck Unified API provides a single integration layer to connect with 200+ third-party services across accounting, CRM, HRIS, file storage, ATS, e-commerce, and more. The official TypeScript SDK (

@apideck/unify

Key capabilities:

• Accounting - Invoices, bills, payments, ledger accounts, journal entries, tax rates, balance sheets, P&L
• CRM - Contacts, companies, leads, opportunities, activities, pipelines, notes
• HRIS - Employees, departments, payrolls, time-off requests, schedules
• File Storage - Files, folders, drives, shared links, upload sessions
• ATS - Jobs, applicants, applications
• Vault - Connection management, OAuth flows, custom field mapping
• Vault JS - Embeddable modal UI for users to authorize connectors and manage settings
• Webhook - Event subscriptions and real-time notifications

Installation

npm add @apideck/unify

Requires Node.js 18+. The SDK is fully typed with TypeScript definitions.

IMPORTANT RULES

• ALWAYS use the

  @apideck/unify

  SDK. DO NOT make raw

  fetch

  /

  axios

  calls to the Apideck API.
• ALWAYS pass

  apiKey

  ,

  appId

  , and

  consumerId

  when initializing the client. These are required for all API calls.
• ALWAYS set the

  APIDECK_API_KEY

  environment variable rather than hardcoding API keys.
• USE

  serviceId

  to specify which downstream connector to use (e.g.,

  "salesforce"

  ,

  "quickbooks"

  ,

  "xero"

  ). If a consumer has multiple connections for an API,

  serviceId

  is required.
• USE cursor-based pagination with

  for await...of

  for iterating large result sets. DO NOT implement manual pagination.
• USE the

  filter

  parameter to narrow results server-side. DO NOT fetch all records and filter client-side.
• USE the

  fields

  parameter to request only the columns you need. This reduces response size and improves performance.
• ALWAYS handle errors with try/catch. The SDK throws typed errors for different HTTP status codes.
• DO NOT store Apideck API keys, App IDs, or Consumer IDs in source code. Use environment variables or a secrets manager.

Quick Start

import { Apideck } from "@apideck/unify";

const apideck = new Apideck({
  apiKey: process.env["APIDECK_API_KEY"] ?? "",
  appId: "your-app-id",
  consumerId: "your-consumer-id",
});

// List CRM contacts
const { data } = await apideck.crm.contacts.list({
  limit: 20,
  filter: { email: "john@example.com" },
});

for (const contact of data) {
  console.log(contact.name, contact.emails);
}

SDK Patterns

Client Setup

import { Apideck } from "@apideck/unify";

const apideck = new Apideck({
  apiKey: process.env["APIDECK_API_KEY"] ?? "",
  appId: "your-app-id",
  consumerId: "your-consumer-id",
});

The

consumerId

CRUD Operations

All resources follow the same pattern:

apideck.{api}.{resource}.{operation}()

// LIST - retrieve multiple records
const { data } = await apideck.crm.contacts.list({
  serviceId: "salesforce",
  limit: 20,
  filter: { email: "john@example.com" },
  sort: { by: "updated_at", direction: "desc" },
  fields: "id,name,email,phone_numbers",
});

// CREATE - create a new record
const { data: created } = await apideck.crm.contacts.create({
  serviceId: "salesforce",
  contact: {
    first_name: "John",
    last_name: "Doe",
    emails: [{ email: "john@example.com", type: "primary" }],
    phone_numbers: [{ number: "+1234567890", type: "mobile" }],
  },
});
console.log(created.id); // "contact_abc123"

// GET - retrieve a single record
const { data: contact } = await apideck.crm.contacts.get({
  id: "contact_abc123",
  serviceId: "salesforce",
});

// UPDATE - modify an existing record
const { data: updated } = await apideck.crm.contacts.update({
  id: "contact_abc123",
  serviceId: "salesforce",
  contact: { first_name: "Jane" },
});

// DELETE - remove a record
await apideck.crm.contacts.delete({
  id: "contact_abc123",
  serviceId: "salesforce",
});

Pagination

Use async iteration to automatically handle cursor-based pagination:

const result = await apideck.accounting.invoices.list({
  serviceId: "quickbooks",
  limit: 50,
});

// Automatically fetches next pages
for await (const page of result) {
  for (const invoice of page.data) {
    console.log(invoice.number, invoice.total);
  }
}

Or handle pagination manually:

let cursor: string | undefined;
do {
  const { data, meta } = await apideck.accounting.invoices.list({
    serviceId: "quickbooks",
    limit: 50,
    cursor,
  });
  for (const invoice of data) {
    console.log(invoice.number);
  }
  cursor = meta?.cursors?.next ?? undefined;
} while (cursor);

Error Handling

import { Apideck } from "@apideck/unify";
import * as errors from "@apideck/unify/models/errors";

try {
  const { data } = await apideck.crm.contacts.get({ id: "invalid" });
} catch (e) {
  if (e instanceof errors.BadRequestResponse) {
    console.error("Bad request:", e.message);
  } else if (e instanceof errors.UnauthorizedResponse) {
    console.error("Invalid API key or missing credentials");
  } else if (e instanceof errors.NotFoundResponse) {
    console.error("Record not found");
  } else if (e instanceof errors.PaymentRequiredResponse) {
    console.error("API limit reached or payment required");
  } else if (e instanceof errors.UnprocessableResponse) {
    console.error("Validation error:", e.message);
  } else {
    throw e;
  }
}

Common Parameters

Most list endpoints accept these parameters:

serviceId

string

"quickbooks"

"salesforce"

limit

number

cursor

string

filter

object

sort

object

{ by: string, direction: "asc" | "desc" }

fields

string

passThrough

object

Pass-Through Parameters

When the unified model doesn't cover a connector-specific field, use

passThrough

const { data } = await apideck.accounting.invoices.list({
  serviceId: "quickbooks",
  passThrough: {
    search: "overdue",
  },
});

For creating/updating, use

pass_through

const { data } = await apideck.crm.contacts.create({
  serviceId: "salesforce",
  contact: {
    first_name: "John",
    last_name: "Doe",
    pass_through: [
      {
        service_id: "salesforce",
        operation_id: "contactsAdd",
        extend_object: { custom_sf_field__c: "value" },
      },
    ],
  },
});

API Namespaces

The SDK organizes APIs by namespace. See the reference files for detailed endpoints:

apideck.accounting.*

apideck.crm.*

apideck.hris.*

apideck.fileStorage.*

apideck.ats.*

apideck.vault.*

apideck.webhook.*

Vault JS (Embeddable UI)

Use

@apideck/vault-js

// 1. Server-side: create a session
const { data } = await apideck.vault.sessions.create({
  session: {
    consumer_metadata: { account_name: "Acme Corp", user_name: "John Doe", email: "john@acme.com" },
    redirect_uri: "https://myapp.com/integrations",
    settings: { unified_apis: ["accounting", "crm"] },
    theme: { vault_name: "My App", primary_color: "#4F46E5" },
  },
});

// 2. Client-side: open the modal
import { ApideckVault } from "@apideck/vault-js";

ApideckVault.open({
  token: sessionToken,
  onConnectionChange: (connection) => console.log("Changed:", connection),
  onClose: () => console.log("Closed"),
});

See references/vault-js.md for full configuration options, theming, React integration, and event callbacks.