# 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.