Talk to us about your integration
In the demo we look at which systems you want to connect and which routes and webhooks you need for that.
- Home
- Product
- API and integrations
A CRM API you can connect yourself
Lumo has a public REST API with 49 routes and an OpenAPI spec, signed webhooks and an MCP server for AI tools. You connect your website, your ERP or your own scripts with keys that can do exactly what they need.
- REST API with 49 routes and openapi.json
- Webhooks with signing and a delivery log
- MCP server with 6 tools
Why a CRM has to be connectable
A CRM never stands alone. Orders come from an ERP, requests from a landing page an agency built, invoices from an accounting package. If the CRM cannot be connected, a second administration appears: someone copies the new requests over every morning, and once a month customer data gets compared by hand. That takes hours and it regularly goes wrong.
So the question with a CRM integration is not just whether there is an API. The real questions are: what can the API read and write, how safe are the keys, what happens when a request arrives twice, and how does the other system hear that something changed? This page answers those questions.
Lumo has a REST API under /api/v1 with 49 routes and an openapi.json your developer or tool can load to read the whole spec. The API covers contacts, deals with pipelines and stages, leads, and activities with notes. Keys get only the permissions they need and can have an expiry date. Webhooks tell your own system about an event, signed with a secret so you can check that the message really comes from Lumo.
For AI tools there is an MCP server. It lets an AI assistant outside Lumo search your CRM, create a person or lead and log an activity. If you would rather use the assistant inside Lumo, see the AI assistant. For an overview of every integration, including Gmail, Google Calendar and the Pipedrive import, see integrations.
How you connect a system to Lumo
Go to Settings, the Automation group, and open API and integrations.
Create a key
Under API keys, create a key. Give it a name, choose the permissions and optionally a date when it expires.
Store the key
Copy the key straight away. You will never see it again. Store it in the vault or settings of the system that connects.
Send requests
Send the key as an Authorization header with Bearer. Load openapi.json for the routes and fields.
Add a webhook
Under Webhooks, add a webhook, choose the https address and the events, and copy the secret you use to verify messages.
Test and monitor
Send a test message and check under Deliveries whether it is Delivered, Queued or Failed. Last used shows when a key last worked.
The API covers the core of your sales records. Persons and organizations, deals with their pipeline and stage, leads, and activities with notes. You can use it to mark a deal won when an order is confirmed in your ERP, create a lead for every request from a landing page, or log a call from your own phone tool.
Keys have permissions per area: read, write or both, for contacts, deals, leads and activities, plus a separate permission to manage webhooks. A key for your website can only write leads. A key for a reporting tool can only read. That limits the damage if a key ever leaks, and you revoke it with one click.
The limits are clear: 600 requests per minute per key and a body of up to 1 MiB. Errors come back with a fixed code, such as insufficient_scope when a key lacks a permission, or validation_failed with an explanation per rule.
- 49 routes under /api/v1 plus openapi.json
- Permissions per area: read, write or both
- Keys with expiry, revoke and last used
- 600 requests per minute and up to 1 MiB per request
With a webhook, Lumo sends a message to an address of yours as soon as something happens, such as a person being created. You choose 1 to 50 event types, or an asterisk for all of them. Your ERP no longer has to ask every minute whether anything is new.
Every message is signed with a secret you see once when you add the webhook. Your system checks the signature and knows the message came from Lumo. Create new secret rotates it, for example when someone leaves. Deliveries shows for each message whether it arrived.
Lumo only sends webhooks to public https addresses. Addresses with credentials in them, blocked ports and internal or private addresses are refused. Web forms also have their own outgoing signed webhooks with retries and a delivery log, for anyone who wants to send a submission straight to another system. See web forms.
- Choose events, or an asterisk for everything
- Signed with a secret you can rotate
- Deliveries with status Delivered, Queued or Failed
- Public https addresses only
MCP is an open way for AI tools to use the tools of other systems. Lumo has an MCP server at /mcp that you reach with an API key. An AI assistant that supports MCP can then work in your CRM.
The server has six tools: search, get_person to fetch a person, list_deals to list deals, create_person, create_lead and log_activity. That is enough to look up a customer during a conversation in your AI tool, record a new request as a lead or log a call note.
Because the MCP server uses a normal API key, the same permissions and limits apply. Only give the key what the AI tool needs. Keep in mind that the AI tool itself may send data to its own provider, so read that tool's terms.
- MCP server at /mcp with an API key
- Six tools: search, get_person, list_deals, create_person, create_lead, log_activity
- Same permissions and limits as the REST API
What the API and integrations include
OpenAPI spec
openapi.json describes all 49 routes, so your developer or tool can load them.
Permissions per key
Read, write or both per area, plus manage webhooks. With expiry and revoke.
Idempotency-Key
Send an Idempotency-Key and a repeated request does not create a second record.
Clear limits
600 requests per minute per key and up to 1 MiB per request.
Webhooks
Signed, with secret rotation, a delivery log and a test message.
Safe addresses
Public https addresses only. Internal and private addresses are refused.
MCP server
Six tools for AI tools, reached with an API key.
Error codes
Every error has a fixed code, such as invalid_api_key, rate_limited or payload_too_large.
Example: orders from an ERP and requests from a landing page
Say a manufacturer with its own ERP and a marketing agency that builds landing pages wants to connect both to Lumo. Here is an example of how a developer could set it up.
For the landing pages he creates a key with only the Leads write permission and an expiry date at the end of the campaign. The agency's form sends a request to create a lead for every submission, with an Idempotency-Key per submission. If a network error makes a request arrive twice, Lumo creates the lead only once. When the campaign ends, the key expires on its own.
For the ERP he creates a second key with Deals read and write and Contacts read. When an order is confirmed in the ERP, the ERP looks up the deal and marks it won. In the other direction he adds a webhook that notifies the ERP when a new person is created, so the contact exists there too. The ERP checks every message against the secret. On the first day Deliveries shows two Failed messages because the ERP was briefly unreachable, and he fixes it.
If the agency developer leaves, the admin revokes that key and creates a new webhook secret. Everything else keeps working.
How to set up an integration safely
These points apply to every integration, large or small.
- Create a separate key per system with a recognisable name.
- Give each key only the permissions that system needs.
- Set an expiry date on keys for temporary integrations, such as a campaign.
- Store keys and secrets in a vault, not in a document or an email.
- Send an Idempotency-Key with every create request.
- Check the signature on every webhook message with the secret.
- After the first day, check Deliveries for failed messages.
- Revoke keys and rotate secrets when someone with access leaves.
How the API connects to the rest of Lumo
The API is one of several integrations. Gmail and Google Calendar connect per user without code, and a Pipedrive import runs through the wizard with a Pipedrive API token. See switching from Pipedrive. The full overview is on integrations.
If you want something to happen automatically inside Lumo, such as a task after a stage change, you do not need the API but a rule in automations. Web forms have their own webhooks, see web forms. And how keys, roles and the log fit together is on security and privacy.
What you should know about the API
Today the public API covers contacts, deals with pipelines and stages, leads, and activities with notes. Tickets and campaigns are not in it yet, and you manage those in Lumo itself. There are no OAuth apps for third parties and no ready-made app in Zapier or Make. If you want to use such a tool anyway, use its generic HTTP and webhook modules with an API key and the Lumo webhooks. If you work with Outlook or Microsoft 365: the Outlook and Microsoft 365 integration is planned. Until then, put your personal BCC address in Bcc or forward a mail to it, and it lands on the right person, organization and deal.
API and integration questions
Does Lumo have a public API?
Yes, a REST API under /api/v1 with 49 routes and an openapi.json. It covers contacts, deals with pipelines and stages, leads, and activities with notes.
How do I keep an API key safe?
Give it only the permissions it needs, set an expiry date if it suits and store it in a vault. You see the key only once. Revoking it switches it off at once.
What are the API limits?
600 requests per minute per key and a body of up to 1 MiB per request. Too many requests return the code rate_limited.
How do I avoid duplicates when a request is repeated?
Send an Idempotency-Key. A second request with the same key does not create a new record.
How do I check that a webhook really comes from Lumo?
Every message is signed with a secret you see once when you add the webhook. Your system verifies the signature with that secret.
What is the MCP server?
An integration for AI tools that support MCP. With an API key the tool gets six tools: search, fetch a person, list deals, create a person or lead and log an activity.
Is there a Zapier or Make integration?
There is no ready-made app. You can use the generic HTTP and webhook modules in those tools with an API key and the Lumo webhooks.
Can I manage tickets and campaigns through the API?
Not yet. The API covers contacts, deals, leads and activities. You manage tickets and campaigns in Lumo.
Does Lumo work with Outlook?
The Outlook and Microsoft 365 integration is planned. Today the personal BCC address works with any mail client, Outlook included, and you can log mail by hand. Every other part of Lumo is independent of your mail client.
Keep reading
