API and integrations

Kelomo’s public API is used with API keys. The organisation’s keys are managed under Settings → Integrations → API keys and apps, and its webhooks on the Webhooks page in the same group. You create your own personal key in your own settings on the My API keys tab.

Two kinds of keys

• A personal key acts with your permissions and reaches at most as far as you do. The key ends when your membership ends. Every user can create their own.
• A service key is for integrations that must work independently of any single person. It has a named Owner – the member whose authority the key acts with – and the owner can be changed later with Change owner; the token, permissions and history stay. Service keys are created by an admin.

Create a key

1. Press New key (your own key) or New service key (the organisation’s).
2. Give the Key name and, if you like, a description. A service key also needs an Owner.
3. Pick the Key permissions. Only the permissions the key’s holder has themselves are available. A personal key with no permissions selected reaches only your own data; a service key requires at least one permission.
4. Pick the Validity (30 days, 90 days, 1 year or no expiry) and tick Read-only if needed.
5. Save. The key’s value starts with kelomo_ and is sent in requests in the Authorization: Bearer header.

The value is shown only once. Copy it right away. If the value is lost, you can rotate your own key with Rotate key – the old one remains valid for 24 hours – or create a new key.

Managing keys

The list shows the key’s prefix, creation date, last use and the request count over seven days. Revoke takes a key out of use permanently. When a key approaches its expiry, Kelomo sends a notification in advance so you can renew it before the outage.

Webhooks

On the Webhooks page, Kelomo posts the selected events to the URL you give – for example published shifts, invoice events and absence decisions.

1. Press Add webhook and give the URL. It must start with https://.
2. Pick the Message type: JSON (signed) for integrations, Slack or Microsoft Teams for ready messages posted to the channel’s incoming-webhook URL. Slack and Teams messages also take a Message language.
3. Pick the Events.
4. Save. For the JSON type, the signing secret (X-Kelomo-Signature) is shown – it too only once.

Row actions: Test sends a test message, Disable stops deliveries and Enable resumes them. Rotate secret rotates the signing secret (the old one remains valid for 24 hours). The type cannot be changed afterwards – create a new webhook if needed.

The webhook’s URL in the list opens its page with the Delivery history. A failed delivery is retried automatically; the row shows the next attempt, and you can resend a delivery by hand with the Resend action. If a delivery is given up on for good, you get a notification.

Zapier

Kelomo is available in Zapier as a ready-made connector. A Zap starts from a Kelomo event, such as a new lead, a won deal, a quote decision, a submitted or decided absence, an approved workday, a published shift, a finished payroll export, an issued invoice, a recorded payment or a change to a customer, project or task. The actions Create Lead, Create Task, Create Customer and Create Intake Item create a lead, a task, a customer or an intake request in Kelomo. The register imports, work days and approvals are described further down.

1. Create a service key as described above. Give it the permission Manages webhooks and integration events plus the permission of each event you use: sales events need the sales workspace permission, absences and workdays the supervisor permission, shifts the shift-planning permission, and invoices and payments the invoicing permission. If the Zap creates data in Kelomo, leave Read-only unticked.
2. Open Kelomo’s invite link in Zapier, Kelomo in Zapier, and accept the invitation. After that, Kelomo appears in Zapier’s app search.
3. Build the Zap. The first time you pick Kelomo, Zapier asks you to connect an account: paste the key into API Key. API URL defaults to Kelomo’s address.

The sample event Zapier shows is taken from the organisation’s most recent events, so test the Zap once Kelomo has at least one event of that kind. An event carries identifiers, state and timestamps. Each Zap creates its own row under Webhooks, and deleting the Zap removes the row.

Recipe: projects from another tool as tracking targets

When the projects live in Jira, they can become tracking targets in Kelomo without the project module. Create the tracking level first, for example “Project (Jira)”.

The Zap starts from a new or updated issue in the chosen Jira project. Kelomo’s action Create or Update Tracking Target creates the target or updates it: pick the level from the list, give the issue key as the code, the summary as the name, your own namespace as the source (jira_acme_issue, for instance) and the issue id as the identifier. When the issue reaches a state that ends the work, send the same action with Active false: the target is taken out of use and the hours booked on it stay. The next step of the Zap reads the target with Find Tracking Target, which looks it up by the code or by the source identifier.

The action needs a service key whose owner has organisation admin rights. The same recipe works for any other source Zapier offers an event for.

Customers, projects and tasks the same way

The same pattern reaches the other three registers. Create or Update Customer, Create or Update Project and Create or Update Task match a row on the source identifier first and only then on the code, so a second run on the same source record updates the row instead of creating a new one. Find Customer, Find Project and Find Task look a record up with a single key: the code, the source identifier or the Kelomo id. A task is looked up inside its project by the source identifier or by the task number.

The namespace separates the system, the environment and the record type (hubspot_acme_company, jira_acme_project, jira_acme_issue), so two sources can never collide inside one organisation. The code is given once and a later sync never changes it: the payroll material and the accounting transfers recognise the record by it.

A row that goes through unchanged writes nothing in Kelomo and leaves no line in the history. A row that is refused stops the Zap and says why: the usual reasons are a code already held by another source, a record made by hand that needs the Adopt an Existing Record by Code option, or a row carrying neither a code nor an identifier.

In the other direction, triggers report what Kelomo did: customer created or changed, project created, changed or closed, task created, changed or moved to another column. The event carries identifiers and a timestamp, so the next step is a Find action.

A task’s status from the source

