NodeJS

The Gleap Admin SDK for Node.js lets your backend push authoritative customer data into Gleap: identify contacts, manage companies, manage CRM pipeline entries, track customer value (MRR) and send server-side events.

Installation

npm install gleap-admin --save

Usage

Import the GleapAdmin package.

import GleapAdmin from "gleap-admin";

Initialize the SDK

It is required to initialize the GleapAdmin SDK before sending events or other requests.

GleapAdmin.initialize(process.env.GLEAP_API_TOKEN);

Generate a server API key under Settings → Developer → API keys and pass it to GleapAdmin.initialize. Keep the key in an environment variable; it must never ship to client apps.

Identify a user

GleapAdmin.identify("user-id", {
  name: "John Doe",
  email: "[email protected]",
  value: 499, // MRR: monthly recurring revenue, major units
  phone: "+4395959595",
  customData: {
    plan: "Growth plan",
  },
  // Optional: associate the user with a company.
  company: {
    id: "acme-inc",
    name: "ACME inc.",
  },
});

The userId should match the userId you are using to identify your users. All key-value pairs in the user properties part are optional. Only company.id is required inside the optional company object; company.name never overwrites a name set via updateCompany.

Companies

Set authoritative company attributes (plan, value, SLA, address, custom data) from your backend. These are shown in the dashboard, used for company-level SLAs and revenue-based prioritization, and are never overwritten by data sent from your client apps.

// Create or update a company (companyId is your own immutable identifier).
const company = await GleapAdmin.updateCompany("acme-inc", {
  name: "ACME inc.",
  plan: "Growth plan",
  value: 4990, // MRR: monthly recurring revenue, major units
  sla: 3600, // Response-time SLA in seconds.
  domain: "acme.com",
  address: { line1: "1 Infinite Loop", city: "Cupertino", country: "US" },
  customData: { tier: "gold" },
});

// Read a company (returns null if it doesn't exist).
const existing = await GleapAdmin.getCompany("acme-inc");

// Delete a company (its contacts and conversations are kept).
const success = await GleapAdmin.deleteCompany("acme-inc");

Pipelines (CRM)

Manage CRM pipeline entries from your backend: put a company or contact on a pipeline, move it through stages, set field values, or remove it — for example to mirror your signup or billing lifecycle onto an onboarding pipeline.

Entries are addressed by your own identifiers: the companyId you pass to updateCompany for company pipelines, or the userId you pass to identify for contact pipelines. Pipeline, stage and field ids come from getPipelines:

// [{ id, name, recordType, stages: [{ id, name, color }], fields: [{ fieldId, label, type }] }]
const pipelines = await GleapAdmin.getPipelines();

// Add a company to a pipeline. stageId defaults to the first stage; values
// are keyed by fieldId. If the record is already on the pipeline, the
// existing entry is returned unchanged (adding is idempotent).
const entry = await GleapAdmin.addPipelineEntry("pipeline-id", {
  companyId: "acme-inc",
  stageId: "stage-id",
  values: { dealsize: 4990 },
});

// Create-or-update (like updateCompany): adds the record, or moves it and
// updates its values if it is already on the pipeline. Values are merged,
// and null clears a field.
await GleapAdmin.updatePipelineEntry("pipeline-id", {
  companyId: "acme-inc",
  stageId: "next-stage-id",
});

// Contact pipelines address entries by userId instead.
await GleapAdmin.addPipelineEntry("pipeline-id", { userId: "user-1234" });

// Read an entry (null if the record is not on the pipeline).
const existing = await GleapAdmin.getPipelineEntry("pipeline-id", {
  companyId: "acme-inc",
});

// Remove a record from a pipeline (the company/contact itself is kept).
const success = await GleapAdmin.removePipelineEntry("pipeline-id", {
  companyId: "acme-inc",
});

Adding a record and moving it to a new stage run the pipeline's automations, exactly like the same action in the dashboard. Unknown stage ids and unknown field keys are rejected with a 400 naming the valid ids.

Track MRR (customer value)

Gleap uses the value field as a customer's MRR: monthly recurring revenue, in your billing currency, in major units (for example 499 or 49.9, not cents). Kai Copilot weighs a company account with the maximum of the company value and its members' contact values, counted once per company — so for team accounts, setting the company value is enough.

Update it from your billing webhook so Gleap always mirrors your billing system:

// e.g. inside a Stripe customer.subscription.updated webhook handler
const mrr = computeMonthlyAmount(subscription); // yearly prices / 12, cents -> major units
await GleapAdmin.updateCompany(companyId, { value: mrr });
// On cancellation:
await GleapAdmin.updateCompany(companyId, { value: 0 });

Complete runnable Stripe and Paddle webhook examples ship with the SDK: github.com/GleapSDK/GleapAdmin-NodeJS/tree/main/examples.

identify and updateCompany send immediately — safe in short-lived webhook handlers. trackEvent is buffered (flushed every 2.5 seconds), so only use it from long-running processes.

Track an event

GleapAdmin.trackEvent("user-id", "event-name", {
  someEventData: "yeah!",
});

The userId should match the userId you are using to identify your users.

The event data (last param) is optional.

Rate limit

Please note that the identify and track APIs enforce a rate limit of 1500 requests / 60 seconds per API token. If you exceed the limit, requests are rejected with 429 Too Many Requests and the token is blocked for a short period before requests are accepted again.