Managed Organizational Units

Read as Markdown

A Managed Organizational Unit is an Organizational Unit that your application creates and manages for one of your customers. Cronofy holds its members, their calendars, Selection Rules, Templates, and Scheduling Controls, and your application runs scheduling for it with Scheduling Requests.

The Sandbox you set up in Getting Started is a Managed Organizational Unit. In production, your application provisions one for each of your customers.

Managed Organizational Units are for building scheduling into software you sell to other companies.

If you’re using Cronofy within your own company, use an Internal Application linked to your own Organizational Unit instead. Internal Applications can’t provision Managed Organizational Units.

Provisioning #

Your application provisions a Managed Organizational Unit with a single call, passing your own identifier for the customer:

POST /v1/organizational_units HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {CLIENT_SECRET}
Content-Type: application/json; charset=utf-8

{
  "organizational_unit_id": "customer-123",
  "name": "Hill Valley Futures"
}

The call is safe to repeat. If your application has already provisioned an Organizational Unit with that identifier, Cronofy updates it rather than creating another.

The response includes an access token and refresh token for the Organizational Unit with the organizational_unit_scheduling scope. In effect, it’s the same as the customer authorizing your application with Organization Connect, without them going through an authorization flow. Use the access token to create Scheduling Requests for the customer’s members, and put the same organizational_unit_id in the Embed Token to embed the Scheduler for them.

Pass a callback_url to receive webhooks for the Organizational Unit, such as those for Scheduling Requests.

See Provision a Managed Organizational Unit for every option.

Members #

Members are the people your customer schedules for, such as interviewers or sales reps. As people join and leave the customer’s team, add members or remove members to keep the Organizational Unit in step with your application.

How a person you add becomes a member depends on how the customer connects their calendars:

Through a service account their administrator authorizes once, as with Enterprise Connect, people you add become members automatically.
Each for themselves, as with Individual Connect, send each person the onboarding link returned when you add them. They become a member once they’ve connected their calendars.

Either way, your application works with the Organizational Unit rather than with each calendar connection, so the same integration serves customers of any size.

Deprovisioning #

When a customer stops using scheduling in your product, deprovision their Managed Organizational Unit. Your application’s access to it ends immediately, and Cronofy stops sending webhooks for it.

From the Sandbox to production #

Provision a Managed Organizational Unit for each customer when they turn on scheduling in your product, and store the tokens against the customer.
Add the customer’s people as members.
Create Scheduling Requests with the customer’s access token, or embed the Scheduler, as you did with the Sandbox.
Handle webhooks sent to the callback_url to keep your records up to date.