NAV

API Overview

Welcome to the GReminders API.

GReminders API is currently in BETA. We have developed some API endpoints and Webhooks functionality. We are looking to work with customers who have special use cases they want to enable.

For access or details please contact [email protected]

Webhooks Overview

Webhooks allow developers to trigger actions off things that happen in GReminders. Webhooks are triggered for New Bookings, Reschedules, Cancellations and Event Confirmations. This guide introduces how webhooks work, including how to configure a webhook for your app and manage webhooks.

Any breaking changes made to the API will result in a new version of the Webhook API. Currently we are on version 1.

Concepts

Webhook: A single event message. GReminders sends a webhook to an Webhook receiving endpoint URL. A webhook contains a JSON payload in the body, and metadata in the headers.

object_type: type of the object that triggers an webhook event. Could be event, event_type and user

change_type: This reflects the type of callback you're receiving. Could be created, updated or deleted. Also, you may encounter url_verification during the configuration process.

Webhook subscription: A persisted data object, which defines the object_type and the change_type that the app wants to receive.

A webhook receiving endpoint URL is where GReminders sends webhooks for the specified object_type and change_type.

Payload

Webhook payload structure:

{
    "object_type": "event",
    "change_type": "created"
    "data": {
        ...
    }
}

Each webhook sent by GReminders has the same structure

Parameter Description
object_type string Type of the object that triggers an webhook event
change_type string Change Type of callback (created, updated, etc...)
data one of Api Object data representing object

Headers

In addition to the message payload, each webhook message has a predefined set of HTTP headers containing metadata.

HTTP Header Use
X-Greminders-Api-Version Version of the Webhook API
X-Greminders-Request-Timestamp UNIX Timestamp of the request
X-Greminders-Signature Used for verification of the request
X-Greminders-Retry-Num Indicates the delivery retry attempt number: 1, 2, or 3.
X-Greminders-Retry-Reason Describes why the request was retried

Delivery Retries

GReminders will try to deliver a failed request up to 3 times in a gradually increasing timetable. We'll tell you why we're retrying the request in the X-Greminders-Retry-Reason HTTP header. Possible values are:

Working with Webhooks

Webhook Subscription

To create webhook subscription follow next steps:

Verification of Receiving Endpoint URL

We'll dispatch a HTTP POST containing following body to your request URL:

{
    "change_type": "url_verification",
    "verification_key": "85cfdbc3dab3d0124aad1158b90b9fa745a1a00a4d15eea85f7d8db2ffc81400"
}

To ensure that webhooks are being delivered to a server under your control, GReminders must verify your ownership by sending you a url_verification request. You'll automatically receive url_verification request whenever configuring an Webhook Receiving Endpoint URL.

Once you receive the url_verification request, verify it and then respond in plaintext with the verification_key attribute value:

HTTP 200 OK
85cfdbc3dab3d0124aad1158b90b9fa745a1a00a4d15eea85f7d8db2ffc81400

Receive the Webhook

After you register an endpoint, GReminders sends an HTTP POST request to the URL specified every time that event occurs. The HTTP POST request's parameters contain the JSON data relevant to the event that triggered the request.

Verify the Webhook (Optional)

The following example uses pseudocode to verify a webhook request:


function verifyRequest(): bool {
    $request = getRequest();

    $signing_secret   = 'your signing sexret generated by GReminders';
    $requestSignature = $request->headers('X-Greminders-Signature');
    $timestamp        = $request->headers('X-Greminders-Request-Timestamp');
    $payload          = $request->getBody();

    $calculatedSignature = $hash_hmac('sha256', "$timestamp:$body", $signing_secret);

    return $requestSignature === $calculatedSignature;
}

Before you respond to a webhook, you need to verify that the webhook was sent from GReminders. You can verify the webhook by calculating a digital signature and comparing it to the value of the X-Greminders-Signature HTTP header.

Respond to the webhook

Your webhook acknowledges that it received data by sending a 200 OK response.

API Objects

Event

Example:

