API Reference

Every feature, one API call away

nodestash gives you a complete CRM backend as a REST API. Contacts, deals, pipelines, custom fields, search — all with consistent, predictable endpoints and real code examples.

Contacts & Companies

Full contact and company management with custom fields, tags, and relationship tracking.

Create, update, search, and delete contacts and companies. Link contacts to companies, add tags for segmentation, and store arbitrary data in custom fields. All records are workspace-scoped with full CRUD operations.

Contacts & Companies
// Create a contact
const response = await fetch('https://api.nodestash.io/v1/contacts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer nds_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    first_name: 'Jane',
    last_name: 'Smith',
    email: 'jane@example.com',
    company_id: 'co_7nR4kXqB2vM9wYpT5sG',
    tags: ['enterprise', 'decision-maker'],
    custom_fields: {
      lead_score: 85,
      source: 'website',
    },
  }),
})

// Response
{
  "data": {
    "id": "ct_9mK2pLxR4vN8wYqT3hJ",
    "type": "contact",
    "attributes": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "tags": ["enterprise", "decision-maker"]
    }
  }
}

Deals & Pipelines

Custom sales pipelines with stages. Track deal values, currencies, and expected close dates.

Create pipelines with custom stages (open, won, lost). Move deals through stages, track monetary values with currency support, and link deals to contacts and companies. Cursor-based pagination for large deal sets.

Deals & Pipelines
// Create a deal in a pipeline
const response = await fetch('https://api.nodestash.io/v1/deals', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer nds_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Enterprise License Q2',
    value: 48000.00,
    currency: 'EUR',
    pipeline_id: 'pp_3kM8nLxR2vP5wYqT7sH',
    stage_id: 'ps_6jN9mKwQ4vR7xZpS2tG',
    contact_id: 'ct_9mK2pLxR4vN8wYqT3hJ',
    expected_close_date: '2025-06-30',
  }),
})

Activities & Timeline

Log every interaction. Calls, emails, meetings, notes — all linked to contacts, companies, and deals.

Track all customer interactions in a unified timeline. Support for built-in types (note, task, email, call, meeting) and custom types. Mark activities as done, set due dates, and filter by type or entity.

Activities & Timeline
// Log an activity
const response = await fetch('https://api.nodestash.io/v1/activities', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer nds_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'meeting',
    subject: 'Product Demo - Q2 Review',
    body: 'Discussed roadmap and pricing.',
    contact_id: 'ct_9mK2pLxR4vN8wYqT3hJ',
    deal_id: 'dl_5hK7mNxQ3vR8wYpT4sG',
    is_done: true,
  }),
})

Custom Fields

Define fields of any type and query them like first-class citizens. Not an afterthought.

Define custom field definitions with types (text, number, boolean, date, select, multi_select, url, email, phone). Set required flags and options for select fields. Values are stored separately and queryable per entity.

Custom Fields
// Define a custom field
await fetch('https://api.nodestash.io/v1/custom-fields', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer nds_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entity_type: 'contact',
    name: 'Lead Score',
    slug: 'lead_score',
    field_type: 'number',
    is_required: false,
  }),
})

// Set value on a contact
await fetch('https://api.nodestash.io/v1/contacts/ct_.../custom-fields', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer nds_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    lead_score: 92,
  }),
})

Webhooks & Events

Real-time event notifications with automatic retries and cryptographic signatures.

Every state change fires a webhook to your configured endpoint. Events include contact.created, deal.stage_changed, field.updated, and more. Payloads include the full resource data and metadata for reliable processing.

Webhooks & Events
// Webhook payload delivered to your endpoint
{
  "event": "contact.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "id": "ct_9mK2pLxR4vN8wYqT3hJ",
    "type": "contact",
    "attributes": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  },
  "metadata": {
    "workspace_id": "ws_2kN8mLxR4vP5wYqT",
    "triggered_by": "api"
  }
}

Full-text Search

Meilisearch-powered instant search with typo tolerance and filtering.

Search across contacts, companies, deals, and activities with a single query parameter. Results are ranked by relevance with typo tolerance. Combine search with tag filters, date ranges, and custom field queries.

Full-text Search
// Full-text search across contacts
const response = await fetch(
  'https://api.nodestash.io/v1/contacts?search=jane&tags=enterprise',
  {
    headers: {
      'Authorization': 'Bearer nds_live_...',
    },
  },
)

// Response with pagination
{
  "data": [...],
  "meta": {
    "pagination": {
      "next_cursor": "eyJpZCI6ImN0XzltSz...",
      "has_more": true
    }
  }
}

Platform Features

Infrastructure you can rely on. Built for production from day one.

OpenAPI 3.1 Spec

Full OpenAPI 3.1 specification with schemas and examples. Auto-generate clients in any language — TypeScript, Python, Go, Ruby, Java.

API Key & OAuth2

Two auth methods: API keys for server-to-server, OAuth2 for third-party integrations. Scope-based permissions on every request.

Transparent Rate Limits

Clear rate limit headers on every response. Daily limits and per-second burst limits. No surprises — plan your integration with confidence.

Multi-Tenant by Design

Every query is workspace-scoped. Data isolation is built into the schema, not bolted on. Safe for multi-tenant SaaS applications.

TypeScript SDK

Official TypeScript SDK with full type safety, autocompletion, and custom error types. npm install @nodestash/sdk and go.

OAuth2 Authorization

Full OAuth2 flow with authorization codes, PKCE, token refresh, and revocation. Build integrations that your customers can authorize.

nodestash vs Traditional CRMs

How a headless CRM API compares to traditional CRM platforms.

FeaturenodestashTraditional CRMs
API-first designCore productAfterthought
OpenAPI 3.1 SpecFull specPartial or none
Custom fields via APIFirst-classLimited
Real-time webhooksAll eventsSelect events
Cursor-based paginationAll endpointsInconsistent
Rate limit headersEvery responseSometimes
Per-seat pricingNo — usage-basedYes — per user
Self-hostableDockerUsually no
UI vendor lock-inNone — your UIHigh

Ready to build your CRM?

Get started with nodestash in minutes. No credit card required.

Get Your API KeyRead the Docs