Provision a Managed Organizational Unit Early access

Description #

Creates a Managed Organizational Unit, or updates it if your application has already provisioned one with the same organizational_unit_id, and returns an authorization for it.

The Managed Organizational Unit collects your customer’s connections to services such as their calendar and conferencing systems, the people you add as members, and everyone’s scheduling preferences. Your application solely controls its membership.

The authorization has the organizational_unit_scheduling scope. It’s equivalent to the customer authorizing your application through Organization Connect, and its access token is refreshed in the same way. If the authorization has been revoked, provisioning again creates a new one.

Authentication is with your application’s client_secret.

URL format #

{data_center_url}/v1/organizational_units

Example Request #

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",
  "default_locale": "en",
  "default_tzid": "America/Chicago",
  "callback_url": "https://example.com/cronofy/notifications"
}

Example Response #

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "organizational_unit": {
    "sub": "org_16c99459e89a32a08cdb6b2a",
    "organizational_unit_id": "customer-123",
    "name": "Hill Valley Futures",
    "default_locale": "en",
    "default_tzid": "America/Chicago",
    "callback_url": "https://example.com/cronofy/notifications"
  },
  "authorization": {
    "access_token": "{ACCESS_TOKEN}",
    "token_type": "bearer",
    "expires_in": 3600,
    "refresh_token": "{REFRESH_TOKEN}",
    "scope": "organizational_unit_scheduling",
    "sub": "org_16c99459e89a32a08cdb6b2a"
  }
}

200 OK is returned whether the Managed Organizational Unit was created or already existed.

Request Parameters #

organizational_unit_id Required  #

Your application’s identifier for the Managed Organizational Unit, such as the ID of the customer in your system String.

It’s unique among the Managed Organizational Units your application manages in the data center. Provisioning again with the same organizational_unit_id updates the existing Managed Organizational Unit.

name Required  #

The name of the Managed Organizational Unit, typically your customer’s name String.

Set to the value sent on every call.

default_locale Optional  #

The default locale for the Managed Organizational Unit, such as en or fr String.

Defaults to en when the Managed Organizational Unit is created. Left unchanged when omitted.

Supported locales:

• ar Arabic
• cs Czech
• cy Welsh
• de German
• en US English (default)
• es Spanish
• fr French
• fr-CA Canadian French
• he Hebrew
• it Italian
• ja Japanese
• nl Dutch
• pl Polish
• pt-BR Brazilian Portuguese
• ro Romanian
• ru Russian
• sv Swedish
• tr Turkish
• zh-CN Simplified Chinese

default_tzid Optional  #

The default time zone for the Managed Organizational Unit, as an identifier from the IANA Time Zone Database such as America/Chicago String.

Left unchanged when omitted. If it has never been set, the data center’s default time zone is used.

callback_url Optional  #

The URL Cronofy sends webhooks to for the Managed Organizational Unit, such as those about its members and Scheduling Requests String.

It must be an http or https URL that’s reachable from the internet. Left unchanged when omitted. Pass null to stop sending webhooks.

Response Parameters #

organizational_unit.sub  #

Cronofy’s identifier for the Managed Organizational Unit String.

organizational_unit.organizational_unit_id  #

Your application’s identifier for the Managed Organizational Unit String.

organizational_unit.name  #

The name of the Managed Organizational Unit String.

organizational_unit.default_locale  #

The default locale String.

organizational_unit.default_tzid  #

The default time zone identifier String.

organizational_unit.callback_url  #

The URL webhooks are sent to, or null if none String.

authorization.access_token  #

The access token for calling the API on behalf of the Managed Organizational Unit String.

authorization.token_type  #

Always bearer String.

authorization.expires_in  #

The number of seconds until the access token expires Integer.

authorization.refresh_token  #

The refresh token for getting a new access token with Refresh an Access Token String.

Provisioning again also returns a valid access token.

authorization.scope  #

The scopes granted, separated by spaces. Includes organizational_unit_scheduling String.

authorization.sub  #

Cronofy’s identifier for the Managed Organizational Unit String.

Error responses #

401 Unauthorized #

The request was refused as the client_secret wasn’t recognized.

402 Payment Required #

The request was refused as your plan doesn’t include Managed Organizational Units.

403 Forbidden #

The request was refused as it was made by an Internal Application.

422 Unprocessable #

The request was unable to be processed due to it containing invalid parameters.

The response contains a JSON object with one or more errors for the invalid parameters. For example, omitting the required name parameter returns:

{
  "errors": {
    "name": [
      {
        "key": "errors.required",
        "description": "required"
      }
    ]
  }
}

The key is intended for programmatic use, and the description is a human-readable equivalent.