{
  "id": "2142ba19-64a3-4109-9e60-64f47d9bcb49",
  "external_id": "26jkvg7t3sp1ugmkd72tih91hk",
  "user_id": "d287cc96-ff37-4c47-b703-5309a7171ea1",
  "calendar_id": "87e5e15e-cdc8-467e-a256-ae6aada02a54",
  "event_type_id": "6474fc7c-2023-48c7-9d35-52451a34cacf",
  "url": "https://app.greminders.com/event/2142ba19-64a3-4109-9e60-64f47d9bcb49",
  "weburl": "https://www.google.com/calendar/event?eid=MjZqa3ZnN3Qzc3AxdWdta2Q3MnRpaDkxaGsgbG9wYXRpbnNreXN2LnNkYWlAbQ",
  "reschedule_url": "https://www.greminders.com/r/TDL7xW",
  "cancel_url": "https://www.greminders.com/c/TDL7xW",
  "location": "https://meet.google.com/utd-yois-fsp",
  "body": "Review Value Proposition of ACME",
  "name": "Demo Meeting with ACME Inc",
  "status": "confirmed",
  "freebusy": "busy",
  "provider": "google",
  "timezone": "America/Los_Angeles",
  "categories": [],
  "origination_date": "2022-07-07T02:16:35-07:00",
  "start_date": "2022-07-07T23:30:00-07:00",
  "end_date": "2022-07-08T00:00:00-07:00",
  "created_date": "2022-07-07T02:16:35-07:00",
  "updated_date": "2022-07-07T09:16:57+00:00",
  "is_organizer": true,
  "reply_status": null,
  "all_day_event": false,
  "client_timezone": "America/Los_Angeles",
  "meeting_urls": [
    {
      "url": "https://meet.google.com/utd-yois-fsp",
      "provider": "google_meet"
    }
  ],
  "registrants": [
    {
      "role": "participant",
      "email": "[email protected]",
      "phone": null,
      "status": "registered",
      "internal": false,
      "timezone": "America/Los_Angeles",
      "last_name": "Person",
      "questions": [
        {
          "key": "f52105e8-94dd-4c11-9666-b1a42e72970d",
          "label": "sample question",
          "value": "sample answer"
        }
      ],
      "cancel_url": "https://www.greminders.com/c/BgIzRz",
      "first_name": "Another",
      "confirm_url": "https://www.greminders.com/f/BgIzRz",
      "created_date": "2022-07-07T02:49:06-07:00",
      "source_email": "eventregistration",
      "source_phone": null,
      "updated_date": "2022-07-07T02:50:21-07:00",
      "external_role": "recipient",
      "reschedule_url": "https://www.greminders.com/r/BgIzRz"
    }
  ],
  "participants": [
    {
      "role": "participant",
      "email": "[email protected]",
      "phone": null,
      "status": "registered",
      "internal": false,
      "timezone": "America/Los_Angeles",
      "last_name": "Person",
      "questions": [],
      "cancel_url": "https://www.greminders.com/c/BgIzRz",
      "first_name": "Another",
      "confirm_url": "https://www.greminders.com/f/BgIzRz",
      "created_date": "2022-07-07T02:49:06-07:00",
      "source_email": "eventregistration",
      "source_phone": null,
      "updated_date": "2022-07-07T02:50:21-07:00",
      "external_role": "recipient",
      "reschedule_url": "https://www.greminders.com/r/BgIzRz"
    },
    {
      "role": "organizer",
      "email": "[email protected]",
      "phone": null,
      "status": "registered",
      "internal": true,
      "timezone": "America/Los_Angeles",
      "last_name": "Person",
      "questions": [],
      "cancel_url": "https://www.greminders.com/c/BgIzRz",
      "first_name": "Some",
      "confirm_url": "https://www.greminders.com/f/BgIzRz",
      "created_date": "2022-07-07T02:49:06-07:00",
      "source_email": null,
      "source_phone": "user",
      "updated_date": "2022-07-07T02:49:06-07:00",
      "external_role": "sender",
      "reschedule_url": "https://www.greminders.com/r/BgIzRz"
    }
  ],
}
Parameter Description
id uuid Internal ID
external_id string ID of the External Event (from Google, Microsoft, etc...) Could be used to match up the Event against the Source Provider.
user_id uuid Internal User ID
calendar_id uuid Internal Calendar ID
event_type_id uuid Internal Event Type ID
url string GReminders Web UI URL
weburl string External Event Provider URL (Link to the Google, Microsoft, etc... Event)
reschedule_url string Public URL to be used for client rescheduling
cancel_url string Public URL to be used for client cancellations
location string Location of the Event
body string Description of the Event
name string Title/Subject of the Event
status string Status of the Source Event (confirmed, tentative, cancelled) If event is "cancelled" it has been deleted from the source calendar
freebusy string "free" or "busy", if busy the event is not considered as part of the availability check
provider string Source Provider of the Event (google, microsoft, etc...)
timezone string Time Zone of Event in IANA Time Zone format
client_timezone string Client Time Zone of Event in IANA Time Zone format See Article
reply_status string Internal Reply State (confirmed,rescheduling,optout,cancelled) GReminders Event Status. Result of client replies to notifications.
is_organizer bool This user is the Organizer of this Meeting
all_day_event bool This event is an all day event
categories array Categories of this Event from Source Event/Calendar (only applies to Office 365 / Exchange Calendar Events)
origination_date date Original Date the Event was created on the Source Calendar, ISO8601 format
start_date date Start Date & Time of the Event, ISO8601 format
end_date date End Date & Time of the Event, ISO8601 format
created_date date Date & Time Event was created in GReminders, ISO8601 format
updated_date date Date & Time Event was last updated in GReminders, ISO8601 format
meeting_urls array of Meeting Url
participants array of Registrant List of People that are ON the Event Invitation List.
registrants Registrant List of People who Registered for the Event via GReminders. In most cases this is one registrant, for Group Events this may contain more than one registrant.

