> For the complete documentation index, see [llms.txt](https://docs.sprinthub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sprinthub.com/en/topics/api/how-to-schedule-a-meeting-via-api.md).

# How to Schedule a Meeting via API

This article explains how to use the public endpoint `/calendarmeeting` of the SprintHub API to schedule meetings automatically based on a calendar created on the platform.

***

#### ✅ Overview

The endpoint `/calendarmeeting` allows scheduling meetings directly on a calendar link, using data from an existing lead or automatically creating a new lead with the submitted data.

> 📌 **This endpoint is public.** It does not require authentication (`apitoken` or `Authorization`) — but requires the call to be made within the correct instance context.

```
POST https://sprinthub-api-master.sprinthub.app/calendarmeeting?i=instance_name

```

#### 🔑 Required parameters

| Parameter | Type   | Where it goes | Description                                    |
| --------- | ------ | ------------- | ---------------------------------------------- |
| `i`       | string | query         | Instance name (ex: `support`)                  |
| `keyName` | string | body          | Calendar ID, obtained from the public link URL |
| `date`    | string | body          | Meeting date and time in ISO 8601 format (UTC) |

#### 🧾 Body structure

**🔹 Option 1 – Schedule by creating a new lead**

```json
{
  "keyName": "TGcbitBqLjqmmp5tRzlX3",
  "leadId": null,
  "opportunityId": null,
  "date": "2025-06-27T15:30:00.000Z",
  "formData": {
    "firstname": "Wanderson Fernandes",
    "email": "emailteste@sprinthub.com"
  },
  "properties": {}
}

```

🔹 Option 2 – Schedule for an existing lead

```json
{
  "keyName": "TGcbitBqLjqmmp5tRzlX3",
  "leadId": 2222,
  "opportunityId": null,
  "date": "2025-06-27T15:30:00.000Z",
  "formData": {},
  "properties": {}
}

```

❗ When `leadId` is provided, **do not send the `formData`** to avoid conflicts.

#### 🧠 Important notes

* **`leadId`** must be a valid lead from the same instance.
* **`formData`** is required **only when `leadId` is `null`** (will be used to create the lead).
* **`properties`** can remain as `{}`. It is used only for rescheduling or additional data in more advanced calls.
* The date and time must be in **UTC** (ex: `2025-06-27T15:30:00.000Z`).
* The calendar link needs to be **active and with available times**.

#### 📌 Where to find the `keyName`

Access your public scheduling link. Example:

```
https://instance.sprinthub.app/calendar/TGcbitBqLjqmmp5tRzlX3

```

The final segment of the URL is the `keyName`:

```json
TGcbitBqLjqmmp5tRzlX3
```

#### 💥 Common errors

| Code    | Meaning                                                                  |
| ------- | ------------------------------------------------------------------------ |
| `CL006` | The `keyName` does not belong to the provided instance or is not active. |
| `CL008` | The `leadId` does not exist or does not belong to the correct instance.  |
| `400`   | Missing or poorly formatted data (ex: `null` as a string: `"null"`).     |

request example:

```
curl -X POST "https://sprinthub-api-master.sprinthub.app/calendarmeeting?i=instance" \
  -H "Content-Type: application/json" \
  -d '{
    "keyName": "TGcbitBqLjqmmp5tRzlX3",
    "leadId": null,
    "opportunityId": null,
    "date": "2025-06-27T15:30:00.000Z",
    "formData": {
      "firstname": "Wanderson Fernandes",
      "email": "emailteste@sprinthub.com"
    },
    "properties": {}
  }'

```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sprinthub.com/en/topics/api/how-to-schedule-a-meeting-via-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.