API and webhooks for developers

With the API, your system reads and loads your company data in Keptmarks: properties, jobs with their progress, maintenance tickets, stock, expenses per property and reservations. With webhooks, Keptmarks notifies your system when something happens. Included in the Professional and Enterprise plans.

OpenAPI 3.1 specificationapp.keptmarks.com/api/v1/openapi.json

Authentication

Create a key in Settings, Integrations, API keys. The full key is shown only once; Keptmarks stores only a fingerprint. Send it on every request in the Authorization header.

Each key belongs to one company and acts with the permissions of whoever created it, limited to the scopes you chose (for example, read properties only). If that person loses a permission or is deactivated, so does the key. You can restrict it to some IP addresses and set an expiry.

curl https://app.keptmarks.com/api/v1/properties \
  -H "Authorization: Bearer km_live_xxxxxxxx"

Creating and changing

Writes go through the same rules as the app: creating a job uses that property template and its fixed people, as on screen. With the Idempotency-Key header, repeating the same request (after a network drop) does not do it twice: it returns the first response with Idempotent-Replayed: true. Idempotency keys are kept for 30 days.

curl -X POST https://app.keptmarks.com/api/v1/jobs \
  -H "Authorization: Bearer km_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f1c7c1e-job-0042" \
  -d '{"property_id":"<uuid>","type":"cleaning","scheduled_date":"2026-11-02","scheduled_time_start":"10:00"}'

Syncing reservations from your PMS

Send each reservation with source (your system) and external_id (its id in your system). If it exists it is updated; otherwise it is created, with its check-out cleaning if you ask. You can resend everything without duplicates.

curl -X POST https://app.keptmarks.com/api/v1/reservations \
  -H "Authorization: Bearer km_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"source":"my_pms","external_id":"R-1029","property_id":"<uuid>",
       "guest_name":"Ana","check_in_date":"2026-12-20","check_out_date":"2026-12-27",
       "create_checkout_cleaning":true}'
# 201 la primera vez, 200 cuando source + external_id ya existian

Lists, pagination and dates

Lists return up to 200 records (limit, 50 by default) sorted by last change. To continue, pass the next_cursor you received. With updated_since you get only what changed since a date: that is how to sync.

Dates are ISO 8601 (YYYY-MM-DD for days). Every response includes time_zone, the company time zone, to read local dates and times.

curl "https://app.keptmarks.com/api/v1/jobs?from=2026-11-01&to=2026-11-30&status=approved&limit=100" \
  -H "Authorization: Bearer km_live_xxxxxxxx"
# -> { "data": [...], "has_more": true, "next_cursor": "eyJ2Ijo...", "time_zone": "America/Costa_Rica" }
curl "https://app.keptmarks.com/api/v1/jobs?from=2026-11-01&to=2026-11-30&status=approved&limit=100&cursor=eyJ2Ijo..." \
  -H "Authorization: Bearer km_live_xxxxxxxx"

Errors

Errors always have the same shape. The code is stable and is what your program should read; the message is in English, or in Spanish with Accept-Language: es.

Common codes: unauthorized (401), key_revoked and key_expired (401), plan_required (402), insufficient_scope, forbidden and ip_not_allowed (403), not_found (404, also when the record belongs to another company), conflict (409), validation_error (422) and rate_limited (429).

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key does not have the jobs:write scope.",
    "request_id": "8c1d..."
  }
}

Rate limits

120 requests per minute per key. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; when exceeded, 429 with Retry-After in seconds.

Webhooks

In Settings, Integrations, Webhooks, add a public https address and choose which notices to receive. Keptmarks sends a POST with the event as JSON: ids and the key fields of the record, never contact data or secrets.

Every delivery is signed: the Keptmarks-Signature header carries the time (t) and an HMAC-SHA256 (v1) of "t.body" with the webhook secret, shown once when created. Reject signatures older than 5 minutes. Answer 2xx quickly; otherwise it is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h. After 15 failures in a row the webhook is turned off and administration is notified. The same event may arrive twice: use its id to ignore duplicates.

Events: job.created, job.started, job.completed, job.approved, ticket.created, ticket.updated, expense.created, supply.low_stock, reservation.created, reservation.updated, document.signed, inventory.item_damaged, asset.maintenance_due and incident.created. The "Send test" button sends a webhook.test.

POST https://tu-sistema.com/keptmarks
Keptmarks-Signature: t=1792411200,v1=5f2b...
Keptmarks-Event: job.completed
Keptmarks-Event-Id: 6a0e...
Keptmarks-Delivery: 91c2...

