# Scheduling

## Use this method to schedule a meeting

<mark style="color:green;">`POST`</mark> `https://app.zencal.io/api/v1/schedule`

#### Headers

| Name                                               | Type   | Description      |
| -------------------------------------------------- | ------ | ---------------- |
| X-Zencal-Api-Key<mark style="color:red;">\*</mark> | String | Zencal Api key   |
| Accept<mark style="color:red;">\*</mark>           | String | application/json |
| Content-Type<mark style="color:red;">\*</mark>     | String | application/json |

#### Request Body

| Name                                           | Type   | Description                                                                                                                                                                                                                                                                      |
| ---------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dates<mark style="color:red;">\*</mark>        | Array  | Array of objects. Each date need to have "start" and "username" fields. Field "start" is a UTC date in ISO 8601 format. Field "username" is a host's username e.g. \[ { "start":"2023-05-13T10:00:00.000Z", "username":"joe-smith" } ],                                          |
| email<mark style="color:red;">\*</mark>        | String | Participant's email                                                                                                                                                                                                                                                              |
| lang<mark style="color:red;">\*</mark>         | String | Language for system messages. Available values: en, pl                                                                                                                                                                                                                           |
| name<mark style="color:red;">\*</mark>         | String | Participant's name                                                                                                                                                                                                                                                               |
| phone                                          | String | Participant's phone number. It can be required as it's defined in meeting topic advanced settings.                                                                                                                                                                               |
| place<mark style="color:red;">\*</mark>        | String | <p>Place of the meeting. Available values: </p><p>"offline"</p><p>"phone-call"</p><p>"google-meet"</p><p>"teamsForBusiness"</p><p>"skypeForBusiness"</p><p>"skypeForConsumer"</p><p>"zoom"</p><p>"webex"</p><p></p><p>The place must match the account integration settings.</p> |
| meetingTopic<mark style="color:red;">\*</mark> | String | Meeting topic's uuid                                                                                                                                                                                                                                                             |
| team                                           | String | Team's uuid. Required if it's a team meeting                                                                                                                                                                                                                                     |
| timezone<mark style="color:red;">\*</mark>     | String | Participant's timezone                                                                                                                                                                                                                                                           |
| gateway                                        | String | <p>Payment gateway code. Available options:</p><p>"stripe"</p><p>"p24"</p><p>"payu"</p><p>"paypal"</p><p>"tpay"</p><p></p><p>It's required if meeting topic is defined as paid.</p>                                                                                              |
| note                                           | String | Note left by participant                                                                                                                                                                                                                                                         |
| invoiceName                                    | String | Name for the invoice                                                                                                                                                                                                                                                             |
| invoiceAddress                                 | String | Address for the invoice                                                                                                                                                                                                                                                          |
| invoicePostalCode                              | String | Postal code for the invoice                                                                                                                                                                                                                                                      |
| invoiceCity                                    | String | City for the invoice                                                                                                                                                                                                                                                             |
| invoiceTaxNumber                               | String | Tax number for the invoice                                                                                                                                                                                                                                                       |
| discount                                       | String | Discount code                                                                                                                                                                                                                                                                    |
| priceVariant                                   | String | Price variant uuid                                                                                                                                                                                                                                                               |
| form                                           | Object | Form answers                                                                                                                                                                                                                                                                     |
| metadata                                       | Object | In this field you can store any information you need                                                                                                                                                                                                                             |

{% tabs %}
{% tab title="200: OK For free meetings" %}

```json
{
    "success": "Meetings have been scheduled",
    "meetings": [
        {
            "uuid": "ceb85978-0494-11ee-be56-0242ac120002",
            "date": "2023-06-12T13:00:00.000000Z"
        }
    ]
}
```

{% endtab %}

{% tab title="200: OK For paid meetings" %}

```json
{
    "paymentUrl": "https://...."
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```json
{
    "errors": [
        "gateway": "This field is required",
        "meetingTopic": "This field is required"
    ]
}
```

{% endtab %}
{% endtabs %}

## Use this method to calculate available dates

<mark style="color:green;">`POST`</mark> `https://app.zencal.io/api/v1/calculate-schedule`

#### Request Body

| Name                                           | Type   | Description                                                                                                                                                                                             |
| ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| username<mark style="color:red;">\*</mark>     | String | Host's username from profile                                                                                                                                                                            |
| meetingTopic<mark style="color:red;">\*</mark> | String | Meeting topic's uuid                                                                                                                                                                                    |
| timezone<mark style="color:red;">\*</mark>     | String | Participant's  timezone                                                                                                                                                                                 |
| offset<mark style="color:red;">\*</mark>       | Number | <p>Number of days added to the current date to determine the first date in the schedule. Must be a multiple of 7</p><p></p><p>Minimum: 0</p><p></p><p>It's ignored when month is defined.</p>           |
| month                                          | Number | <p>Number of the month. The first month is January of the current year. For example, the value 5 means May of this year. The value 14 means February of the following year.</p><p></p><p>Minimum: 1</p> |
| team                                           | String | Team's uuid. Required if it is meeting topic for the team                                                                                                                                               |
| year                                           | Number | The year for which we retrieve available dates                                                                                                                                                          |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "schedule": {
         "2024-01-01": [
              {
                   "day": "2024-01-01",
                   "start": "2024-01-01T13:00:00+00:00",
                   "end": "2024-01-01T13:40:00+00:00",
                   "timezone": "Europe/Warsaw",
                   "user": {
                        "username": "joe-smith"
                   }
              },
              {
                   "day": "2024-01-01",
                   "start": "2024-01-01T13:40:00+00:00",
                   "end": "2024-01-01T14:20:00+00:00",
                   "timezone": "Europe/Warsaw",
                   "user": {
                        "username": "joe-smith"
                   }
              }
         ],
         "2024-01-02": [
              {
                   "day": "2024-01-02",
                   "start": "2024-01-02T13:00:00+00:00",
                   "end": "2024-01-02T13:40:00+00:00",
                   "timezone": "Europe/Warsaw",
                   "user": {
                        "username": "joe-smith"
                   }
              },
              {
                   "day": "2024-01-02",
                   "start": "2024-01-02T13:40:00+00:00",
                   "end": "2024-01-02T14:20:00+00:00",
                   "timezone": "Europe/Warsaw",
                   "user": {
                        "username": "joe-smith"
                   }
              }
         ],
         ...
    }
}
```

{% endtab %}
{% endtabs %}