Core concepts

Sources of truth

This is the rule that prevents most integration bugs:

• Talki’s database is authoritative for appointments Talki owns. Whether a booking may be committed is decided there, under a lock, after a recount.
• External calendars contribute read-only busy time. Google and Outlook events that Talki does not own become constraints the agent honours during a call. They never decide whether something may be booked.

A connected CRM calendar behaves the same way: it can block time, it cannot approve a booking.

Identifiers

Timestamps

All timestamps are RFC 3339 with an explicit offset. Account-local wall-clock times carry the account’s timezone separately where it matters.

Phone identity

A phone number in E.164 is how a caller is matched to a contact. Matching is narrower than you might expect on purpose — see the contact-matching rules before assuming a call and a contact will be linked.

Names you write are respected

A contact name written through the API is treated as a trusted source and is not overwritten by the post-call name extraction.

Pagination

Cursor-based, stable under concurrent writes. Combine updated_after with the cursor to recover anything you missed while your endpoint was down.

Versioning

Two independent mechanisms:

1. The path /v1 is frozen. It will not change shape.
2. A dated version — Talki-Version: 2026-10-01 — is pinned per credential and per webhook endpoint, and is how breaking changes are introduced.

Additive changes (new fields, new enum members on open enums, new event types) ship inside a dated version without notice. Write parsers that ignore what they do not recognise.