Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Calendar and CRM

Typed calendar and CRM methods on a customer: book and find meetings, free slots, contacts, notes, tasks and deals, with the app picked from what the customer connected.

customer.calendar and customer.crm are the unified API with the fields named. Each method takes a TypeScript interface with the catalog's own field names (start_time, first_name, …) and answers a record { id, provider, data, warnings? } or a page { records, nextCursor, hasMore }. You never name the app: the SDK reads which app the customer connected for that entity and uses it.

const customer = fastn.customer("acme_customer_42");

const booked = await customer.calendar.book(
  { title: "Intro call", start_time: "2026-11-03T15:00:00Z", end_time: "2026-11-03T15:30:00Z", timezone: "Europe/London", attendee_email: "jane@example.com" },
  { idempotencyKey: "booking_123", correlationId: "req_abc" },
);
console.log(booked.id, booked.provider, booked.data.web_url);

const { records } = await customer.crm.contacts.find({ email: "jane@example.com" });
const contact = records[0] ?? (await customer.crm.contacts.create({ first_name: "Jane", last_name: "Doe", email: "jane@example.com" }));
await customer.crm.notes.add({ body: "Booked an intro call", parent_id: contact.id, parent_type: "contact" });

Every method takes the request options last: provider, connectionId, idempotencyKey, correlationId, timeoutMs, retries.


Which app answers

Situation
What happens

The customer connected one app for the entity

It is used. The choice is kept for 60 seconds per client, then read again, so a new connection is picked up without a restart.

None

404 NO_CONNECTED_PROVIDER. Send a setup link.

Several, for example two CRMs

409 PROVIDER_AMBIGUOUS. Pass { provider: "hubspot" } on the call.

The connected app cannot do this operation

404 OPERATION_NOT_SUPPORTED. Check customer.catalog.providers(category, entity).

Two accounts for the same app

Pass { connectionId } (from customer.connections()).

Date values are sent as ISO strings. warnings on an answer lists a field the app does not map and therefore dropped.


Calendar

Method
Underneath
Input

calendar.freeSlots(window)

scheduling/availability

start_time, end_time (required), timezone, slot_minutes. Answers { busy, free, slots }: busy from the calendar, free the gaps, slots the gaps cut into slot_minutes pieces (left out without slot_minutes).

calendar.book(meeting)

scheduling/meeting create

title and start_time (required), plus end_time or duration_minutes. Optional: timezone, description, attendee_email, attendee_name, location, calendar_id, event_type_id, status.

calendar.get(id)

get

The meeting id.

calendar.find(filters, page?)

search

start_time, end_time (required), query (matches the title, description and attendee email). page_size only: a search answers one page.

calendar.list(page?)

list

page_size, cursor.

calendar.reschedule(id, times)

update

start_time, plus end_time or duration_minutes.

calendar.cancel(id)

delete

The meeting id. Answers { id, provider, deleted: true }.

freeIntervals(start, end, busy) and slotsOf(free, minutes) are exported too: the arithmetic behind freeSlots, for busy times you already have.


CRM

Group
Underneath
Methods

crm.contacts

crm/contact

create, get, find({ email, phone, first_name, last_name }), list, update, delete

crm.notes

crm/note

add({ body, parent_id, parent_type, title?, created_at? }), update, delete. created_at defaults to now.

crm.tasks

crm/task

add({ subject, due_date, status, … }) (status is the app's own value, for example HubSpot's NOT_STARTED, IN_PROGRESS, WAITING, COMPLETED or DEFERRED), get, list, update, delete

crm.deals

crm/opportunity and crm/stage

create({ name, amount, stage, … }), get, list, update, moveStage(id, stage), delete, stages()

find is the app's own search and answers one page: narrow the filters or raise page_size to see more. Passing a cursor to find is refused with a TypeError; list({ page_size, cursor }) pages.


The catalog

Which categories and entities exist, the fields each takes, and which apps a customer connected:

Method
Answer

fastn.catalog.categories()

Every category with its entities. Cached for the life of the client; fastn.catalog.refresh() reads it again.

fastn.catalog.category(slug), fastn.catalog.entity(category, entity)

One category, one entity.

fastn.catalog.fields(category, entity)

The create fields, each { field, label, type, required }.

fastn.catalog.providers(category, entity)

The apps mapped to the entity.

customer.catalog.providers(category, entity)

The same list with connected for this customer.

What the typed methods do not cover is one call away: customer.records({ category, entity }) takes any entity in the catalog (see Unified records), and customer.runAction(…) runs an app's own action (see Direct app actions).

Last updated

Was this helpful?