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.

Limits are per workspace, counted in one-minute windows. Each resource has its own bucket.

• Every resource: 100 requests per minute. Batch ingest and Inbound form submissions spend the contacts bucket.
• Contacts: also 10,000 requests per day, Inbound form submissions included.
• Activities: also 50,000 requests per day.
• A batch call counts once toward the daily cap, however many contacts it carries.

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.
• X-DailyLimit-RemainingRequests left today. Contacts and activities only.
• X-DailyLimit-ResetWhen the day resets, in Unix seconds. Contacts and activities only.
• Retry-AfterOn a 429, the wait in seconds.

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.

Behaviour that does not match what the rest of this page would lead you to expect. Listed here because finding it at runtime is worse.

• Two requests with the same X-Idempotency-Key sent at the same moment can both write.
• The activity_id in a contact ingest response cannot be fetched through the Activities endpoints.
• An ingested activity keeps its type only in the ingest log. On the timeline its type is note.
• Requests turned away by the per-minute limit still count toward the daily cap.
• Inbound form submissions keep X-Idempotency-Key in the contacts space. A key already used on POST /v1-public-contacts replays that answer. Send external_id instead, which is kept per form.