{"info":{"_postman_id":"034f9569-adcc-4632-aee0-445e0234c14d","name":"FreeBusy REST API","description":"

Preliminary API documentation subject to change.

API Security

All requests made to the FreeBusy REST API require an authorization token in the form of an API Key. API Keys are scoped to either teams or individuals:

Team API Keys allow you to create webhooks scoped to all team scheduling activity and can be obtained from the Team Management Page (formerly known as the Subscription Management Page).
Individual API Keys allow you to create webhook scope to an individual's scheduling activity and can be obtained from the Calendars & Integrations Page (coming soon)

The API Key must be supplied with every REST API request in the Authorization header using the Bearer scheme, like this:

POST https://api.freebusy.io/v1/webhook\nAuthorization: Bearer [API Key]\n\n

Webhook Notifications

You can create webhooks to be notified about these types of scheduling activity:

event.scheduled
Triggered when a calendar event is created by FreeBusy as a result of an appointment being scheduled via a booking page (whether manually as a result of Manual Accept or automatically as a result of Auto-Accept policy) or a poll being scheduled (whether manually by the organizer or delegate or automatically because it reached consensus)
event.rescheduled
Triggered when the time for a calendar event created by FreeBusy is changed as a result of either the host or a guest using the reschedule link to reschedule via FreeBusy. This notification is not triggered when the calendar event is changed directly in the calendar.
event.cancelled
Triggered when the calendar event created by FreeBusy is cancelled and deleted as a result of either the host or a guest using the reschedule link to cancel via FreeBusy. This notification is not triggered when the calendar event is removed directly from the calendar.

Webhook Security

Ensuring authenticity of Create Webhook request

To protect the target URL from abuse and to ensure that a Create Webhook request is submitted by the owner of the webhook target URL, FreeBusy validates the Create Webhook request by posting a validation message to the target URL with an activation code in the X-Webhook-ActivationCode header.

To confirm authenticity of the Create Webhook request, target URL must reflect the X-Webhook-ActivationCode header and value back to FreeBusy by including it in the response.

Sample validation sequence:

Request from FreeBusy to target URL:

POST https://hooks.freebusy.io/freebusy\nX-Webhook-ActivationCode: abcdefgh\n\n

Response from target URL to FreeBusy:

200 OK\nX-Webhook-ActivationCode: abcdefgh\n\n

Best practice:

Don't treat the validation response as a one-off operation, rather implement your webhook so it continuously reflects the X-Webhook-ActivationCode header value back to FreeBusy for any request that contains it. This is because FreeBusy may use this validation technique if your webhook becomes inactive due to repeated errors why notifications are being POST-ed.

An easy way to do this is to include the validation handling code at the top of the function that processes incoming webhook notifications like this (pseudocode):

if (request.headers[\"X-Webhook-Activation\"] !== null) {\n  response.headers.add(\"X-Webhook-Activation\", request.headers[\"X-Webhook-Activation\"].value);\n  return Ok();\n}\n\n

Ensuring authenticity of posted Webhook Notifications

To ensure that notifications POST-ed to the target URL originate with FreeBusy, target URL owner can submit a self-generated secret when creating the webhook. FreeBusy will use this secret to compute a SHA-1 HMAC for the POST-ed notification and will include the SHA-1 HMAC value in the X-Webhook-Signature header. Target URL can use its own self-generated secret to perform its own HMAC calculation and compare with the FreeBusy value included with the notification.

Sample Webhook Notification

POST https://hooks.freebusy.io/freebusy\nX-Webhook-Signature: de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9\n{\n    \"webhookId\": \"e4230c8b-f0b2-4625-bacc-573adc21785c\",\n    \"notificationId\": \"161c60cf-b926-417a-94cb-2a8bf6966b4c\",\n    \"notificationType\": \"event.scheduled\",\n    \"notificationTimestamp\": 1647292633,\n    \"payload\": {\n        \"id\": \"efc8ddfd88874fd38cd289053ce560b1\",\n        \"startTime\": \"2022-03-14T21:17:13.6798312Z\",\n        \"durationInMin\": 45,\n        \"subject\": \"This field would contain the name of the event\",\n        \"location\": \"This field would contain the locatin of the event\",\n        \"organizer\": {\n            \"email\": \"organizer@example.com\",\n            \"name\": \"Orgnizer Name\",\n            \"timeZone\": \"America/New_York\"\n        },\n        \"participants\": [\n            {\n                \"email\": \"organizer@example.com\",\n                \"name\": \"Orgnizer Name\",\n                \"timeZone\": \"America/New_York\"\n            },\n            {\n                \"email\": \"participant@example.com\",\n                \"name\": \"Participant Name\",\n                \"timeZone\": \"America/Los_Angeles\"\n            }\n        ],\n        \"link\": \"https://freebusy.io/example/event-template\",\n        \"rescheduleUrl\": \"https://freebusy.io/m/efc8ddfd88874fd38cd289053ce560b1\",\n        \"cancelUrl\": \"https://freebusy.io/m/efc8ddfd88874fd38cd289053ce560b1/cancel\"\n    }\n}\n\n

Contact Support:
Email: hello@freebusy.io

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"API Security","slug":"api-security"},{"content":"Webhook Notifications","slug":"webhook-notifications"},{"content":"Webhook Security","slug":"webhook-security"}],"owner":"14312939","collectionId":"034f9569-adcc-4632-aee0-445e0234c14d","publishedId":"UVsHSnYq","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2022-03-10T20:25:48.000Z"},"item":[{"name":"webhook","item":[{"name":"https://api.freebusy.io/v1/webhook","id":"df8b7d45-848c-484b-b9e7-75f12a4f31e9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"warning":"This is a duplicate header and will be overridden by the Authorization header generated by Postman.","key":"Authorization","value":"Bearer ","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://hooks.example.com/freebusy\",\n \"notificationTypes\": [\n \"event.scheduled\",\n \"event.rescheduled\",\n \"event.cancelled\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://api.freebusy.io/v1/webhook","urlObject":{"path":["webhook"],"host":["https://api.freebusy.io/v1"],"query":[],"variable":[]}},"response":[{"id":"bb68ca35-920d-4278-aaae-9506100ae120","name":"Created","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer ","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://hooks.example.com/freebusy\",\n \"notificationTypes\": [\n \"event.scheduled\",\n \"event.rescheduled\",\n \"event.cancelled\"\n ],\n \"secret\": \"qwertyuioopasdfghjklzxcvbnm\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.freebusy.io/v1/webhook"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"3d4c7349-2122-a534-2296-111519e3919d\",\n \"url\": \"https://hooks.example.com/freebusy\",\n \"notificationTypes\": [\n \"event.scheduled\",\n \"event.rescheduled\",\n \"event.cancelled\"\n ]\n}"},{"id":"0f2d389d-382a-433d-a35f-d4f90e9fd6cb","name":"Invalid input","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer ","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"amet dolore in\",\n \"events\": [\n \"event.scheduled\",\n \"event.rescheduled\",\n \"event.cancelled\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://api.freebusy.io/v1/webhook"},"status":"Bad Request","code":400,"_postman_previewlanguage":"text","header":[{"key":"Content-Type","value":"text/plain"}],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"df8b7d45-848c-484b-b9e7-75f12a4f31e9"},{"name":"https://api.freebusy.io/v1/webhook/:id","id":"367b5567-d04c-44e1-ade0-f93077c05879","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[],"url":"https://api.freebusy.io/v1/webhook/:id","urlObject":{"path":["webhook",":id"],"host":["https://api.freebusy.io/v1"],"query":[],"variable":[{"description":{"content":"

(Required) Webhook id to test

\n","type":"text/plain"},"type":"any","value":"3d4c7349-2122-a534-2296-111519e3919d","key":"id"}]}},"response":[{"id":"b4ac21e9-3ff8-472a-8044-1a892a6e45cc","name":"Submitted","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer ","type":"text"}],"url":{"raw":"https://api.freebusy.io/v1/webhook/:id","host":["https://api.freebusy.io/v1"],"path":["webhook",":id"],"variable":[{"key":"id","value":"3d4c7349-2122-a534-2296-111519e3919d","description":"(Required) Webhook id to delete"}]}},"status":"No Content","code":204,"_postman_previewlanguage":"text","header":[{"key":"Content-Type","value":"text/plain"}],"cookie":[],"responseTime":null,"body":""},{"id":"cd377ff3-a9f2-4f35-9b18-f89071fdd006","name":"Invalid ID supplied","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer ","type":"text"}],"url":{"raw":"https://api.freebusy.io/v1/webhook/:id","host":["https://api.freebusy.io/v1"],"path":["webhook",":id"],"variable":[{"key":"id","value":"cillum pariatur in reprehenderit","description":"(Required) Webhook id to delete"}]}},"status":"Bad Request","code":400,"_postman_previewlanguage":"text","header":[{"key":"Content-Type","value":"text/plain"}],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"367b5567-d04c-44e1-ade0-f93077c05879"},{"name":"https://api.freebusy.io/v1/webhook/:id","id":"437fe69a-dfb0-42ed-8b39-4cc5fe209433","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"DELETE","header":[],"url":"https://api.freebusy.io/v1/webhook/:id","urlObject":{"path":["webhook",":id"],"host":["https://api.freebusy.io/v1"],"query":[],"variable":[{"description":{"content":"

(Required) Webhook id to delete

\n","type":"text/plain"},"type":"any","value":"3d4c7349-2122-a534-2296-111519e3919d","key":"id"}]}},"response":[{"id":"0b69a65c-7d47-4310-83b0-71c32ee3dff1","name":"Deleted","originalRequest":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer ","type":"text"}],"url":{"raw":"https://api.freebusy.io/v1/webhook/:id","host":["https://api.freebusy.io/v1"],"path":["webhook",":id"],"variable":[{"key":"id","value":"3d4c7349-2122-a534-2296-111519e3919d","description":"(Required) Webhook id to delete"}]}},"status":"No Content","code":204,"_postman_previewlanguage":"text","header":[{"key":"Content-Type","value":"text/plain"}],"cookie":[],"responseTime":null,"body":""},{"id":"a6cc7094-b437-4629-b825-15b02871f8a4","name":"Invalid ID supplied","originalRequest":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer ","type":"text"}],"url":{"raw":"https://api.freebusy.io/v1/webhook/:id","host":["https://api.freebusy.io/v1"],"path":["webhook",":id"],"variable":[{"key":"id","value":"cillum pariatur in reprehenderit","description":"(Required) Webhook id to delete"}]}},"status":"Bad Request","code":400,"_postman_previewlanguage":"text","header":[{"key":"Content-Type","value":"text/plain"}],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"437fe69a-dfb0-42ed-8b39-4cc5fe209433"},{"name":"Webhook Notification","id":"a479536c-10b4-48f4-9fbc-f793197060b9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"X-Webhook-Signature","value":"qwertyuioopasdfghjklzxcvbnm","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"webhookId\": \"e4230c8b-f0b2-4625-bacc-573adc21785c\",\r\n \"notificationId\": \"161c60cf-b926-417a-94cb-2a8bf6966b4c\",\r\n \"notificationType\": \"event.scheduled\",\r\n \"notificationTimestamp\": 1647292633,\r\n \"payload\": {\r\n \"id\": \"efc8ddfd88874fd38cd289053ce560b1\",\r\n \"startTime\": \"2022-03-14T21:17:13.6798312Z\",\r\n \"durationInMin\": 45,\r\n \"subject\": \"This field would contain the name of the event\",\r\n \"location\": \"This field would contain the locatin of the event\",\r\n \"organizer\": {\r\n \"email\": \"organizer@example.com\",\r\n \"name\": \"Orgnizer Name\",\r\n \"timeZone\": \"America/New_York\"\r\n },\r\n \"participants\": [\r\n {\r\n \"email\": \"organizer@example.com\",\r\n \"name\": \"Orgnizer Name\",\r\n \"timeZone\": \"America/New_York\"\r\n },\r\n {\r\n \"email\": \"participant@example.com\",\r\n \"name\": \"Participant Name\",\r\n \"timeZone\": \"America/Los_Angeles\"\r\n }\r\n ],\r\n \"link\": \"https://freebusy.io/example/event-template\",\r\n \"rescheduleUrl\": \"https://freebusy.io/m/efc8ddfd88874fd38cd289053ce560b1\",\r\n \"cancelUrl\": \"https://freebusy.io/m/efc8ddfd88874fd38cd289053ce560b1/cancel\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"/targetURL","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"1ec12c86-036d-4e5d-b3de-9c7d575033f8","id":"1ec12c86-036d-4e5d-b3de-9c7d575033f8","name":"webhook","type":"folder"}},"urlObject":{"path":["targetURL"],"query":[],"variable":[]}},"response":[],"_postman_id":"a479536c-10b4-48f4-9fbc-f793197060b9"}],"id":"1ec12c86-036d-4e5d-b3de-9c7d575033f8","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"event":[{"listen":"prerequest","script":{"id":"b854861f-d542-418c-afe7-54ff9e9fe3cd","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"8aafd945-3727-4961-a604-c9bab8789041","type":"text/javascript","exec":[""]}}],"_postman_id":"1ec12c86-036d-4e5d-b3de-9c7d575033f8","description":""}],"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]}},"event":[{"listen":"prerequest","script":{"id":"3cb32f88-b366-4f3e-8fb0-1678d7f4cb1a","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"0752984b-4ab9-487e-8b1d-97d07c5da88d","type":"text/javascript","exec":[""]}}],"variable":[{"key":"baseUrl","value":"https://api.freebusy.io/v1","type":"string"}]}