API reference

One endpoint adds people, timeline entries and tasks to a workspace. It is the same one Damaruka uses, so anything you send looks and behaves like a call does.

Keys

An owner makes a key in the workspace, under Connections. It starts with tlk_, is shown once and is stored only as a fingerprint. Send it as a bearer token from your server, never from a browser. Removing a key stops it at once.

curl https://tieloom.com/api/v1/workspace \
  -H "Authorization: Bearer tlk_your_key"

{"id": "5c2f...", "name": "Maple Street Dental", "kind": "clinic"}

Sending events

POST /api/v1/events takes one event as JSON. For anything that is not a call, use activity.created:

curl https://tieloom.com/api/v1/events \
  -H "Authorization: Bearer tlk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "activity.created",
    "id": "form-1042",
    "person": {"name": "Dee Shah", "email": "dee@example.com", "phone": "(415) 555-0142", "company": "Shah Dental"},
    "activity": {"kind": "form", "title": "Asked for a quote", "body": "Wants 40 units.", "link": "https://example.com/forms/1042"},
    "task": {"title": "Send Dee a quote", "due_on": "2026-10-21"}
  }'

{"person_id": "9b1e...", "duplicate": false, "new_person": true}

Field	What it does
id	Required. Your own id for this event. Send the same id again and Tieloom keeps one entry.
person.phone, person.email	At least one, so Tieloom can find the person. A phone number without a country code is read as the workspace's country.
person.name, person.company	Filled in when the record has none; never written over.
activity.kind	One of call, message, email, booking, request, note, meeting or form.
activity.title	Required. One line, shown on the timeline.
activity.body, activity.link, activity.occurred_at	Optional. A link must start with http or https; the time is ISO 8601 and defaults to now.
task.title, task.due_on, task.urgent	Optional. A task for the person, due on a date like 2026-10-21.

Calls

A call.ended event is the body Damaruka's webhooks carry. Tieloom finds or makes the person by the number that called, hangs the call on their timeline with the summary and details, adds a call back task for a message, an enquiry, an intake, a repair request or an emergency, and moves the person forward on a booking. A call with "mode": "test" is shown as a test and leaves no task.

{
  "event": "call.ended",
  "id": "a delivery id",
  "call": {
    "id": "c1", "mode": "live", "caller_phone": "+14155550123",
    "started_at": "2026-10-18T15:04:00+00:00", "duration_seconds": 94,
    "summary": "Wants a cleaning before the 30th.", "urgent": false,
    "outcomes": [{"kind": "message", "fields": {"name": "Ana Ruiz"}}],
    "details": [{"label": "Message", "value": "Cleaning before the 30th"}],
    "link": "https://damaruka.com/c/abc123"
  }
}

Answers and errors

A 200 answer says which person the event landed on, whether they are new, and whether it was a repeat ("duplicate": true, nothing changed). Otherwise:

401	No key, or a key that is not this workspace's (or was removed).
400	The body is not JSON.
413	The event is over 256 KB.
422	The event cannot be used as sent. The message says what to change; sending it again unchanged will not help.
409	Two events for one new person arrived at the same moment and this one lost. Send it again.

Questions or something missing? See how connections work, or write to augusta@4ugusta.agency.