OnceHub | Developer center

Suggest Edits

Introduction

 

Welcome to the OnceHub API

The OnceHub API is organized around the RESTful architectural style.

Our API is designed to be understood by off-the-shelf HTTP clients through the use of Basic HTTP authentication, built-in HTTP verbs, and built-in HTTP status codes for error responses.

Data Format

The API takes its input through user-provided headers and body parameters.

All API responses, including errors, are returned as JSON objects. Time data is represented in UTC - JSON format.

Note that in order for our API to read the request from the user properly, all requests should have the following header:

Content-type: application/json

Suggest Edits

Authentication

 

Your API key

The API key is available in your OnceHub account, under ScheduleOnce > Setup > Integrations > API Integration. If you don't have an account, you can sign up for a free trial.

Learn more about accessing and managing your API key

Using your API key to authenticate HTTP requests

Authenticate each HTTP request you send by passing your API key in the API-Key header.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Keep your API key secret

Your API key carries many privileges, so be sure to keep it secret! Do not share your secret API key in publicly accessible areas such GitHub, client-side code, and so forth.

Suggest Edits

Validate API key

 
gethttps://api.oncehub.com/v1/test
curl --request GET \
  --url https://api.oncehub.com/v1/test
var request = require("request");

var options = { method: 'GET', url: 'https://api.oncehub.com/v1/test' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.oncehub.com/v1/test")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.oncehub.com/v1/test");

xhr.send(data);
import requests

url = "https://api.oncehub.com/v1/test"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "message": "The API key is valid for account: admin@example.com"
}
{
  "type": "authentication_error",
  "message": "Invalid API key."
}
{
  "type": "authentication_error",
  "message": "Your account plan does not support API access. To use the ScheduleOnce API, you must upgrade to the Enterprise plan."
}
{
  "type": "authentication_error",
  "message": "Expired API key. The key has been revoked by the account owner."
}

Headers

API-Key
string

An api key from your OnceHub account

 
Suggest Edits

Errors

 

Overview of error responses

OnceHub uses conventional HTTP response codes to indicate the success or failure of an API request.

Successful requests are given status codes in the 2xx range, while unsuccessful requests have status codes in the 4xx or 5xx range.

4xx codes indicate an error that failed given the information provided (e.g., an invalid parameter, object not found, etc.); 5xx codes indicate an error with OnceHub servers (these are rare).

Error structure

The API returns error responses in JSON format, with the following structure:

{
  "type": "invalid_request_error",
  "message": "No existing Webhook subscription with this ID can be found."
}

Error types

Error responses are categorized into four different types, corresponding to the following situations:

Type
Description

authentication_error

The server could not authenticate your request. Check to make sure you have entered a valid API key in the correct format, in the API-Key header.

invalid_request_error

One or more of the input parameters is not valid. Check that you have entered the correct values for all required parameters. URLs must be entered in full, and they must use the https:// prefix.

rate_limit_error

Too many requests hit the API too quickly.

api_error

There was an error on the OnceHub servers. This type of error is rare.

Error messages

In addition to the standard HTTP codes and error type specified in the table above, each error response includes a human-readable message that provides additional details that can help you troubleshoot why the request failed.

For example, if you attempt to create a new Webhook subscription, but there is already a Webhook with the same name, you would receive the following error message:

{
  "type": "invalid_request_error",
  "message": "A Webhook subscription with this name already exists."
}
Suggest Edits

The Webhook object

 

Data model description

Webhook subscriptions are configured with a unique ID, User-provided name and POST URL, and an array of User-specified event triggers representing different booking lifecycle events.

Learn more about Webhook subscription configuration

Field
Type
Description

id

string

Unique alphanumeric identifier for the object. The prefix of the Webhook ID is WHK_.

object

string

String representing the object’s type. Objects of the same type share the same value. The value here is webhook.

name

string

Name of the Webhook. This name is only used by you to easily differentiate between Webhooks in the app.

url

string

The URL on your side to which we will send the event payload.

events

list

A list of events this Webhook will trigger for.

creation_time

timestamp

The time the Webhook was created.

Suggest Edits

Example Webhook object

 

Sample Webhook object

The following is an example of a Webhook object with the name Cancellations and No-shows. This Webhook subscription is configured to send POST messages to https://mywebsite.com/webhooks whenever a booking is canceled or set to "no-show" status (event triggers: booking.canceled and booking.no_show).

{
  "object": "webhook",
  "id": "WHK-7JD9LBVZTQ",
  "name": "Cancellations and No-shows",
  "url": "https://mywebsite.com/webhooks",
  "events": ["booking.canceled", "booking.no_show"],
  "creation_time": "2018-03-19T07:51:11.290Z"
}
Suggest Edits

