Guide: Schedule a meeting

Let's take the API for a spin in this 10-15 minute walkthrough

For this exercise, we're going to use the API as a backend for a Doodle-like scheduling app. Imagine a scenario where users can create meetings, invite others to vote on possible dates and decide on a time. The purpose is to showcase how Timekit can handle user authentication, meeting creation, suggestions and voting in a few simple steps.

Build solutions like:

Doodle scheduling
Timebird calendar overlays
AI-based scheduling assistants
Recruitment interview planner

Here's what we're going to go through:

Authenticate as a user
Create a new meeting with suggested timeslots
Have another user vote on a suggestion
Decide on a suggested time by creating a final event invitation

Let's get to it!

1. Authenticate as a user

We're going to assume that we already have created a user and possibly synced to a Google Calendar (you dont need to actually do this for now). So our first task is to obtain a user specific api_token so we can make subsequent API calls for that user. This would usually happen through a login form where the user, in this case Doc Brown, is asked for email and password and the request is sent to our API - we'll imitate this behaviour like so:

curl# Request example
curl -X POST \
     -H 'Timekit-App: docs' \
     -d '{
           "email": "doc.brown:::at:::timekit.io",
           "password": "DeLorean"
         }' \
     https://api.timekit.io/v2/auth

This will return our user object:

json// Result example
{
  "data": {
    "first_name": "Dr. Emmett",
    "last_name": "Brown",
    "name": "Dr. Emmett Brown",
    "email": "doc.brown@timekit.io",
    "img": "http:\/\/www.gravatar.com\/avatar\/7a613e5348d6347627693502580f5aad",
    "activated": true,
    "timezone": "America\/Los_Angeles",
    "token": "UZpl3v3PTP1PRwqIrU0DSVpbJkNKl5gN",
    "last_sync": null,
    "token_generated_at": null,
    "api_token": "FluxCapacitator"
  }
}

Notice the api_token - thats the one we're going to use in subsequent calls (usually you would save it in a session or something similar).

2. Create a new meeting with suggested timeslots

Great, now let's create a new meeting. This works as "container" for suggested timeslots and also contains information about what the meeting is about, where it is and its status (pending, completed etc.)

Our newly obtained api_token is what we use in the Basic Authentication header (email:api_token).

curl# Request example
curl -X POST \
     -H 'Timekit-App: docs' \
     -u doc.brown@timekit.io:FluxCapacitator \
     -d '{
           "what": "Travel back to the future",
           "where": "Hill Valley Clock Tower",
           "suggestions": [
             {
             	 "start": "1955-11-06T18:30:00.000Z",
               "end": "1955-11-06T19:00:00.000Z"
             },
             {
             	 "start": "1955-11-12T22:04:00.000Z",
               "end": "1955-11-12T22:34:00.000Z"
             },
             {
             	 "start": "1955-11-18T09:15:00.000Z",
               "end": "1955-11-18T09:45:00.000Z"
             }
           ]
         }' \
     https://api.timekit.io/v2/meetings

And that should leave us with a newly created meeting object including suggestions, looking something like this:

json// Result example (id and token will differ)
{
  "data": {
    "id": 4, // example
    "what": "Travel back to the future",
    "where": "Hill Valley Clock Tower",
    "token": "PuicNx37V2pY", // example
    "completed": false,
    "status_text": "PENDING",
    "status_code": 300,
    "start": null,
    "end": null,
    "suggestions": [{
      "id": 2, // example
      "start": "1955-11-06 18:30:00",
      "end": "1955-11-06 19:00:00"
    }, {
      "id": 3, // example
      "start": "1955-11-12 22:04:00",
      "end": "1955-11-12 22:34:00"
    }, {
      "id": 4, // example
      "start": "1955-11-18 09:15:00",
      "end": "1955-11-18 09:45:00"
    }]
  }
}

3. Have another user vote on a suggestion

Fantastic, now lets pretend that we have another user, Marty, that is sent an invitation to vote on his preferable timeslot. For this, he will need to know the token of the meeting and the suggestion IDs as returned earlier.

We're gonna cheat a bit and assume that we authenticated already and received our api_token. So, with that in mind, let's have Marty vote on the second suggestion (the one with the start timestamp 1955-11-12 22:04:00 (lightning strikes!)):

curl# Request example (replace suggestion_id)
curl -X POST \
     -H 'Timekit-App: docs' \
     -u marty.mcfly@timekit.io:DarthVader \
     -d '{
           "suggestion_id": 3,
           "available": 1
         }' \
     https://api.timekit.io/v2/meetings/availability

And if we get a 204 No Content back, our request was successful. This will also trigger an email notification to the meeting organizer, doc.brown@timekit.io, telling him that Marty just voted on a suggestion.

4. Decide on a suggested time by creating a final event invitation

In a real life scenario, Doc Brown would probably invite a few more and wait for their reply, but we're going to skip that and have the Doc decide on a time. We'll call the book method to confirm the suggestion and have Timekit send out the final meeting invitations:

curl# Request example (replace suggestion_id)
curl -X POST \
     -H 'Timekit-App: timebird' \
     -u doc.brown@timekit.io:FluxCapacitator \
     -d '{
           "suggestion_id": 3
         }' \
     https://api.timekit.io/v2/meetings/book

Et voila! There we go - we created a meeting, had a user vote on a suggestion and send out the meeting invitation. Good job, Doc.