The source’s status is the source’s own word (“In Progress”, “Klaar”, “3”). It is given in the External Status field, and Kelomo translates it under Settings → Projects → Status mappings: source, external status and the Kelomo status type. A word that is not in the table stops the Zap — Kelomo does not guess a column. Fill the mappings in before the first run.

Recipe: a Jira project and its tasks into Kelomo

1. The Zap starts from Jira Software Cloud → New Issue on the chosen board.
2. Create or Update Customer brings the customer in: the name from Jira’s organisation field, source jira_acme_org, identifier the organisation id. Skip the step when the customers are already in Kelomo.
3. Create or Update Project brings the project in: the name from the epic’s summary, Customer Code the code from the previous step, source jira_acme_project, identifier the Jira project id and Status from Jira’s state (Done → closed).
4. Create or Update Task brings the task in: Project Code the code from the previous step, the title from the issue summary, source jira_acme_issue, identifier the issue id, External Status the name of the Jira status and Assignee Email the assignee’s address.
5. Make a second Zap on the Updated Issue event with the same three actions.

The recipe has not been run against a real Jira account — it is written from the actions and the API. The Kelomo side is verified by running the actions against a development server.

Work days, approvals and people

Add Work Entries adds a row to a work day: start and end or a duration in minutes, the entry type and project from the list, and a note. The day’s other rows stay, and the day remains a draft the employee confirms themselves. With Replace the Day’s Entries the row becomes the day’s only one. If the day was edited in Kelomo at the same time or is already confirmed, the Zap stops with the reason and writes nothing. With Member left empty the row goes on the key owner’s own day; another person’s day needs supervisor rights and the organisation setting that lets a supervisor record on someone’s behalf. A repeated run from the same source record writes the row once when Source Record ID carries the source record’s id.

An approval is always its own action: Approve Work Day and Return Work Day handle a confirmed work day, Approve Absence and Reject Absence an absence request. Returning and rejecting take a reason the employee sees. Invite Member adds a person to the organisation and e-mails them an invitation.

The searches Find Member (by e-mail address), Find Invoice (by invoice number), Find Lead (by part of the name, company or title) and Find Work Day (person and day) read the records an event points to. The new events cover confirmed, returned and corrected work days, cancelled absences, paid and overdue invoices, people added, changed and deactivated, ended employments, and changes to deals, leads and field work.

Power Automate

In a Microsoft 365 house Kelomo is connected with a custom connector. A ready-made one is available in the developer portal, Power Automate connector: it carries the same register import actions and lookups, work days and approvals, and an event trigger.

1. Download the connector definition from the portal page.
2. In Power Automate choose Data → Custom connectors → New custom connector → Import an OpenAPI file.
3. Create a connection and paste the key in full, as Bearer kelomo_….
4. Try the connection with the Check the connection action.

The writing actions need a service key whose owner has organisation admin rights.

Deleting the flow also cancels the trigger’s subscription: Kelomo’s response names the subscription’s address, which Power Automate calls when the flow is deleted. A single subscription can also be removed under Settings → Integrations → Webhooks, or with the connector’s Delete an event subscription action.

Connected apps

AI assistants and other off-the-shelf apps connect by signing in, not by copying a key: in the app you choose Kelomo, the user signs in, picks an organisation and approves the permissions asked for. The app acts with the approver’s permissions and never gets more than they hold themselves — if the app asked for more, the consent screen says so before they approve.

Connections appear under Settings → Integrations → API keys and apps in the Connected apps section: which app, whose permissions it uses and when it last called. You see your own connections in your own settings on the AI assistant tab, which also has the instructions for connecting (see Connect an AI assistant). Disconnect ends a connection immediately — the app’s next call fails. Changing or resetting your password disconnects every app on your account.

A connected app is never granted the right to manage organisation settings, billing or API keys. An integration that has to do those things needs a service key, created by a person.

API documentation and MCP

The developer documentation lives at kelomo.fi/developers: authentication, events, error codes, rate limits and the OpenAPI spec. The MCP and OAuth guides are there too. An MCP connection works either way: the client signs in (recommended) or uses a kelomo_ key. Either way the AI client acts within the credential’s permissions.

Netvisor and Lemonsoft connection

The connection is created under Settings → Integrations → Connections. The same connection serves the payroll, invoicing and travel material transfers.

Do these in Netvisor first:

1. Create API identifiers: Company menu → Api identifiers → create a new one. The key is shown only once. The identifier belongs to a user, so the transfer stops working if that user is removed.
2. Allow the API resources: Company menu → API resource rights. The resources needed are workday.nv, getrecordtypelist.nv, getemployees.nv and salesinvoice.nv, plus customerlist.nv and purchaseinvoicelist.nv when customer creation or purchase-invoice import is used.
3. Give the record types their numbers in Netvisor. They are empty by default, and the number routes hours to the right type.
4. Check the product codes and customer numbers in Netvisor’s registers. They go into the destination’s mappings.

Netvisor’s fields: the customer ID and key come from the API identifier, and the business ID is that of the company whose Netvisor the data goes to.

Lemonsoft’s fields: the interface user (not a personal login), the key Lemonsoft issues and the database (Settings → Details in Lemonsoft). Fill in the address only if Lemonsoft gave you a dedicated address.

If something goes wrong

You no longer have the key’s value. The value is not shown again. Rotate your own key, or create a new key and revoke the old one.

A service key responds with 401. If the key’s owner has been deactivated, the key stops working. Assign the key to another member with Change owner.

A request responds with 403. The key’s permissions are not enough, or the key is Read-only. Create a new key with the permissions you need.

A webhook delivery does not get through. When the delivery history shows Permanently failed, check the receiver’s URL and response, fix the receiver and choose Resend.