Event triggers

 

Supported event types

The following event types are supported. Learn more about Webhook event triggers

Event type
Booking scenario

booking

All booking lifecycle events

booking.scheduled

Customer schedules a booking
User approves a booking requested by a Customer

booking.rescheduled

Customer reschedules a booking on the same booking page
Customer reschedules a booking following a request from the User to reschedule

booking.canceled_then_rescheduled

Customer cancels a booking and then reschedules on a different booking page

booking.canceled_reschedule_requested

User cancels and sends a request to the Customer to reschedule

booking.canceled

User or Customer cancels a booking

booking.completed

Booking end time has passed

booking.no_show

User sets the completed booking to No-show

Suggest Edits

Create Webhook

Creates a Webhook subscription.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.oncehub.com/v1/webhooks
curl --request POST \
  --url https://api.oncehub.com/v1/webhooks
var request = require("request");

var options = { method: 'POST', url: 'https://api.oncehub.com/v1/webhooks' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.oncehub.com/v1/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.oncehub.com/v1/webhooks");

xhr.send(data);
import requests

url = "https://api.oncehub.com/v1/webhooks"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "object": "webhook",
  "id": "whk_164xRv2eZvKYlo2CZxJZWm1E",
  "name": "New booking webhook",
  "url": "https://mywebsite.com/webhooks/booking",
  "events": ["booking.completed", "booking.rescheduled"],
  "creation_time": "2017-09-06T20:57:17.467Z"
}

Body Params

url
string

URL for receiving POST messages from OnceHub

name
string

Unique name for your Webhook subscription. This name is only used by you for reference.

events
array of strings

An array of Booking lifecycle events that will trigger the Webhook.

Headers

API-Key
string

An api key from your OnceHub account

 

Input parameters

When creating the Webhook, you should provide a name, a url for receiving POST messages, and an array of events in the request body.

You may specify specific booking lifecycle events you wish to subscribe to, or you can pass the booking event to trigger the POST payload message whenever any of the supported booking lifecycle events occurs. Learn more about events

Make sure that you pass the full URL. For security reasons, we only accept HTTPS URLs.

You must authenticate the request by passing a valid API key in the API-Key header parameter. Learn more about the API key

Returns

Returns the Webhook object if the call succeeded. Returns an error if something goes wrong. Learn more about errors

Suggest Edits

List all Webhooks

Returns a list of your Webhook subscriptions, sorted by creation date.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.oncehub.com/v1/webhooks
curl --request GET \
  --url https://api.oncehub.com/v1/webhooks
var request = require("request");

var options = { method: 'GET', url: 'https://api.oncehub.com/v1/webhooks' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.oncehub.com/v1/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.oncehub.com/v1/webhooks");

xhr.send(data);
import requests

url = "https://api.oncehub.com/v1/webhooks"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "object": "list",
  "data": [
    {
      "object": "webhook",
      "id": "whk_164xRv2eZvKYlo2CZxJZWm1E",
      "name": "New booking webhook",
      "url": "https://mywebsite.com/webhooks/booking",
      "events": ["booking.completed", "booking.rescheduled"],
      "creation_time": "2017-09-06T20:57:17.467Z"
    },
    {...},
    {...}
  ]
}

Headers

API-Key
string

An api key from your OnceHub account

 

Input parameters

No body parameters are required.

You must authenticate the request by passing a valid API key in the API-Key header parameter. Learn more about the API key

Returns

Returns a list with a data property that contains an array of Webhooks if the call succeeded. Each entry in the array is a separate webhook object. The entries are sorted by creation date; the most recently created Webhook subscriptions appear first.

Returns an error if something goes wrong. Learn more about errors

Suggest Edits

Get a single Webhook

Returns a single Webhook subscription by ID.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.oncehub.com/v1/webhooks/id
curl --request GET \
  --url https://api.oncehub.com/v1/webhooks/id
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.oncehub.com/v1/webhooks/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.oncehub.com/v1/webhooks/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.oncehub.com/v1/webhooks/id");

xhr.send(data);
import requests

url = "https://api.oncehub.com/v1/webhooks/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "object": "webhook",
  "id": "whk_164xRv2eZvKYlo2CZxJZWm1E",
  "name": "New booking webhook",
  "url": "https://mywebsite.com/webhooks/booking",
  "events": ["booking.completed", "booking.rescheduled"],
  "creation_time": "2017-09-06T20:57:17.467Z"
}

Path Params

id
string
required

ID of the Webhook

Headers

API-Key
string

An api key from your OnceHub account

 

Input parameters

To retrieve a single Webhook, pass the Webhook ID in the URL path.

You must authenticate the request by passing a valid API key in the API-Key header parameter. Learn more about the API key