Event type

Example:

{
  "id": "6474fc7c-2023-48c7-9d35-52451a34cacf",
  "url": "https://app.greminders.com/c/someperson/demomeeting",
  "name": "Demo Meeting",
  "type": "single",
  "active": true,
  "team_id": null,
  "user_id": "d287cc96-ff37-4c47-b703-5309a7171ea1",
  "location": "",
  "shortname": "demomeeting",
  "show_home": true,
  "calendar_id": null,
  "description": "",
  "availability": {
    "advanced_availability": false,
    "default_availability_end": "17:00:00",
    "default_availability_start": "09:00:00",
    "availability_observe_holidays": true
  },
  "created_date": "2022-07-07T08:56:22+00:00",
  "updated_date": "2022-07-07T08:56:22+00:00",
  "location_type": "google_meet",
  "event_duration_max": null,
  "event_duration_min": null,
  "event_duration_type": "fixed",
  "max_events_per_slot": null,
  "can_schedule_from_date": null,
  "can_schedule_until_date": null,
  "can_schedule_within_days": 60,
  "event_duration_in_minutes": 30,
  "prevent_events_scheduled_hours": 2,
  "add_customer_to_calendar_invite": true
}
Parameter Description
id uuid Internal ID
active bool Active Flag
user_id uuid Internal User ID
team_id uuid Internal Team ID
url string Public Scheduling Link for this Event Type
shortname string Shortname of the User or Team (used in the url above)
type string
calendar_id uuid Internal Calendar ID the Event will be booked on (if NULL then the Primary Calendar is used)
name string Title of the Event Type
description string Description of the Event Type
location string Location of the Event Type
location_type string If Location is "custom" this is the location of the Event Type
event_duration_in_minutes int Event Type Duration in Minutes
can_schedule_within_days int Event can be scheduled within X Days
prevent_events_scheduled_hours int Prevent Events being scheduled less than X hours from now
show_home bool Will the Event Type show on the main Booking Screen
event_duration_type string Event Type Duration Type (fixed, variable)
event_duration_min int if Event Type Duration Type = fixed, this is the min time duration for the event in minutes
event_duration_max int if Event Type Duration Type = fixed, this is the max time duration for the event in minutes
max_events_per_slot int Max # of Events per Time Slot (Overlapping Bookings), default null
can_schedule_from_date date Can schedule between this Start Date, ISO8601 format
can_schedule_until_date date Can schedule between this End Date, ISO8601 format
add_customer_to_calendar_invite bool Are we adding the client to the participant list (onto the Event Invitation)
availability Availability Availability Settings of the Event Type
created_date date Date & Time Event Type was originally created, ISO8601 format
updated_date date Date & Time Event Type was last modified, ISO8601 format

