Skip to content
Baselumen is in private alphaSee the CRM

Build for Baselumen.
An app every agency can install.

Agencies build apps for the CRM they work in: a reminder that nudges unsigned proposals, a report for a client, a link to the tool their team already uses. Build it in Baselumen, submit it for review, and every workspace can install it.

How it works. Build, review, install.

  1. Build it

    In Baselumen, Integrations › Build an app. Name it, say what it does, choose the permissions it needs and the page it draws, and list its redirect addresses. You get a client id and a secret, shown once.

  2. Submit a version

    Each version is reviewed by Stacklumen before any other workspace can install it. A new version that asks for more is reviewed again, and workspaces that installed it are asked to allow the new permissions.

  3. Install it

    Your own workspace installs it first. A public app is then listed at baselumen.com/integrations, with a page that says what it does, what it can see and who made it.

  4. Hear what happens

    Install, uninstall and permission changes reach your app signed, and so do the deal, proposal and room events your app subscribes to, for each workspace whose permissions cover them.

Permissions. Ask for what the app needs.

The person installing your app sees each one before they allow it. Deploys, domains and account changes are never offered to an app.

components:read
Read your components. The component library and the custom components this workspace saved.
components:write
Change your components. Create, edit and fork custom components. Shown with weight on the consent screen.
clients:read
Read your clients. The companies this workspace works for: names, details and contacts. Shown with weight on the consent screen.
crm:read
Read your CRM. Deals, people and companies, with their notes and activity. Shown with weight on the consent screen. Workspaces on Baselumen Business and Enterprise.
crm:write
Add notes and activity to your CRM. Add notes and log calls, emails and meetings on deals, people and companies. Nothing is changed or deleted. Shown with weight on the consent screen. Workspaces on Baselumen Business and Enterprise.
deals:read
Read your deals. Each deal’s name, stage, value, owner and dates. Not people or notes. Workspaces on Baselumen Business and Enterprise.
rooms:read
Read your share rooms. Rooms and links, their deal, and who opened them and when. Never the files’ contents. Workspaces on Baselumen Business and Enterprise.
library:read
List your Library. Each file’s name, kind, tags, folder and version. Never the files themselves, and never a folder only some members can open. Workspaces on Baselumen Business and Enterprise.

Events. What happens in a workspace.

Your app hears its own lifecycle. Choose the events below on your app’s Build page and each workspace sends the ones its permissions cover to your webhook, signed with your client secret and retried if your endpoint is down.

app.installed
Sent to your app when it happens to an install of it.
app.uninstalled
Sent to your app when it happens to an install of it.
app.scopes_updated
Sent to your app when it happens to an install of it.
app.suspended
Sent to your app when it happens to an install of it.
app.reinstated
Sent to your app when it happens to an install of it.
deal.created
A deal was added to the CRM pipeline. Needs crm:read or deals:read.
deal.stage_changed
A deal moved to another stage. Needs crm:read or deals:read.
deal.won
A deal was won. Needs crm:read or deals:read.
deal.lost
A deal was lost. Needs crm:read or deals:read.
proposal.viewed
A proposal was opened by the client for the first time. Needs crm:read or deals:read.
proposal.signed
A proposal was signed. Needs crm:read or deals:read.
proposal.paid
A proposal’s deposit was paid. Needs crm:read or deals:read.
room.opened
Someone opened a share room for the first time. Needs rooms:read.
room.revisited
Someone came back to a share room. Needs rooms:read.
room.forwarded
A share room was opened by someone it was forwarded to. Needs rooms:read.
client.request
A client opened a request from their portal. Needs clients:read.

A workspace can also send these to any endpoint from its own developer center: tool.run_completed, agent_token.created, agent_token.revoked, design.created, design.revised, design.pushed, deal.updated, deal.deleted, contact.created, contact.updated, contact.deleted, company.created, company.updated, company.deleted, subscriber.joined, subscriber.left, campaign.sent, journey.finished, journey.webhook.

The API. Read the CRM, add to it.

Every answer is from the workspace that installed your app, and each route needs one of its permissions. Up to 120 requests a minute for each token and 600 for each workspace; past that you get 429 with Retry-After.

GET /deals
Deals, newest change first. stage, updated_since, limit (up to 100) and offset. With deals:read a deal is its name, stage, value, owner and dates; crm:read adds its company, person, email and source. Needs deals:read or crm:read.
GET /deals/{id}
One deal. Needs deals:read or crm:read.
GET /people
People, with their name, email, title and company. updated_since, limit and offset; /people/{id} for one. Needs crm:read.
GET /companies
Companies, with their domain, industry and size. updated_since, limit and offset; /companies/{id} for one. Needs crm:read.
POST /notes
A note on a deal, a person or a company: {"deal_id": "…", "body": "…"}. It shows on the record’s timeline, written as the person who installed your app. Needs crm:write.
POST /activities
A call, email or meeting: {"person_id": "…", "kind": "call", "subject": "…", "body": "…", "occurred_at": "…", "duration_minutes": 15}. Needs crm:write.
GET /rooms
Share rooms and links, with their deal, how many people opened each, visits, reading time and when it was last opened. deal_id narrows to one deal. Needs rooms:read.
GET /rooms/{id}
One room, with who opened it, how often and when. Never a document’s contents. Needs rooms:read.
GET /library
Each file’s name, kind, tags, folder, version, size and pages, from folders open to everyone. Never the files themselves. Needs library:read.

Endpoints and signing. Check every request.

Every event carries Stacklumen-Signature: t=<unix seconds>,v1=<hex>, an HMAC-SHA256 of t.body keyed with your client secret. Refuse one more than 5 minutes from your clock. Stacklumen-Event names the event, Stacklumen-Event-Id is the same on every retry of it (de-duplicate on it), and Stacklumen-Delivery-Id is new each time. A delivery without a 2xx is tried again after 1 minutes, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, 24 hours, and given up 72 hours after the first.

Authorize
https://www.baselumen.com/app/dashboard/apps/authorize
OAuth 2 authorization code, with PKCE (S256) when you send a code challenge. The person sees every permission before they allow it.
Token
https://www.baselumen.com/app/api/apps/oauth/token
Exchange the code, and refresh. Refresh tokens rotate; a reused one revokes the grant.
Revoke
https://www.baselumen.com/app/api/apps/oauth/revoke
RFC 7009.
Install
https://www.baselumen.com/app/api/apps/v1/install
GET where your app is installed and what it may do; DELETE to remove itself.
API
https://www.baselumen.com/app/api/apps/v1
The routes below, with the access token as Authorization: Bearer bl_app_….

Start building.

Owners and admins build apps from Integrations in their Baselumen workspace.