Lumenbase API Reference

The Lumenbase API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You use API keys from your workspace to authenticate requests. Create and manage keys in Settings → Company Settings → Integrations → API. The API key determines which workspace the request applies to.

Full CRUD is available for Contacts, Companies, Deals, Tasks, Invoices, and Activities.

Base URL & authentication

https://api.lumenbase.io

All requests require:

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

Optional: X-Idempotency-Key to prevent duplicate processing on retries; X-Request-Id for tracing.

Response envelope: Success responses return { success: true, data: { ... }, meta: { request_id, api_version, timestamp } }. Errors return { success: false, error: { code, message, details? }, meta: { ... } }.

Setup

Go to Settings → Company Settings → Integrations → API. Click "Create API Key" and select the scopes you need.
Copy the key immediately: it won't be shown again.
Optionally create a Connector to map incoming fields to CRM fields and set matching rules (for ingest endpoints).

API key scopes

Each API key has one or more scopes that control what it can access. Assign only the scopes you need.

Field	Type	Description
contacts:read	scope	Read and list contacts
contacts:write	scope	Create, update, and delete contacts
companies:read	scope	Read and list companies
companies:write	scope	Create, update, and delete companies
deals:read	scope	Read and list deals
deals:write	scope	Create, update, and delete deals
tasks:read	scope	Read and list tasks
tasks:write	scope	Create, update, and delete tasks
invoices:read	scope	Read and list invoices
invoices:write	scope	Create, update, and delete invoices
activities:read	scope	Read and list activities
activities:write	scope	Create and delete activities
read	scope	Read access to all entity types
admin	scope	Full access to all endpoints

Legacy scopes contact_ingest and activity_ingest still work and map to the corresponding read+write scopes.

Pagination

All list endpoints support pagination via query parameters:

Field	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Items per page, max 100 (default: 25)
sort_by	string	Field to sort by (varies per entity)
sort_order	string	"asc" or "desc" (default: "desc")
search	string	Free-text search across key fields

Paginated response shape:

{
  "success": true,
  "data": {
    "items": [ ... ],
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total": 142,
      "total_pages": 6
    }
  },
  "meta": { "request_id": "...", "api_version": "1", "timestamp": "..." }
}

POST: Create / Ingest Contact

Create or update contacts from forms, landing pages, or third-party systems. Matches by email; optionally creates or links companies.

POSThttps://api.lumenbase.io/functions/v1/v1-public-contacts

Scope:

contacts:write

contact_ingest

Request body:

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1-555-123-4567",
  "title": "Product Manager",
  "company_name": "Acme Inc",
  "company_domain": "acme.com",
  "source": "website_form",
  "signal_strength": 75,
  "message": "Interested in your enterprise plan"
}

Field	Type	Description
first_name	string	Contact first name
last_name	string	Contact last name
email	string	Email (used for matching)
phone	string	Phone number
title	string	Job title
company_name	string	Company name (creates if new)
company_domain	string	Company domain for matching
source	string	Lead source
signal_strength	number	Intent signal 0–100
message	string	Notes

201 when new contact created; 200 when existing contact updated.

POST: Batch Ingest Contacts

Ingest up to 100 contacts in one request. Same field schema as Contact Ingest.

POSThttps://api.lumenbase.io/functions/v1/v1-public-contacts-batch

Scope:

contacts:write

{
  "contacts": [
    { "email": "a@example.com", "first_name": "Alice" },
    { "email": "b@example.com", "first_name": "Bob" }
  ],
  "options": { "stop_on_error": false }
}

201 all succeed; 207 mixed; 400 all fail. Max 100 contacts, 500 KB payload.

GET: Retrieve / List Contacts

GEThttps://api.lumenbase.io/functions/v1/v1-public-contacts-crud?id={uuid}

Retrieve a single contact by ID.

GEThttps://api.lumenbase.io/functions/v1/v1-public-contacts-crud?page=1&per_page=25

List contacts with pagination.

Scope:

contacts:read

Filters:

Field	Type	Description
email	string	Filter by exact email
company_id	uuid	Filter by company
status	string	Filter by status
search	string	Search first_name, last_name, email

Sort by: created_at, updated_at, first_name, last_name, email

PATCH: Update Contact

PATCHhttps://api.lumenbase.io/functions/v1/v1-public-contacts-crud?id={uuid}

Scope:

contacts:write

{
  "title": "Senior Product Manager",
  "phone": "+1-555-999-0000"
}

Updatable fields: first_name, last_name, email, phone, title, company_id, source, status.

DELETE: Delete Contact

DELETEhttps://api.lumenbase.io/functions/v1/v1-public-contacts-crud?id={uuid}

Scope:

contacts:write

{ "success": true, "data": { "deleted": true, "id": "uuid" } }

POST: Create Company

POSThttps://api.lumenbase.io/functions/v1/v1-public-companies

Scope:

companies:write

Upserts by domain if provided. Creates new if no match.

{
  "name": "Acme Inc",
  "domain": "acme.com",
  "industry": "Technology",
  "size": "51-200",
  "website": "https://acme.com",
  "city": "San Francisco",
  "country": "US"
}