Returns

Returns a Webhook object that you have previously created if the call succeeded. Returns an error if something goes wrong. Learn more about errors.

Suggest Edits

Delete Webhook

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.oncehub.com/v1/webhooks/id
curl --request DELETE \
  --url https://api.oncehub.com/v1/webhooks/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.oncehub.com/v1/webhooks/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.oncehub.com/v1/webhooks/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.oncehub.com/v1/webhooks/id");

xhr.send(data);
import requests

url = "https://api.oncehub.com/v1/webhooks/id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "deleted": true,
  "id": "whk_164xRv2eZvKYlo2CZxJZWm1E"
}

Path Params

id
string
required

ID of the Webhook to delete

Headers

API-Key
string

An api key from your OnceHub account

 

Input parameters

To delete a Webhook subscription, pass the Webhook ID in the URL path.

You must authenticate the request by passing a valid API key in the API-Key header parameter. Learn more about the API key

Returns

Deletes the Webhook and returns a 200 success code if the call succeeded. Returns an error if something goes wrong. Learn more about errors

Suggest Edits

User-specified endpoint responses

 

Responding to a Webhook POST message

When you create a Webhook subscription, you must specify the URL endpoint that will receive the HTTP POST messages triggered by the defined event types.

Your receiving server must be configured to receive the JSON event object. Learn more about how to configure Webhook subscriptions

Error codes

To acknowledge receipt of a Webhook data payload, your endpoint should return a 2xx HTTP status code. All response codes outside this range, including 3xx codes, will indicate to us that you did not receive the payload.

A URL redirection or a "Not Modified" response will also be treated as a failed request. OnceHub will ignore any other information returned in the request headers or request body.

Retry mechanism

If for some reason your endpoint does not successfully receive the Webhook payload, we will continue trying to send the HTTP POST message every hour, for up to three days. If your servers are unable to successfully receive the Webhook payload for more than three days, the retry protocol will be halted.

Suggest Edits

The event object

 

Data model description

The event object is sent in the Webhook payload, in standard JSON format and contains a unique ID, the event that triggered the payload (e.g. booking.scheduled), the time the event occurred, the API version, and a nested data object. Learn more about the event object and the Webhook payload

Field
Type
Description

id

string

Unique alphanumeric identifier for the object. The prefix of the event ID is EVNT_.

object

string

String representing the object’s type. Objects of the same type share the same value. The value here is event.

creation_time

datetime

The time the event object was created.

type

string

The type of the event. See below for the event types we currently support.

api_version

string

The OnceHub API version used to render the data object.

data

hash

The object containing relevant data associated with the event that triggered the payload.

Suggest Edits

Example event object

 

Sample event object

The following is an example of an event object. The object has a unique ID, object type event, time of creation, event type (the event that triggered the payload), API version, and data object. For a booking lifecycle event, the data object will contain a booking object with information about the relevant booking. Learn more about the booking object 

{
  "id": "EVNT-KN56U3YL7C",
  "object": "event",
  "creation_time": "2018-03-22T09:49:12Z",
  "type": "booking.scheduled",
  "api_version": "v1",
  "data": {}
}
Suggest Edits

The booking object

 

Data model description

The booking object is sent in standard JSON format inside the data object, which is nested under the event object in the Webhook payload. The booking object contains a tracking ID, booking data, cancel/reschedule data when relevant, Booking form submission data, Booking page, Master page, and event type data. Learn more about the data object and the Webhook payload

Field
Type
Description

object

string

String representing the object’s type. Objects of the same type share the same value. The type here is booking.

tracking_id

string

A unique ID automatically assigned to every booking.

package_id

string

A unique ID automatically assigned to every Session package.

subject

string

The name of the Service or Subject as defined in the Booking form.

status

string

The status of the booking event. The booking can have any of the following statuses: Requested, Scheduled, Rescheduled, Completed, Canceled, or No-Show.

creation_time

datetime

The date and time when the booking was created, in UTC.

starting_time

datetime

The starting date and time, in the Booking page time zone.

owner

string

The owner of the booking. This is the User who originally accepted the booking, and remains unchanged even if the booking was reassigned to a new Booking page.

duration_minutes

integer

The length of the meeting, in minutes.

virtual_or_physical_location

string

The virtual or physical location for the meeting.

customer_time_zone_description

string

The time zone selected by the Customer.

cancel_reschedule_link

url

The Cancel/Reschedule link sent to the Customer.

canceled_booking_tracking_id

string

The tracking ID of the booking that was canceled.

cancel_reschedule_reason

string

The reason given for canceling or rescheduling a meeting.

name_of_user_who_canceled_rescheduled

string

The name of the User who performed the cancellation or reschedule action.

