POST Create a project

Create a new project.

Projects are meant to be used togehter with our fetch availability endpoint and the create bookings endpoint. It's a way to persistent configurations for these parts of Timekit at our end. Please note that you can always override the project settings in the request to the booking and availability endpoints.

Let's take a look at the properties you can set and what they do in 1-to-1 projects:

Availability

resources is a list of resource IDs that make your defined resources available for booking within specific the project. Please see the fetch availability endpoint.

availability contains the top-level parameters that the fetch availability endpoint takes. The accepted keys are mode (required), length, from, to, buffer, timeslot_increments and ignore_all_day_events. to can be at most 6 months into the future.

availability_constraints are you project-level availability constraints which are applied in addition to resource-level constraints defined directly on your resources. Please see the fetch availability endpoint.

Clarification: Please note that { "block_period": { "start": "2022-05-01", "end": "2022-05-06" } } means 2022-05-01T00:00:00 (midnight of May 1st) to 2022-05-06T00:00:00 (midnight of May 6th). This means that May 6th at 00:01 and everything afterwards are not counted in the block. If you want to block off all of May 6th, you'd use { "block_period": { "start": "2022-05-01", "end": "2022-05-07" } } as this is midnight of May 7th.

Booking

booking contains the top-level parameters that the create booking endpoint takes. The accepted keys are graph, what and where (all required), and description, rescheduling_url and min_cancel_time.

Please note that if you want to make a project that offers group bookings (classes etc.) you need to create the group_owner classes before they will be visible through the project. The project setting under booking.graph should likewise be set to group_customer because this is the kind of bookings that will end up being created through the project.

reminders are reminders (aka. "event notifications"), which are documented in depth here.

Presentation

customer_fields specifies which inputs you want your customers to fill out when making a booking. If you send customer_fields, it must include both name and email. If you use our booking.js widget, the fields you declare are rendered on the form screen. Please see the booking.js docs for a full reference.

ui are miscellaneous UI specific settings that are meant to instruct how the booking flow for your customers should behave. Our booking.js v2 widget uses these when embedded on your own web page or on our hosted URL. If you're building your own UI, you can use these as hints on how to render to your component, although it's completely optional.

Attach meta data to projects

meta is extra data you can attach to the project, stored as key-value pairs. This could be an external_id from your own system or maybe the address of the store the project represents. This data will be searchable via /projects endpoint, see: https://developers.timekit.io/v2/reference#projects

Endpoint

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

Parameters

Request examples

curl
curl --request POST \
  --url https://api.timekit.io/v2/projects \
  --header 'Content-Type: application/json' \
  --user :test_api_key_nvHfRSlhvsnlg4rS7Wt28Ty47qdgegwSu3YK7hPW \
  --data '{
  "name": "My Test Project",
  "slug": "my-test-project",
  "allow_conference": "1",
  "resources": [
    "d187d6e0-d6cb-409a-ae60-45a8fd0ec879",
    "a728e860-99c7-4009-8843-7d9ac5d7f53f"
  ],
  "availability": {
    "mode": "roundrobin_random",
    "length": "15 minutes",
    "from": "1 hour",
    "to": "4 weeks",
    "buffer": "15 minutes",
    "ignore_all_day_events": false
  },
  "availability_constraints": [
    { "allow_day_and_time": { "day": "monday", "start": "1:00", "end": "10:30" } },
    { "allow_day_and_time": { "day": "tuesday", "start": "1:00", "end": "14:30" } },
    { "block_period": { "start": "2022-05-01", "end": "2022-05-06" } }
  ],
  "booking": {
    "graph": "instant",
    "what": "Test Bookings",
    "where": "TBA",
    "description": "The lightning strikes at 10:04 PM exactly!"
  },
  "reminders": [
    {
      "settings": { "recipient": "owner", "subject": "Time for take-off!"},
      "type":"email",
      "when": {"type": "before", "unit": "mins", "time": "15"}
    }
  ],
  "customer_fields": {
    "name": {
      "title": "Name",
      "prefilled": "",
      "readonly": false
    },
    "email": {
      "title": "E-mail",
      "prefilled": "",
      "readonly": false
    },
    "comment": {
      "title": "Comment",
      "required": true,
      "prefilled": "",
      "readonly": false
    }
  },
  "ui": {
    "display_name": "Martys Timetravel Service",
    "avatar": "",
    "availability_view": "agendaWeek",
    "show_credits": true,
    "time_date_format": "12h-mdy-sun",
    "localization": {
      "allocated_resource_prefix": "with",
      "submit_button": "Book it",
      "success_message": "Thanks for booking!"
    }
  },
  "meta": {
  	"external_id": 11223344,
    "store_location": "9303 Lyon Drive, Lyon Estates, Hill Valley CA 95420"
  }
}'

Response examples

201

The response does not list the project's resources. Add ?include=resources to the request URL to get them as an array of resource objects under resources.

json
{
  "data": {
    "id": "826ddc8e-8698-45be-9320-0c81dcf797d9",
    "name": "My Test Project",
    "slug": "my-test-project",
    "latitude": null,
    "longitude": null,
    "use_hours_from": null,
    "distance": 0,
    "ui": {
      "availability_view": "agendaWeek",
      "show_credits": true,
      "time_date_format": "12h-mdy-sun",
      "localization": {
        "allocated_resource_prefix": "with",
        "submit_button": "Book it",
        "success_message": "Thanks for booking!"
      },
      "display_name": "Martys Timetravel Service",
      "avatar": ""
    },
    "availability_constraints": [
      { "allow_day_and_time": { "day": "monday", "start": "1:00", "end": "10:30" } },
      { "allow_day_and_time": { "day": "tuesday", "start": "1:00", "end": "14:30" } },
      { "block_period": { "start": "2022-05-01", "end": "2022-05-06" } }
    ],
    "reminders": [
      {
        "settings": { "recipient": "owner", "subject": "Time for take-off!"},
        "type":"email",
        "when": {"type": "before", "unit": "mins", "time": "15"}
      }
    ],
    "customer_fields": {
      "name": {
        "title": "Name",
        "required": true,
        "prefilled": "",
        "readonly": false,
        "format": "text"
      },
      "email": {
        "title": "E-mail",
        "required": true,
        "prefilled": "",
        "readonly": false,
        "format": "email"
      },
      "comment": {
        "title": "Comment",
        "required": true,
        "prefilled": "",
        "readonly": false
      }
    },
    "allow_conference": "1",
    "reservation_time": null,
    "allow_double_bookings": false,
    "enabled_email_notification": false,
    "availability": {
      "length": "15 minutes",
      "from": "1 hour",
      "to": "4 weeks",
      "buffer": "15 minutes",
      "ignore_all_day_events": false,
      "mode": "roundrobin_random"
    },
    "booking": {
      "graph": "instant",
      "what": "Test Bookings",
      "where": "TBA",
      "description": "The lightning strikes at 10:04 PM exactly!",
      "rescheduling_url": "https://book.timekit.io/my-test-project"
    },
    "meta": {
      "external_id": 11223344,
      "store_location": "9303 Lyon Drive, Lyon Estates, Hill Valley CA 95420"
    },
    "created_at": "2022-01-18T20:09:30+0000",
    "updated_at": "2022-01-18T20:09:30+0000"
  }
}