# Introduction

The Datelist API allows you to build external systems that programmatically communicate with the [Datelist.io application](https://datelist.io). 

This guide contains the REST interface to interact with the Datelist API. \
For a specific integration with your language, you can also check our SDK: 

* **For Python**: <https://pypi.org/project/datelist-sdk-python/>
* **For Ruby**: <https://rubygems.org/gems/datelist>
* **For Javascript**: <https://www.npmjs.com/package/datelist-sdk-js>


# Authentication & API structure

Datelist API is a standard HTTP based JSON API that follows a conventional structure.&#x20;

## Authentication&#x20;

Each request must be authenticated with an API key, which you can get in your user profile in the Datelist.io application (<https://datelist.io/users/edit>) .

To use it in your HTTP calls, you must emit each of your request using a custom "Authorization" endpoint, which follows this format:&#x20;

**`Authorization: Bearer API_TOKEN`**&#x20;

## API Structure

Once authenticated, Datelist API will answer your requests using HTTP payload in JSON format. Standard HTTP status code is used to indicate the success or the failure of each request.&#x20;

To be sure to get data in the correct format, be sure to append the following headers:&#x20;

**`Accept: application/json`** \
**`Content-Type: application/json`**


# Calendars

The calendar endpoint allows you to list the available calendars. It currently only allows one HTTP method.

## /api/calendars

<mark style="color:blue;">`GET`</mark> `https://dalelist.io/api/calendars`

List the available calendars

#### Headers

| Name           | Type   | Description                                                |
| -------------- | ------ | ---------------------------------------------------------- |
| Authentication | string | Authentication token to (see the "Authentication" section) |

{% tabs %}
{% tab title="200 Returns the requested calendars" %}

```
[
  {    
    "id": 123456, 
    "name": "MyCalendar",    
  }, 
  {...}
]
```

{% endtab %}
{% endtabs %}


# Products

## /api/products

<mark style="color:blue;">`GET`</mark> `https://datelist.io/api/products`

This endpoint allows listing the available products.&#x20;

#### Query Parameters

| Name         | Type   | Description                                  |
| ------------ | ------ | -------------------------------------------- |
| name         | string | Search for products matching a specific name |
| calendar\_id | number | Search for products on a specific calendar   |

#### Headers

| Name           | Type   | Description                                             |
| -------------- | ------ | ------------------------------------------------------- |
| Authentication | string | Authentication token (see the "authentication" section) |

{% tabs %}
{% tab title="200 Returns the requested products" %}

```
[
    {
        "id": 1234,
        "name": "Your product",
        "price": null,
        "places": 1,
        "duration": 60,
        "calendar_id": 73,
        "created_at": "2021-06-15T12:31:25.652Z",
        "updated_at": "2021-06-15T13:00:04.757Z",
        "description": "",
        "deleted_at": null,
        "active": true,
        "tax_amount": null
    },
    {...}
]
```

{% endtab %}
{% endtabs %}


# Booked slots

## /api/booked\_slots

<mark style="color:blue;">`GET`</mark> `https://datelist.io/api/booked_slots`

This endpoint allows you to list the booked slots.&#x20;

#### Query Parameters

| Name         | Type    | Description                                                          |
| ------------ | ------- | -------------------------------------------------------------------- |
| email        | string  | Only get booked slots matching a specific email                      |
| calendar\_id | string  | Only get booked slots for a specific calendar                        |
| from         | string  | Get booked slots starting from a specified date (in iso 8601 format) |
| to           | boolean | Get booked slots up to a specified date (in iso 8601 format)         |

#### Headers

| Name           | Type   | Description                                             |
| -------------- | ------ | ------------------------------------------------------- |
| Authentication | string | Authentication token (see the "authentication section") |

{% tabs %}
{% tab title="200 Returns the requested slots" %}

```
[
    {
        "id": 2163,
        "calendar_id": 31,
        "start": "2021-07-21T11:00:00.000Z",
        "end": "2021-07-21T11:10:00.000Z",
        "email": "alexis@datelist.io",
        "phone": "123456789",
        "created_at": "2021-07-11T11:04:22.542Z",
        "updated_at": "2021-07-11T11:04:22.542Z",
        "external_id": null,
        "created_from": "booking",
        "email_notification_sent_at": null,
        "phone_notification_sent_at": null,
        "deleted_at": null,
        "first_name": "Alexis",
        "last_name": "Clarembeau",
        "product_id": 63,
        "language": "default",
        "email_notification_really_sent_at": null,
        "phone_notification_really_sent_at": null,
        "custom_field_values": {
            "31": "Custom field value 1"
        },
        "integration_details": null
    },
    {...}
]
```

{% endtab %}
{% endtabs %}

## /api/booked\_slots/:id

<mark style="color:purple;">`PATCH`</mark> `https://datelist.io/api/booked_slots/:id`

Update data of a booked slot

#### Path Parameters

| Name | Type   | Description               |
| ---- | ------ | ------------------------- |
| id   | number | The ID of the booked slot |

#### Headers

| Name           | Type   | Description                                             |
| -------------- | ------ | ------------------------------------------------------- |
| Authentication | string | Authentication token (see the "Authentication" section) |

#### Request Body

| Name | Type   | Description                                                |
| ---- | ------ | ---------------------------------------------------------- |
| Body | string | Data to update (in same format as the GET endpoint result) |

{% tabs %}
{% tab title="200 The updated booked slot" %}

```
{
    "id": 2163,
    "calendar_id": 31,
    "start": "2021-07-21T11:00:00.000Z",
    "end": "2021-07-21T11:10:00.000Z",
    "email": "alexis.clarembeau@gmail.com",
    "phone": "123456789",
    "created_at": "2021-07-11T11:04:22.542Z",
    "updated_at": "2021-07-11T11:04:22.542Z",
    "external_id": null,
    "created_from": "booking",
    "email_notification_sent_at": null,
    "phone_notification_sent_at": null,
    "deleted_at": null,
    "first_name": "Alexis",
    "last_name": "Clarembeau",
    "product_id": 63,
    "language": "default",
    "email_notification_really_sent_at": null,
    "phone_notification_really_sent_at": null,
    "custom_field_values": {
        "31": "Custom field value 1"
    },
    "integration_details": null
}
```

{% endtab %}
{% endtabs %}

## /api/booked\_slots/:id

<mark style="color:red;">`DELETE`</mark> `https://datelist.io/api/booked_slots/:id`

Cancels a booked slot

#### Path Parameters

| Name                                 | Type   | Description               |
| ------------------------------------ | ------ | ------------------------- |
| id<mark style="color:red;">\*</mark> | number | The ID of the booked slot |

#### Query Parameters

| Name                    | Type    | Description |
| ----------------------- | ------- | ----------- |
| send\_email\_on\_delete | boolean |             |

#### Headers

| Name           | Type   | Description                                             |
| -------------- | ------ | ------------------------------------------------------- |
| Authentication | string | Authentication token (see the "Authentication" section) |

{% tabs %}
{% tab title="200 The deleted booked slot" %}

```
{
    "id": 2163,
    "calendar_id": 31,
    "start": "2021-07-21T11:00:00.000Z",
    "end": "2021-07-21T11:10:00.000Z",
    "email": "alexis.clarembeau@gmail.com",
    "phone": "123456789",
    "created_at": "2021-07-11T11:04:22.542Z",
    "updated_at": "2021-07-11T11:04:22.542Z",
    "external_id": null,
    "created_from": "booking",
    "email_notification_sent_at": null,
    "phone_notification_sent_at": null,
    "deleted_at": null,
    "first_name": "Alexis",
    "last_name": "Clarembeau",
    "product_id": 63,
    "language": "default",
    "email_notification_really_sent_at": null,
    "phone_notification_really_sent_at": null,
    "custom_field_values": {
        "31": "Custom field value 1"
    },
    "integration_details": null
}
```

{% endtab %}
{% endtabs %}


# Webhooks

To retrieve the bookings of one of your Datelist calendars, you must tell our application to send you all the new booking events, by "subscribing to a webhook".

## /api/webhooks

<mark style="color:green;">`POST`</mark> `https://datelist.io/api/webhooks`

This endpoint allows you to subscribe to a webhook, to receive the new booking notification.&#x20;

#### Headers

| Name           | Type   | Description                                           |
| -------------- | ------ | ----------------------------------------------------- |
| Authentication | string | Authentication token (see the authentication section) |

#### Request Body

| Name         | Type    | Description                                                                 |
| ------------ | ------- | --------------------------------------------------------------------------- |
| url          | string  | The URL where we should POST information about new bookings.                |
| calendar\_id | integer | The ID of the calendar you would like to watch (see the #calendar endpoint) |

{% tabs %}
{% tab title="200 Webhook successfully created" %}

```
{
  "id": 1234,
  "calendar_id": 12,
  "user_id": 23,
  "url": "https://datelist.io/webhooks/12345",
  "created_at": "2021-06-15T12:31:25.652Z",
  "updated_at": "2021-06-15T12:31:25.652Z",
}

```

{% endtab %}
{% endtabs %}