name_of_customer_who_canceled_rescheduled

string

The name of the Customer who performed the cancellation or reschedule action.

form_submission

hash

The object containing information entered by the Customer into the Booking form.

form_submission.name

string

The name provided by the Customer in the Booking form.

form_submission.email

string

The email provided by the Customer in the Booking form.

form_submission.phone

string

The phone number provided by the Customer in the Booking form.

form_submission.mobile_phone

string

The mobile phone number provided by the Customer in the Booking form.

form_submission.note

string

The note provided by the Customer in the Booking form.

form_submission.company

string

The company provided by your Customer in the Booking form.

form_submission.guests

array

List of additional attendees (emails) invited by the Customer.

form_submission.custom_fields

hash

The object containing custom Booking form fields.

booking_page.public_name

string

The Customer-facing name of the Booking page used to make the booking.

booking_page.internal_label

string

The internal name of the Booking page used to make the booking.

booking_page.link

url

The URL of the Booking page used to make the booking.

booking_page.category

string

The Category to which the Booking page has been assigned.

booking_page.time_zone_description

string

The time zone of the Booking page as defined in the Availability section.

master_page.name

string

The Customer-facing name of the Master booking page used to make the booking.

master_page.label

string

The internal name of the Master booking page used to make the booking. The label is defined in the left pane of the Master booking pages tab under Configuration.

master_page.link

url

The URL of the Master booking page used to make the booking.

event_type.name

string

The name of the Service selected by the Customer.

event_type.description

string

The description of the Service selected by the Customer.

event_type.category

string

The Category of the Service selected by the Customer.

external_calendar.type

string

The type of external calendar to which the booking was added.

external_calendar.name

string

The name of the external calendar to which the booking was added.

external_calendar.id

string

The id of the external calendar to which the booking was added.

external_calendar.event_id

string

The id of the booking event that was created in the external calendar.

Suggest Edits

Example booking object

 

Sample booking object

The following is an example of a booking object. The booking object is nested inside the data object, which is delivered inside the event object of the Webhook data payload. Learn more about the event object

The booking object contains all of the relevant booking data related to the booking lifecycle event that triggered the Webhook POST message. Learn more about the Webhook data payload 

{
  "id": "EVNT-KN56U3YL7C",
  "object": "event",
  "creation_time": "2018-03-22T09:49:12Z",
  "type": "booking.scheduled",
  "api_version": "v1",
  "data": {
    "object": "booking",
    "tracking_id": "D36E0002",
    "subject": "Budget management",
    "status": "Scheduled",
    "creation_time": "2018-03-22T09:48:48Z",
    "starting_time": "2018-03-22T04:30:00Z",
    "owner": "Andrea Hartie",
    "package_id": null,
    "duration_minutes": 60,
    "virtual_or_physical_location": "1600 Pennsylvania Avenue",
    "customer_time_zone_description": "(GMT-5) United States; Eastern time",
    "cancel_reschedule_link": "https://go.oncehub.com/financefirm?Params=IPLa6BkbZ-QjWTEeZH3cb7afCgcinMNuLvaH-7mTZO4",
    "canceled_booking_tracking_id": null,
    "cancel_reschedule_reason": null,
    "name_of_user_who_canceled_rescheduled": null,
    "name_of_customer_who_canceled_rescheduled": null,
    "form_submission": {
      "name": "Carrie Customer",
      "email": "so.carrie.customer@gmail.com",
      "phone": "",
      "mobile_phone": "1-2025550195",
      "note": "I want to discuss how to save more money each month.",
      "company": null,
      "guests": [""],
      "custom_fields": [
        { "name": "Profession", "value": "Executive assistant" },
        { "name": "Earned income", "value": "35,000 USD" },
        { "name": "Passive income", "value": "None" }
      ]
    },
    "booking_page": {
      "public_name": "Andrea Hartie",
      "internal_label": "AndreaHartie",
      "link": "https://go.oncehub.com/andreahartie",
      "category": "Financial planning firm",
      "time_zone_description": "(GMT-5) United States; Eastern time"
    },
    "master_page": {
      "name": "Financial Services Inc.",
      "label": "financefirm",
      "link": "https://go.oncehub.com/financefirm"
    },
    "event_type": {
      "name": "Budget management",
      "description":
        "We analyze your current income, expenses and debt. From this we work with you to create a sound financial plan that will allow you to enjoy life and meet your financial obligations simultaneously.",
      "category": "Budgeting & Saving"
    },
      "external_calendar": {
      "type": "Google",
      "name": "andrea.hartie@example.com",
      "id": "andrea.hartie@example.com",
      "event_id": "8kvu74dda8kcv0gmmlm3folrhc"
    }
  }
}