Lumenbase API Reference

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

1. Go to Settings → Company Settings → Integrations → API. Click "Create API Key" and select the scopes you need.
2. Copy the key immediately: it won't be shown again.
3. 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.

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:

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.

Scope:

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"
}

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.

Scope:

{
  "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

Retrieve a single contact by ID.

List contacts with pagination.

Scope:

Filters:

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

PATCH: Update Contact

Scope:

{
  "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

Scope:

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

POST: Create Company

Scope:

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"
}

GET: Retrieve / List Companies

Scope:

Filters:

Sort by: created_at, updated_at, name, domain

PATCH: Update Company

Scope:

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

DELETE: Delete Company

Scope:

POST: Create Deal

Scope:

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

GET: Retrieve / List Deals

Scope:

Filters:

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

PATCH: Update Deal

Scope:

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

DELETE: Delete Deal

Scope:

POST: Create Task

Scope:

{
  "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"
}

GET: Retrieve / List Tasks

Scope:

Filters:

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

PATCH: Update Task

Scope:

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

DELETE: Delete Task

Scope:

POST: Create Invoice

Scope:

{
  "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"
}

GET: Retrieve / List Invoices

Scope:

Filters:

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

PATCH: Update Invoice

Scope:

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

DELETE: Delete Invoice

Scope:

POST: Create / Ingest Activity

Scope:

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:

Entity linking:

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

GET: Retrieve / List Activities

Scope:

Filters:

Sort by: created_at, type, title

DELETE: Delete Activity

Scope:

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

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.