---
title: "How do I Schedule Chili Piper Meetings Programmatically?"
source_url: https://help.chilipiper.com/hc/en-us/articles/50860790980627-How-do-I-Schedule-Chili-Piper-Meetings-Programmatically
article_id: 50860790980627
updated_at: 2026-07-24T18:55:56Z
content_hash: cf910e5b
---

## Who can use this feature?

Available on All Products or Routing & Scheduling

Available to Only Admins

[Billing Center](https://fire.chilipiper.com/fire/admin/billing/overview) [Get a Demo](https://www.chilipiper.com/request-demo?utm_source=zendesk&utm_medium=help-center&utm_campaign=chili-hub)

**Programmatic scheduling** means booking a Chili Piper meeting without sending the lead through any Chili Piper UI. Your own code – a backend process, a custom frontend, an AI assistant – calls the Chili Piper API, picks a time, and books the meeting directly.

You have three starting points:

- A **Concierge router** – routes a lead using data you submit (plus CRM data when the guest matches an existing record);

- A **ChiliCal scheduling link** – books against a link or user you've already identified;

- A **Handoff router** – routes from an existing CRM lead or contact.

All three use the same two-step pattern.

#### Table of Contents

- [The two-step pattern](#the-two-step-pattern)

- [Before you start](#before-you-start)

- [Concierge](#concierge)

- [Scheduling links](#scheduling-links)

- [Handoff](#handoff)

- [Running it via MCP instead](#running-it-via-mcp-instead)

- [Good to Know](#good-to-know)

- [Related articles](#related-articles)

## The two-step pattern

Every programmatic booking follows the same shape:

- **Discover or route** – a first call returns a session with a list of available time slots and an identifier for the session (routeId);

- **Book** – a second call passes the routeId and a chosen startTime to commit the meeting. Calendar invites are sent immediately.

The session is short-lived and single-use. If the book call fails (for example, the slot is no longer available), start again with a fresh discover or route call.

## Before you start

Generate an API token with the permissions for the patterns you need:

- **Concierge**: **Schedule** under the **Concierge** section;

- **Scheduling links**: **Schedule** under the **Scheduling-links** section;

- **Handoff**: **Schedule** under the **Handoff** section.

Add the **Read** permission in any section where you also need to list assets via API – for example, listing scheduling links by type (as this guide does in the Scheduling links example) or listing Concierge routers.Steps for generating tokens are in the [Edge API References](https://help.chilipiper.com/hc/en-us/articles/35576029581971-Edge-API-References#h_01JEBR95Q9TNCM0VK249BCWARM) article.

Store the token securely – it is shown **only once** at generation. The examples below use `$CHILI_PIPER_API_KEY` as a placeholder; replace it with your token or reference it from your environment.

## Concierge

**When to use:** you want Chili Piper to evaluate routing rules and assign the meeting to the right team or user based on the lead's data.

**The two calls:**

- POST /concierge/routers/[routerSlug]/rest with an interval – routes the lead and returns available slots;

- POST /concierge/routing/[routeId]/schedule-simple – books one of the slots.

You need a Concierge router configured with a trigger (**Third-party Form**, **In-app Button**, or **Router Link**). See [Using Concierge via the Edge API](https://help.chilipiper.com/hc/en-us/articles/30935152032275) for the full Concierge-specific guide.

### Example

**Step 1 – route a lead and get available slots:**

```
curl -X POST \
  "https://fire.chilipiper.com/api/fire-edge/v1/org/concierge/routers/[routerSlug]/rest" \
  -H "Authorization: Bearer $CHILI_PIPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "form": { "PersonEmail": "lead@example.com", "PersonFirstName": "Jamie" },
    "options": { "trigger": "InAppButton" },
    "interval": { "startsAt": "2026-04-14T00:00:00Z", "duration": "7 days" }
  }'
```
The response includes a `routeId` and a list of `startTimes` under `schedulingData`. Pick one.

**Step 2 – book the chosen slot:**

```
curl -X POST \
  "https://fire.chilipiper.com/api/fire-edge/v1/org/concierge/routing/[routeId]/schedule-simple" \
  -H "Authorization: Bearer $CHILI_PIPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "startTime": "2026-04-14T17:00:00Z" }'
```
The response includes a `meetingId`. The lead and assignee receive calendar invites immediately.

## Scheduling links

**When to use:** you already know which scheduling link to book against – for example, a lead-owner link resolved from your CRM, or a specific group link tied to a team.

**The two calls:**

- POST /schedulingLinks/init-simple with a link reference and an interval – initializes a session and returns available slots;

- POST /schedulingLinks/routing/[routeId]/schedule-simple – books one of the slots.

Link types supported:

- **Personal** – a link created by a user in ChiliCal for a specific meeting type;

- **Admin (one-on-one)** – the same as Personal, but created by an admin on behalf of a user;

- **Round Robin** – a team link that rotates assignment across members, either strict (equal turns) or flexible (weighted by availability);

- **Group** – a link with a fixed set of multiple attendees (availability is the intersection of all required attendees);

- **Ownership** – routes to the owner of the guest's CRM record (lead, contact, or account owner), resolved at booking time.

Use the scheduling link list endpoints (`scheduling-link-list-round-robin`, `scheduling-link-list-ownership`, `scheduling-link-list-group`, `scheduling-link-list-admin-one-on-one`) to discover available links programmatically.

### Example

**Step 1 – initialize a scheduling session:**

```
curl -X POST \
  "https://fire.chilipiper.com/api/fire-edge/v1/org/schedulingLinks/init-simple" \
  -H "Authorization: Bearer $CHILI_PIPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "link": { "type": "RoundRobin", "linkId": "[linkId]" },
    "interval": { "startsAt": "2026-04-14T00:00:00Z", "duration": "7 days" }
  }'
```
The response includes a `routeId` and a list of `startTimes`. Pick one.

For **Ownership** links, also pass `guestEmail` in the init call – it is required so Chili Piper can resolve the owner from your CRM.

**Step 2 – book the chosen slot:**

```
curl -X POST \
  "https://fire.chilipiper.com/api/fire-edge/v1/org/schedulingLinks/routing/[routeId]/schedule-simple" \
  -H "Authorization: Bearer $CHILI_PIPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": "2026-04-14T17:00:00Z",
    "guestEmail": "lead@example.com"
  }'
```
The response includes a `meetingId`. Calendar invites go out immediately.

## Handoff

**When to use:** a rep is handing off a lead to another team member – for example, an SDR booking a discovery call with an AE. Handoff uses the rules in a Handoff router to evaluate availability and returns time slots per routing path.

**The two calls:**

- POST /handoff/workspace/{workspaceId}/booker/{userId}/init-simple with the guest's email or CRM record and an interval – evaluates routing paths and returns available slots per path;

- POST /handoff/routing/{routingId}/router/{routerId}/path/{pathId}/booker/{userId}/schedule-simple – books one of the returned slots.

The init request body has two forms:

- {type: "GuestEmailRequest", guestEmail, interval} – when you have the guest's email address;

- {type: "CrmRequest", id, interval} – when you have the CRM record ID (lead or contact) and want Chili Piper to resolve from there.

Both accept optional fields:

- routerId – target a specific router in the workspace instead of evaluating all routers;

- crmExplicits – additional CRM context to pass through to routing rules.

The init response returns one or more routing paths, each with its own `pathId` and `startTimes`. Pick a path and a slot, then pass the corresponding `routingId`, `routerId`, `pathId`, and `startTime` to the schedule call.

### Example

Handoff requires a `workspaceId` and the Chili Piper `userId` of the rep initiating the handoff. Use the `workspace-list` and `user-find` endpoints (or MCP tools) to look these up.

**Step 1 – initialize the handoff and get available slots:**

```
curl -X POST \
  "https://fire.chilipiper.com/api/fire-edge/v1/org/handoff/workspace/[workspaceId]/booker/[userId]/init-simple" \
  -H "Authorization: Bearer $CHILI_PIPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "GuestEmailRequest",
    "guestEmail": "lead@example.com",
    "interval": { "startsAt": "2026-04-14T00:00:00Z", "duration": "7 days" }
  }'
```
The response includes a `routingId` and one or more `routers`, each containing `pathResults` with `startTimes`. Pick a path and a slot.

**Step 2 – book the chosen slot:**

```
curl -X POST \
  "https://fire.chilipiper.com/api/fire-edge/v1/org/handoff/routing/[routingId]/router/[routerId]/path/[pathId]/booker/[userId]/schedule-simple" \
  -H "Authorization: Bearer $CHILI_PIPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "startTime": "2026-04-14T17:00:00Z" }'
```
The response includes a `meetingId`. Calendar invites are sent immediately.

## Running it via MCP instead

All three patterns are exposed as MCP tools. If you are building an AI assistant that reasons over Chili Piper – for example, a workflow that says "find the right scheduling link and book a slot this week" – MCP is the right surface. The tool names mirror the Edge operation IDs (`concierge-route-by-slug`, `concierge-schedule`, `scheduling-link-init`, `scheduling-link-schedule`, `handoff-init`, `handoff-schedule`, and the list discovery tools).

See [Connecting Chili Piper via MCP](https://help.chilipiper.com/hc/en-us/articles/50430350863635-Connecting-Chili-Piper-via-MCP) for setup.

The Edge API and MCP resolve to the same backend. Choose MCP when you want an assistant to pick the tool dynamically; choose Edge when you are writing deterministic integration code.

## Good to Know

- **Sessions are single-use.** On a schedule failure, do not retry the schedule call with the same routeId – start again from the discover or route step;

- **Sessions expire.** For Concierge, the timeout is configured per router path and returned in the response as timeoutInMS. For scheduling links and Handoff, sessions have a server-side TTL. In all cases, if the session expires before you book, call the first step again to get a fresh session;

- **Pass****options.trigger****explicitly on Concierge calls.** If a router has multiple triggers configured, omitting this can cause the API to pick a different trigger than your form keys were written for. Accepted values: ThirdPartyForm, InAppButton, RouterLink;

- **Token permissions matter.** Each pattern needs the **Schedule** permission in its section (**Concierge**, **Scheduling-links**, or **Handoff**). Add **Read** in any section where you also need to list assets via API – for example, listing scheduling links by type, or listing Concierge routers. Generate tokens with only the permissions you need;

- **Slot times are UTC.** The startTime in responses is ISO-8601 UTC; pass it back verbatim on the book call.

## Related articles

- [Edge API References](https://help.chilipiper.com/hc/en-us/articles/35576029581971-Edge-API-References) – complete list of Edge API operations and token generation steps;

- [Using Concierge via the Edge API](https://help.chilipiper.com/hc/en-us/articles/30935152032275) – detailed Concierge-specific guide covering both URL-embed and programmatic booking;

- [Connecting Chili Piper via MCP](https://help.chilipiper.com/hc/en-us/articles/50430350863635-Connecting-Chili-Piper-via-MCP) – setup for AI-assistant-driven booking via Claude Code and other MCP clients.