Timekit developers

POST Create a booking

Use this endpoint to create a booking.

Please refer to our tutorial on creating a booking for a more detailed description: http://help.timekit.io/working-with-the-api/bookings/creating-a-booking

If you need an introduction the the booking concept as Timekit sees it, please refer to our introduction: http://help.timekit.io/working-with-the-api/bookings/introduction-to-bookings

Settings

Use the settings for additional settings. Currently we support these additional settings:

  • allow_double_bookings which defaults to false. If you want bookings to allow overlapping you can set this to true

How to allow double bookings

json
{
  "resource_id": "d187d6e0-d6cb-409a-ae60-45a8fd0ec879",
  "graph": "confirm_decline",
  "start": "2018-08-12T21:30:00-07:00",
  "end": "2018-08-12T22:15:00-07:00",
  "what": "Catch the lightning",
  "where": "Courthouse, Hill Valley, CA 95420, USA",
  "description": "The lightning strikes at 10:04 PM exactly! I need you to be there Doc!",
  "customer": {
    "name": "Marty McFly",
    "email": "marty.mcfly@timekit.io",
    "phone": "(916) 555-4385",
    "voip": "McFly",
    "timezone": "America/Los_Angeles"
  },
  "settings": {
    "allow_double_bookings": true
  }
}

Endpoint

POST https://api.timekit.io/v2/bookings

Parameters

Name In Type Required Default Description
include query string Comma-separated dynamic includes, for example attributes,calendar,customers,available_actions. Without it, only the basic booking fields are returned.
project_id body string If you want to use the settings specified in the project. Any additional parameters in the request will override those set in the project
resource_id body string yes The ID of the resource being booked
graph body string yes Name of the flow graph you want to use. Please refer to our graph reference https://developers.timekit.io/reference/graphs
customer body object yes Customer info (depending on the chosen graph!) the customer is the person booking the resource. Only customer.name is required; email, phone, voip and timezone are optional, and timezone defaults to the resource's timezone.
start body timestamp yes When the booking starts. Must not be in the past.
end body timestamp yes When the booking ends
what body string yes The title of the booking
where body string yes A description of the location of the booking
description body string a description of the booking
invite body boolean false Send provider invitation emails when using google/microsoft. False by default. See details in note below.
participants body array_string [] A list of emails to invite as participants (when using google/microsoft). See details in note below.
my_rsvp body string accepted Set your own RSVP when using google/microsoft. See details in note below.
calendar_id body string If you need to save the booking in a different calendar than the resource's primary, you need to supply this
settings body object Additional settings. See below
meta body object Key-values of additional custom meta-data that you want to save.
reservation_id body string If you have reserved a time slot earlier using reservation endpoint add your reservation id here to create booking from your reserved slot

Request examples

The example asks for attributes, calendar, customers and available_actions with the include query parameter, so they appear in the response. Without include, the response only has the basic booking fields.

curl
curl --request POST \
  --header 'Content-Type: application/json' \
  --url 'https://api.timekit.io/v2/bookings?include=attributes,calendar,customers,available_actions' \
  --user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7 \
  --data '{
  "resource_id": "d187d6e0-d6cb-409a-ae60-45a8fd0ec879",
  "graph": "confirm_decline",
  "start": "2018-08-12T21:30:00-07:00",
  "end": "2018-08-12T22:15:00-07:00",
  "what": "Catch the lightning",
  "where": "Courthouse, Hill Valley, CA 95420, USA",
  "description": "The lightning strikes at 10:04 PM exactly! I need you to be there Doc!",
  "meta":{
    "latitude":"34.1381168",
    "longitude":"-118.3533783"
  },
  "customer": {
    "name": "Marty McFly",
    "email": "marty.mcfly@timekit.io",
    "phone": "(916) 555-4385",
    "voip": "McFly",
    "timezone": "America/Los_Angeles"
  }
}'

Response examples

201

json
{
  "data": {
    "id": "58190fc6-1ec0-4ebb-b627-7ce6aa9fc703",
    "graph": "confirm_decline",
    "state": "tentative",
    "completed": false,
    "created_at": "2018-02-11T11:58:45+0100",
    "updated_at": "2018-02-11T11:58:47+0100",
    "available_actions": [
      "decline",
      "confirm"
    ],
    "attributes": {
      "event_info": {
        "start": "2018-08-12T21:30:00-07:00",
        "end": "2018-08-12T22:15:00-07:00",
        "what": "Catch the lightning",
        "where": "Courthouse, Hill Valley, CA 95420, USA",
        "description": "The lightning strikes at 10:04 PM exactly! I need you to be there Doc!"
      }
    },
    "calendar": {
      "id": "bfa0b9fa-36aa-4ae6-8096-f3b20fbed1d2",
      "name": "Important encounters with Marty",
      "display_name": "Important encounters with Marty",
      "description": "Througout time, Marty and I really need to meet in order for the world not to collapse into Biffy cazyness.",
      "foregroundcolor": "#000000",
      "backgroundcolor": "#FFFFFF",
      "created_at": "2016-02-15T13:21:42+0100",
      "updated_at": "2016-02-15T13:21:42+0100"
    },
    "customers": [
      {
        "id": "a728e860-99c7-4009-8843-7d9ac5d7f53f",
        "name": "Marty McFly",
        "email": "marty.mcfly@timekit.io",
        "phone": "(916) 555-4385",
        "voip": "McFly",
        "timezone": "America/Los_Angeles"
      }
    ]
  }
}
Last edited 6 October 2026.