Lumenbase API Reference

1. Step 1

   Create a key

   Grant only the scopes the integration uses. The key is shown once.

   SettingsCompany SettingsAPI
3. Step 2

   Send a request

   Put the key in the Authorization header of every call.

   Bearer lmb_…
5. Step 3

   Read the envelope

   Check success, read data, and log meta.request_id for support.

   meta.request_id

https://api.lumenbase.io/functions/v1

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

Optional headers

• X-Idempotency-Key Makes a retried ingest safe. See Idempotency.
• X-Request-Id Your own trace id, echoed back in meta.request_id.

Every response

{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "req_...",
    "api_version": "1",
    "timestamp": "..."
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "...",
    "details": { "field": "..." }
  },
  "meta": { ... }
}

Every request carries a workspace API key as a Bearer token. There is no other accepted form.

Authorization: Bearer lmb_0f2a...

• A key is lmb_ followed by 64 hexadecimal characters.
• Keys are stored hashed. We cannot show one again, so save it when you create it.
• Revoking takes effect on the next request. Create the replacement first so rotation has no gap.
• A key belongs to one workspace. It can only read records in that workspace, and only link to them.
• Records a key creates are credited to the person who created the key, or to a workspace admin once they have left.

Each key carries one or more scopes. Grant only what the integration uses.

contact_ingest and activity_ingest are older names that still work. Each grants read and write on contacts or activities.

Every list endpoint takes these query parameters.

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

Branch on error.code, not on the message. Messages are written for people and can change; codes are part of the contract.

Three ceilings apply, and each one means something different. All are per workspace, and a refused request spends nothing.

• Every resource: 100 requests per minute. Batch ingest spends the contacts bucket. Inbound form submissions have their own bucket with the same limits.
• Contacts: also 10,000 records per day. This counts records written, so a batch of 100 spends 100 and a read spends nothing.
• Activities: also 50,000 records per day, counted the same way.
• Batch: no separate daily number. A batch spends one contact record per contact it carries.
• Every workspace: 2,000,000 requests per calendar month across the API and inbound capture. This is the fair-use ceiling, far above what an integration needs. Website tracking has its own limits and does not spend it.

Successful responses carry

• X-RateLimit-LimitRequests allowed per minute in this bucket.
• X-RateLimit-RemainingRequests left in this minute.
• X-RateLimit-ResetWhen the minute resets, in Unix seconds. Always the minute, whichever ceiling refused the last request.
• X-DailyLimit-RemainingRecords left today. Contacts, activities and inbound form submissions.
• X-DailyLimit-ResetWhen the day resets, in Unix seconds. Contacts, activities and inbound form submissions.
• X-MonthlyLimit-LimitRequests allowed this calendar month.
• X-MonthlyLimit-RemainingRequests left this calendar month.
• X-MonthlyLimit-ResetWhen the month resets, in Unix seconds.
• Retry-AfterOn a 429, the wait in seconds for the ceiling that refused it.

Send X-Idempotency-Key so a retry after a timeout cannot create a duplicate. Replaying the same key inside 24 hours returns the original result instead of writing again.

X-Idempotency-Key: 7d3f9c1e-2b84-4a17-9f0d-6c5e8a2b1d34

Use 8 to 128 characters, unique per operation. A UUID works. A key outside that length is ignored, not rejected.

Keys are per workspace and resource and last 24 hours. A replay answers 200 with the first response. Idempotency-Key works as an alias.

• Contacts match by email, then phone.
• Companies match by domain (taken from a work email when none is sent), then website, then name.
• An activity without a deal_id joins its company's most recent open deal.
• A connector maps your own field names onto these fields for the ingest endpoints. Nested JSON uses dot notation, for example user.profile.email.

The version is in the path and echoed in every response as meta.api_version and the X-API-Version header.

New fields can appear in a response at any time and are not treated as a breaking change. Parse defensively and ignore fields you do not recognise, rather than validating against an exact shape.

A breaking change means a new path prefix. The existing one keeps working through the deprecation process below.

The application version shown elsewhere in the product is a release date, not an API version. The two move independently.

When an endpoint is retiring, it says so in its own responses before it stops working.

A retiring endpoint returns

• Deprecationtrue
• Sunsetthe date it stops answering, as an HTTP date.
• Linkthe replacement, with rel pointing at the successor version.

The sunset date is at least six months after the deprecation is announced. After it passes the endpoint returns 410 Gone, naming its successor.

Currently deprecated

• POST /public-contactsPOST /v1-public-contactsSunset 26 November 2026
• POST /public-activitiesPOST /v1-public-activitiesSunset 31 March 2027

Log these headers. They are the earliest warning you will get, and they arrive on responses that are otherwise succeeding.

The full contract is published as an OpenAPI 3.1 document. Import it into Postman or Insomnia, generate a client, or diff it between releases to see exactly what changed.

https://lumenbase.io/api/openapi.json

curl -s https://lumenbase.io/api/openapi.json -o lumenbase-openapi.json

1. 1Give each integration its own key, so you can revoke one without breaking the rest.
2. 2Send an email with every contact. It is the most reliable match.
3. 3Send X-Idempotency-Key when retrying an ingest.
4. 4Load contacts in bulk through the batch endpoint.
5. 5Send website forms to POST /v1-public-inbound-submissions with a key that holds only inbound:submit. A leaked key can then send submissions and nothing else.
6. 6Watch X-RateLimit-Remaining, and on a 429 wait for Retry-After.
7. 7Log meta.request_id from every response. Support finds your request by it.