Field	Type	Description
name	string	Company name
domain	string	Company domain (used for matching)
industry	string	Industry
size	string	Company size range
website	string	Website URL
phone	string	Phone number
city	string	City
state	string	State/region
country	string	Country code
status	string	Status

GET: Retrieve / List Companies

GEThttps://api.lumenbase.io/functions/v1/v1-public-companies?id={uuid}

GEThttps://api.lumenbase.io/functions/v1/v1-public-companies?page=1&per_page=25

Scope:

companies:read

Filters:

Field	Type	Description
domain	string	Filter by exact domain
industry	string	Filter by industry
search	string	Search name, domain

Sort by: created_at, updated_at, name, domain

PATCH: Update Company

PATCHhttps://api.lumenbase.io/functions/v1/v1-public-companies?id={uuid}

Scope:

companies:write

{ "industry": "SaaS", "size": "201-500" }

DELETE: Delete Company

DELETEhttps://api.lumenbase.io/functions/v1/v1-public-companies?id={uuid}

Scope:

companies:write

POST: Create Deal

POSThttps://api.lumenbase.io/functions/v1/v1-public-deals

Scope:

deals:write

{
  "title": "Enterprise License: Acme",
  "value": 50000,
  "currency": "USD",
  "stage": "Proposal",
  "expected_close_date": "2026-04-15",
  "company_id": "uuid",
  "contact_id": "uuid"
}

Field	Type	Description
title	string (required)	Deal title
value	number	Deal value
currency	string	Currency code (default: USD)
stage	string	Pipeline stage
status	string	Deal status
probability	number	Win probability 0–100
expected_close_date	date	Expected close date
company_id	uuid	Linked company
contact_id	uuid	Linked contact
pipeline_id	uuid	Pipeline ID
assigned_to	uuid	Assigned user ID

GET: Retrieve / List Deals

GEThttps://api.lumenbase.io/functions/v1/v1-public-deals?id={uuid}

GEThttps://api.lumenbase.io/functions/v1/v1-public-deals?page=1&per_page=25

Scope:

deals:read

Filters:

Field	Type	Description
stage	string	Filter by stage
status	string	Filter by status
company_id	uuid	Filter by company
pipeline_id	uuid	Filter by pipeline
search	string	Search title

Sort by: created_at, updated_at, title, value, expected_close_date

PATCH: Update Deal

PATCHhttps://api.lumenbase.io/functions/v1/v1-public-deals?id={uuid}

Scope:

deals:write

{ "stage": "Negotiation", "probability": 80 }

DELETE: Delete Deal

DELETEhttps://api.lumenbase.io/functions/v1/v1-public-deals?id={uuid}

Scope:

deals:write

POST: Create Task

POSThttps://api.lumenbase.io/functions/v1/v1-public-tasks

Scope:

tasks:write

{
  "title": "Follow up with Acme",
  "description": "Send proposal by Friday",
  "priority": "high",
  "due_date": "2026-03-01",
  "assigned_to": "uuid",
  "contact_id": "uuid",
  "deal_id": "uuid"
}

Field	Type	Description
title	string (required)	Task title
description	string	Task description
status	string	Task status
priority	string	Priority: low, medium, high, urgent
due_date	date	Due date
assigned_to	uuid	Assigned user ID
contact_id	uuid	Linked contact
company_id	uuid	Linked company
deal_id	uuid	Linked deal

GET: Retrieve / List Tasks

GEThttps://api.lumenbase.io/functions/v1/v1-public-tasks?id={uuid}

GEThttps://api.lumenbase.io/functions/v1/v1-public-tasks?page=1&per_page=25

Scope:

tasks:read

Filters:

Field	Type	Description
status	string	Filter by status
priority	string	Filter by priority
assigned_to	uuid	Filter by assignee
contact_id	uuid	Filter by contact
company_id	uuid	Filter by company
deal_id	uuid	Filter by deal
search	string	Search title

Sort by: created_at, updated_at, title, due_date, priority

PATCH: Update Task

PATCHhttps://api.lumenbase.io/functions/v1/v1-public-tasks?id={uuid}

Scope:

tasks:write

{ "status": "completed", "description": "Proposal sent" }

DELETE: Delete Task

DELETEhttps://api.lumenbase.io/functions/v1/v1-public-tasks?id={uuid}

Scope:

tasks:write

POST: Create Invoice

POSThttps://api.lumenbase.io/functions/v1/v1-public-invoices

Scope:

invoices:write

{
  "invoice_number": "INV-2026-001",
  "status": "draft",
  "issue_date": "2026-02-19",
  "due_date": "2026-03-19",
  "subtotal": 5000,
  "tax_amount": 500,
  "total": 5500,
  "currency": "USD",
  "company_id": "uuid",
  "contact_id": "uuid",
  "notes": "Net 30"
}

Field	Type	Description
invoice_number	string	Invoice number
status	string	draft, sent, paid, overdue, cancelled
issue_date	date	Issue date
due_date	date	Due date
subtotal	number	Subtotal amount
tax_amount	number	Tax amount
total	number	Total amount
currency	string	Currency code
company_id	uuid	Linked company
contact_id	uuid	Linked contact
deal_id	uuid	Linked deal
notes	string	Notes
line_items	json	Line items array