User

Example:

{
  "id": "d287cc96-ff37-4c47-b703-5309a7171ea1",
  "url": "https://app.greminders.com/c/someperson",
  "email": "[email protected]",
  "title": "",
  "active": true,
  "language": "en",
  "timezone": "America/Los_Angeles",
  "shortname": "someperson",
  "country_code": "US",
  "created_date": "2022-06-13T10:58:45-07:00",
  "mobile_phone": "19495556666",
  "updated_date": "2022-07-07T09:05:23+00:00",
  "email_verified": false
}
Parameter Description
"id" uuid Internal ID
"url" string Public Scheduling Link for this User
"email" string Email
"title" string Job Title
"active" bool Is user Active?
"language" string Default Language
"timezone" string Time Zone of User in IANA Time Zone format
"shortname" string Shortname for User
"country_code" string ISO 3166-1 2 character Country Code
"created_date" date Date & Time User was originally created, ISO8601 format
"mobile_phone" string Mobile Number in E.164 format
"updated_date" date Date & Time User was last modified, ISO8601 format
"email_verified" bool Has this email address been verified?

Registrant

Example:

{
  "first_name": "Some",
  "last_name": "Person",
  "email": "[email protected]",
  "phone": null,
  "role": "organizer",
  "external_role": "required",
  "status": "registered",
  "internal": true,
  "timezone": "America/Los_Angeles",
  "confirm_url": "https://www.greminders.com/f/TDL7xW",
  "reschedule_url": "https://www.greminders.com/r/TDL7xW",
  "cancel_url": "https://www.greminders.com/c/TDL7xW",
  "questions": [
    {
      "key": "f52105e8-94dd-4c11-9666-b1a42e72970d",
      "label": "sample question",
      "value": "sample answer"
    }
  ],
  "source_email": "eventregistration",
  "source_phone": "user",
  "created_date": "2022-07-07T02:16:39-07:00",
  "updated_date": "2022-07-07T02:16:39-07:00",
}
Parameter Description
first_name string First Name
last_name string Last Name
email string Email
phone string Phone Number in E.164 Format
role string Internal Role (organizer
external_role string Role as defined by the External Calendar Event (sender,recipient,required,optional)
status string Internal Status (registered,pending,confirmed,cancelled)
internal bool Is this an Internal User (GReminders calculated)
timezone string Time Zone of Registrant in IANA Time Zone format
confirm_url string Public Confirmation URL
reschedule_url string Public Reschedule URL
cancel_url string Cancellation URL
questions array of Question Custom Questions/Answers
source_email string Source of the Email (where the email address was first found)
source_phone string Source of the Phone Number (where the phone number was first found)
created_date date Date & Time User was created, ISO8601 format
updated_date date Date & Time User was last modified, ISO8601 format

Meeting Url

Example:

{
  "provider": "google_meet",
  "url": "http://meetingurl"

}
Parameter Description
provider string Provider Name (zoom, google_meet, etc...)
url string URL of the Web Meeting

Availability

Example:

{
  "advanced_availability": false,
  "default_availability_start": "09:00:00",
  "default_availability_end": "17:00:00",
  "availability_observe_holidays": true
}
Parameter Description
advanced_availability bool Is advanced availability enabled?
default_availability_start time Availability Start Time
default_availability_end time Availability End Time
availability_observe_holidays bool Does Event Type observer Holidays

Question

Example:

{
  "key": "f52105e8-94dd-4c11-9666-b1a42e72970d",
  "label": "What is your favorite Color?",
  "value": "Green"
}
Parameter Description
key string Question Key
label string Question Label, the actual Question
value string The Registrants Answer