Introduction

The provisioning API is an admin-only API used to create users and push synchronisations in MyTimetable. This API can be used in your user provisioning processes to support an push synchronisation 'opt-out' scenario. The API is supported from MyTimetable version 3.0, and only supports JSON output and form-encoded input.

User resources

/users

Method: GET

Description: Query all known usernames.

Parameters: none

Request URL

$base_url/api/v0/users

Example response body

{
    "users": [
        "alice", 
        "bob", 
        "carol"
    ]
}

/users/{username}

Method: PUT

Description: Ensures a user with the specified username exists.

Parameters

NameDescriptionDefault value
username (required)The username for which a user profile should be created if it doesn't exist already.-

Example request URL

$base_url/api/v0/users/alice

Example response body: none (status code 204 indicates success/user already exists)

/users/{username}

Method: DELETE

Description: Deletes the user profile with the specified username if it exists.

Parameters

NameDescriptionDefault value
username (required)The username for which a user profile should be deleted if it exists.-

Example request URL

$base_url/api/v0/users/alice

Example response body: none (status code 204 indicates success/user not found)

Synchronization resources

/synchronizations

Method: GET

Description: Query all synchronizations.

Parameters: none

Request URL

$base_url/api/v0/synchronizations

Example response body

{
    "synchronizations": [
        {
            "id": 1,
            "username": "alice",
            "type": "o365"
        },
        {
            "id": 2,
            "username": "bob",
            "type": "googlecalendar"
        }
    ]
}

/synchronizations

Method: PUT

Description: Sets up a synchronization with a user's external calendar.

Parameters

NameDescriptionDefault value
username (required)The username for which the synchronization should be created.-
type (required)The synchronization type, which indicates the calendaring service provider.-
provisioning_smtpAddress *The user's mailbox address in Exchange or Office 365.-

* Only applicable when using a ProvisioningPreDelegatedEWSLinkingAdapter or ProvisioningPreAuthorizedOffice365LinkingAdapter.

Example request URL

$base_url/api/v0/synchronizations

Example request body (application/x-www-form-urlencoded)

username=alice&type=ews&provisioning_smtpAddress=alice@example.org

Example response body: none (status code 204 indicates success)

/synchronizations/{id}

Method: DELETE

Description: Deletes the synchronization with the specified id.

Parameters

NameDescriptionDefault value
username (required)The id of the synchronization which should be deleted.-
unlinkMode (required)

The unlink mode indicates what should happen to the events in the user's calendar:

  • UNLINK_ONLY Leaves all events in place.
  • DELETE_FUTURE_EVENTS Only events which have been pushed with this specific synchronization id and which have a start date in the future are removed.
  • DELETE_ALL_EVENTS All events which have been pushed with this specific synchronization id are removed.
  • CLEANUP All events which have been pushed by this MyTimetable instance are removed, even those with a different synchronization id.
-

Example request URL

$base_url/api/v0/synchronizations/3

Example response body: none (status code 204 indicates success; 422 indicates synchronization not found)