GET: Retrieve / List Invoices

GEThttps://api.lumenbase.io/functions/v1/v1-public-invoices?id={uuid}

GEThttps://api.lumenbase.io/functions/v1/v1-public-invoices?page=1&per_page=25

Scope:

invoices:read

Filters:

Field	Type	Description
status	string	Filter by status
company_id	uuid	Filter by company
contact_id	uuid	Filter by contact
search	string	Search invoice_number

Sort by: created_at, updated_at, invoice_number, due_date, total, issue_date

PATCH: Update Invoice

PATCHhttps://api.lumenbase.io/functions/v1/v1-public-invoices?id={uuid}

Scope:

invoices:write

{ "status": "sent", "due_date": "2026-04-01" }

DELETE: Delete Invoice

DELETEhttps://api.lumenbase.io/functions/v1/v1-public-invoices?id={uuid}

Scope:

invoices:write

POST: Create / Ingest Activity

POSThttps://api.lumenbase.io/functions/v1/v1-public-activities

Scope:

activities:write

activity_ingest

Record activities from Jira, support tools, webhooks, or any external source. Links to contacts/companies by email or domain.

{
  "type": "jira_issue_created",
  "entity_email": "john.doe@example.com",
  "entity_domain": "acme.com",
  "title": "PROJ-123: New Feature Request",
  "description": "Customer requested dashboard export",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": { "issue_key": "PROJ-123", "priority": "high" }
}

Activity types:

jira_issue

support_ticket

form_submission

webhook

external_activity

Entity linking:

entity_email → Contact by email
entity_domain → Company by domain
entity_id → Deal by ID

GET: Retrieve / List Activities

GEThttps://api.lumenbase.io/functions/v1/v1-public-activities-crud?id={uuid}

GEThttps://api.lumenbase.io/functions/v1/v1-public-activities-crud?page=1&per_page=25

Scope:

activities:read

Filters:

Field	Type	Description
type	string	Filter by activity type
contact_id	uuid	Filter by contact
company_id	uuid	Filter by company
deal_id	uuid	Filter by deal
search	string	Search title

Sort by: created_at, type, title

DELETE: Delete Activity

DELETEhttps://api.lumenbase.io/functions/v1/v1-public-activities-crud?id={uuid}

Scope:

activities:write

Field mapping (Connectors)

Connectors map incoming JSON fields to CRM fields. Use dot notation for nested JSON, e.g. user.profile.email → Email. Connectors apply to the ingest endpoints (Contact Ingest, Activity Ingest).

Matching rules

Contact: email (recommended), phone, or ID. Company: domain (recommended), name, or ID. Deal: ID or title. If no match and required data is provided, a new record is created.

Error handling

Field	Type	Description
401	UNAUTHORIZED	Invalid or missing API key; use Bearer <key>
403	FORBIDDEN	API key lacks required scope
400	VALIDATION_ERROR	Invalid request payload or missing required fields
404	NOT_FOUND	Resource not found
405	METHOD_NOT_ALLOWED	HTTP method not supported for this endpoint
413	PAYLOAD_TOO_LARGE	Request body exceeds max size (50 KB single, 500 KB batch)
429	RATE_LIMIT_EXCEEDED	Too many requests; check X-RateLimit-* and Retry-After
500	INTERNAL_ERROR	Server error

Error response body:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable message",
    "details": { }
  },
  "meta": { "request_id": "...", "api_version": "1", "timestamp": "..." }
}

Best practices

Use separate connectors per source to track origin and customize mapping.
Include email for contact matching (most reliable).
Send X-Idempotency-Key on retries to avoid duplicates.
Rate limit: 100 requests/minute per workspace; daily caps 10K contacts and 50K activities. Check X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After on 429.
Use granular scopes (e.g. contacts:read) instead of admin for least-privilege access.
For bulk operations, use the batch endpoint to reduce API calls.

Not a developer?

Use Zapier to connect Lumenbase to 6,000+ apps, or browse the Knowledge Base.

Need an API key? Sign in and go to Settings → Integrations → API.

Every serious CRM was built decades ago and never fully rebuilt.

Lumenbase API Reference

Base URL & authentication

Setup

API key scopes

POST: Create / Ingest Contact

POST: Batch Ingest Contacts

GET: Retrieve / List Contacts

PATCH: Update Contact

DELETE: Delete Contact

POST: Create Company

GET: Retrieve / List Companies

PATCH: Update Company

DELETE: Delete Company

POST: Create Deal

GET: Retrieve / List Deals

PATCH: Update Deal

DELETE: Delete Deal

POST: Create Task

GET: Retrieve / List Tasks

PATCH: Update Task

DELETE: Delete Task

POST: Create Invoice

GET: Retrieve / List Invoices

PATCH: Update Invoice

DELETE: Delete Invoice

POST: Create / Ingest Activity

GET: Retrieve / List Activities

DELETE: Delete Activity

Field mapping (Connectors)

Matching rules

Error handling

Best practices

Not a developer?

Cookie preferences