{
  "id": "6a0e...",
  "type": "job.completed",
  "api_version": "2026-10-15",
  "created_at": "2026-11-02T16:40:11.000Z",
  "organization_id": "...",
  "data": { "job_id": "...", "property_id": "...", "type": "check_out", "status": "ready_for_review", "operator_status": "completed" }
}

import crypto from 'node:crypto'

// rawBody: el cuerpo tal como llego (string), antes de parsear el JSON.
export function verificar(secreto, rawBody, cabecera) {
  const partes = Object.fromEntries(cabecera.split(',').map((p) => p.split('=')))
  const t = Number(partes.t)
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false // vieja: posible repeticion
  const esperada = crypto.createHmac('sha256', secreto).update(`${t}.${rawBody}`).digest('hex')
  const a = Buffer.from(esperada, 'hex')
  const b = Buffer.from(partes.v1 || '', 'hex')
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Ids in other systems

With /links you store what each record is in another system: this property is cost center CC-104 in SAP, this provider is vendor 57 in QuickBooks. An external id is unique per company, system and type.

Zapier and Make

In Zapier or Make, use the webhooks module ("Catch Hook" or "Custom webhook") to receive Keptmarks notices, and the HTTP module with the Authorization: Bearer km_live_... header to read or create data with the API.

Versioning

This is API v1 (/api/v1). Within v1 things are only added: new routes, fields and events. Your program should ignore fields it does not know. A breaking change ships as v2, announced in advance.

Routes

All relative to https://app.keptmarks.com/api/v1. Every field is described in the OpenAPI specification.

Method and routeWhat it doesKey scope
GET/Company, time zone and the scopes of this key.-
GET/propertiesList properties.properties:read
GET/properties/{id}Get a property with its rooms.properties:read
GET/properties/{id}/roomsRooms of a property.properties:read
GET/properties/{id}/stockCurrent stock of each supply in a property.supplies:read
GET/jobsList jobs (cleanings, maintenance, inspections).jobs:read
GET/jobs/{id}Get a job with checklist progress and assignees.jobs:read
POST/jobsCreate a job. Same rules as the app (template of the property, default assignees).jobs:write
GET/ticketsList maintenance tickets.tickets:read
GET/tickets/{id}Get a maintenance ticket.tickets:read
POST/ticketsCreate a maintenance ticket.tickets:write
PATCH/tickets/{id}Update the status (and optionally priority) of a ticket.tickets:write
GET/inventory/itemsList inventory items (furniture, appliances...).inventory:read
GET/suppliesSupply catalog (consumables, tools, amenities).supplies:read
GET/supplies/movementsStock movements (restock, consumption, adjustments).supplies:read
POST/supplies/movementsRecord a restock or a consumption in a property.supplies:write
GET/expensesList expenses, with currency and the property as cost center.expenses:read
GET/reservationsList reservations.reservations:read
GET/reservations/{id}Get a reservation.reservations:read
POST/reservationsCreate a reservation, or update it when source + external_id already exist (PMS sync).reservations:write
GET/providersList service providers (basic fields).providers:read
GET/ownersOwner of each property. Contact fields only when the key creator can edit properties.owners:read
GET/team/hoursHours worked per person and job (up to 93 days).hours:read
GET/rentals/paymentsPayments recorded for equipment rentals (recorded by the office: Keptmarks does not charge rentals).rentals:read
GET/linksLinks between Keptmarks ids and ids in other systems.links:read
POST/linksLink a Keptmarks record with an id in another system (replaces the previous link of that record).links:write
DELETE/links/{id}Remove a link.links:write
GET/assetsList assets and equipment (machines, vehicles, tools). Empty when the module is turned off.assets:read
GET/assets/{id}Get an asset.assets:read
GET/assets/{id}/fuelFuel fill-ups of a vehicle, with the computed fuel economy (km/L, full tank to full tank) of each fill-up that closes a segment, and a summary for the last 30 and 90 days. Amounts only when the key creator can see fleet spending.assets:read
GET/fleet/fuelFuel fill-ups of every vehicle (for accounting and BI), with the vehicle name, plate and property. Amounts only when the key creator can see fleet spending. Empty while fleet phase 2 is not enabled.assets:read
GET/incidentsList incidents. Never the names of the people involved or witnesses; injury details only when the key creator can see them.incidents:read
GET/incidents/{id}Get an incident (same privacy rules as the list).incidents:read

Changelog

  • 2026-10-15 · First public release of API v1, signed webhooks and ids in other systems.