Home
Documentation
Partner Portal
From v3.46 we will release the Hub. For now this will include announcements. Click here for more information.
Hi ,
Welcome to the Support Portal. How can we help?
Submit ticket Submit Change Request Submit Feature Request

Articles in this section

Follow

Workspace 365 API (environment)

Created:
Updated:
Quick reference:
Settings -> Integrations -> API settings

Table of Contents

 

Introduction

The Workspace 365 API uses a REST-ish interface meaning instead of calling Actions/Methods, you define the Action you want to perform on a resource via the HTTP METHOD (i.e. GET, POST, PUT & DELETE) and uses JSON as its data protocol.

In this article we discuss the different types of available Workspace API's and how to make use of them. First, an API key has to be created. Instead of one API key for one functionality (e.g. integrations or activities), you can create multiple keys. With this feature you can receive activities from different parties - a unique key for each party. This contributes to security.

 

Prerequisites

Environment administrator can configure the API on the API settings page. To be able to use the API, the following conditions should be met:

  • Make sure the API setting is configured and enabled in the settings. 

Back to top

 

Authentication

Each request to the API should be authenticated with the token generated on the API settings page. Each environment requires its own token.

For authentication use the standard HTTP Authorization header with "Workspace365" authentication scheme and token as credentials:

Authorization: Workspace365 {token}

E.g. Authorization:

Workspace365 00000000-0000-0000-0000-000000000000

It is strongly recommended not to use the API over non-https channels.

 

Authentication response codes

The API responds with the following HTTP status codes in case of authentication failure:

Code

Description

200

Response OK

400

Validation issue, check error response data format

401, 403

Authentication issue. One of the following applies:

Authorization header is missing
Authentication scheme is incorrect
Token is invalid for the environment
The API is not configured for the environment or the environment is inactive

500

Internal server error. This could be caused by passing an incorrect data object


Error responses

When an action cannot be performed because of incorrect input data, the response will be an HTTP status code 400 containing an JSON object having a “globalError” and “fieldErrors” property.

Property “globalError” will be set to a non-null object in case of a validation error which is not connected to a single specific field. It is a JSON object with a “message” property containing potentially human-readable error description.

Property “fieldErrors” will be set if some field values failed the validation. For every such a field there would be a property named the same as in the input, containing a JSON object with a “message” property containing potentially human-readable error description.

Human readable messages can be given in one of the languages supported by Workspace 365 if the request contains a corresponding Accept-Language header.

Back to top

 

API key

API keys can be created in the Workspace settings > Integrations > API settings. 

To create a new key, check the checkbox "Enable", fill in a name (e.g. "API key for Yammer integration") and select the scope of the key.

Click Save to generate the key. Then, Copy the key.

new_api_key.PNG

key_copy.PNG

When the dialogue as shown above is closed, the user cannot retrieve the key from the Workspace anymore. Make sure you store this key somewhere secure.

When a key is generated, it will no longer be stored in the Workspace. However, it is possible to regenerate API keys when for example when the key has been compromised or forgotten. When regenerating the key, the old key no longer works as you will be prompted with the dialogue as shown below.

regenerate_key.png

Editing the key will only give you the option to change the name, change the scope of the key or disable it. It is also possible to temporarily disable a key.

Back to top

 

API's

Activity Feed

Quick reference:
Settings -> Integrations -> API settings -> Activity feed API


Endpoints

POST
/{EnvironmentName}/api/activities
Creates new activity for given user

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

 
string

Activity

Body

Activity to create

Yes

 
Activity

 

Responses

Code

Description

Schema

200

The Activity is created

 
{
id:
  integer 
The id of the activity which is created
user: {
  id:
  integer 
  The id of the user
  upn:
  string 
  The upn of the activity which is created

Note: Either id or upn should be specified (not both)
  }
}

400

Array of Validation Results

ApiErrorResponse

401, 403

Authentication issue

  

500

Internal server error

 


Example request

POST https://workspace365instance.url/{EnvironmentName}/api/activities HTTP/1.1
Accept: application/json
Content-Length: 228
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Workspace365 00000000-0000-0000-0000-000000000000
  
{
  "User": {
      "Upn": "userone@example.com"
  },
  "Icon": {
      "Name": "Phone"
  },
  "Title": "Test activity",
  "Url": "https://workspace365instance.url",
  "Tag": "Proposals",
  "Color": {
      "Kind": "1",
      "Value": "#00ff00"
  },
  "Actions": [
     {
      "Kind": "1", 
      "Title": "Accept proposal",
      "Url": "https://workspace365instance.url/proposal/accept"
     }
  ]
}


Example response

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

{
   "id": 916,
   "user": {
       "id": 1,
       "upn": "userone@example.com"
   }
}
POST
/{EnvironmentName}/api/activities-batch
Creates new activity for a certain scope of users

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

 
string

Batch Activity

Body

Batch Activity to create

Yes

 
Batch Activity

 

Responses

Code

Description

Schema

200

The Activity is created

 
[{
  id:
  integer 
  The id of the activity which is created
  user: {
      id:
    integer 
    The id of the user
    upn:
    string 
    The upn of the activity which is created
  }
}
,
  …
]

400

Array of Validation Results

ApiErrorResponse

401, 403

Authentication issue

  

500

Internal server error

 


Example request

POST https://workspace365instance.url/{EnvironmentName}/api/activities-batch HTTP/1.1
Accept: application/json
Content-Length: 258
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Workspace365 00000000-0000-0000-0000-000000000000

{
 "Scope": {
   "Kind": 0
 },
 "Data": {
    "Title": "test",
    "Url": "https://workspace365instance.url", 
    "Tag": "Proposals",     
    "Icon": {
      "Name": "Phone"
    },
    "Color": {
      "Kind": 1,
      "Value": "#00ff00"
    },
    "Actions": [
      {
        "Kind": 1
        "Title": "Accept Proposal",
        "Url": "https://workspace365instance.url/proposal/accept"
      }
    ]
  }
}


Example response

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

[
    {
        "id": 962,
        "user": {
            "id": 1,
            "upn": "userone@example.com"
        }
    },
    …
]

 

Schemas

NONE
Activity schema
{
  "User": UserLookup,
  "Icon": Icon,
  "Title": "Test activity",
  "Url": "https://workspace365instance.url",
  "Tag": "Proposals",
  "Color": Color,
  "Actions": [
    Action
   ]
}

Property

Type

Optional/Required

Description

User

UserLookup

Required

Specifies the user for the activity.

Icon

Icon

Optional

Specifies the icon which is displayed in the activity. The default icon is displayed when no icon is specified.

Title

String

Required

The title which is displayed in the activity feed.

Url

String

Optional

A url to a page which shows more details about this activity. If a url is specified the activity feed shows ‘View details’.

Tag

String

Optional

A way to indicate what group the activity belongs to. If one is specified, the activity is grouped with other activities with the same tag. If none is specified, the activity will put in the "Other" group.

Color

Color Object

Optional

The default color is used when not specified.

Actions

Array of Action

Optional

Specifies a list of actions. The maximum number of actions is 2.
NONE
User schema
{
 "User": {
   "id": 1,
   "upn": "userone@example.com"
   }
}

Property

Type

Optional/Required

Description

id

Integer

Optional

Specifies the id of the user. Note: id or upn should be specified.

upn

String

Optional

Specifies the upn of the user. Note: id or upn should be specified.
NONE
Icon schema
{
  "Name": "my icon"
}

Property

Type

Optional/Required

Description

Name

String

Optional

Specifies the name of the icon. The default icon is displayed when no name is specified.
NONE
Color schema
{
  "Kind": "1",
  "Value": "#00ff00"
}

Property

Type

Optional/Required

Description

Kind

Int

Required

Options are 1 (custom), 2 (primary), 3 (header).

Value

String

Required when Kind is 1

The Value property specifies a html color. The field is required when the Kind is 1.
NONE
Action schema
{
 "Kind": 1,
   "Title": "Accept proposal",
   "Url": “https://workspace365instance.url/propasal/accept"
}

Property

Type

Optional/Required

Description

Kind

Int

Required

This property determines which icon is shown next to the action title.

Options are: 1 (check), 2 (cancel), 3 (add), 4 (open), 5 (edit), 6 (manage), 7 (delete), 8 (forward), 9 (backward).

Title

String

Required

Specifies the title of the action. Maximum length is 32 characters.

Url

String

Required

The url the user is redirected to when invoking the action.
NONE
Batch Activity schema
{
  "Scope": Scope,
  "Data": ActivityWithoutUser
}

Property

Type

Optional/Required

Description

Scope

Scope

Required

Specifies the scope of users.

Data

ActivityWithoutUser

Required

Specifies the upn of the user. Note: id Specifies activity data.
NONE
Scope schema
{
  "Kind": 0,
  "Users": [
    UserLookup
],
  "Groups": [
    GroupLookup
  ]
}

Property

Type

Optional/Required

Description

Kind

Int

Required

Specifies the scope kind. Possible values: 0 (all users), 1 (users),  2 (groups). 

Users

Array of UserLookup

Required when Kind is 1

his property is required when the scope kind is set to 1. The array should contain at least one user.

Groups

Array of GroupLookup

Required when Kind is 2

This property is required when the scope kind is set to 2. The array should contain at least one group.
NONE
UserLookup schema
{
  "id": 1,
  "upn": "johndoe@ndawdev.onmicrosoft.com"
}

Property

Type

Optional/Required

Description

Id

Int

Required when upn is not specified

Specifies the user by Id. The Id or the upn should be specified. If both are specified, the Id is used.

Upn

String

Required when Id is not specified

Specifies the user by upn. The Id or the upn should be specified. If both are specified, the Id is used.
NONE
GroupLookup schema
{
  "id": 1,
  "name": "test-group"
}

Property

Type

Optional/Required

Description

Id

Int

Required when Name is not specified

Specifies the group by Id. The Id or the Name should be specified. If both are specified, the Id is used.

Name

String

Required when Id is not specified

Specifies the group by Name. The Id or the Name should be specified. If both are specified, the Id is used.
NONE
ActivityWithoutUser schema
{
  "Icon": Icon,
  "Title": "Test activity",
  "Url": "https://workspace365instance.url",
  "Color": Color,
  "Actions": [
    Action
  ]
}

Property

Type

Optional/Required

Description

Icon

Icon

Optional

Specifies the icon which is displayed in the activity. The default icon is displayed when no icon is specified.

Title

String

Required

The title which is displayed in the activity feed.

Url

String

Optional

A url to a page which shows more details about this activity. If a url is specified, the activity feed shows ‘View details’.

Tag

String

Optional

A way to indicate what group the activity belongs to. If one is specified, the activity is grouped with other activities with the same tag. If none is specified, the activity will put in the "Other" group.

Color

Color

Optional

The default color is used when not specified.

Actions

Array of Action

Optional

Specifies a list of actions. The maximum number of actions is 2.

Back to top

 

Available user apps

Quick reference:
Settings -> Integrations -> API settings -> Available user apps


Endpoint

GET
/{EnvironmentName}/api/users/{upn}/apps
Gets all the available apps for the given user upn

Name

Located in

Description

Required

Schema

Environment name

Path

Name of the environment

Yes

string

UPN

Path

User upn

Yes

string

 

 

Code

Description

Schema

200

The available apps are returned 

 
[{ 

  appId: 
   integer  
   The app id 

  type: 
   integer  
   The app type 

  icon: { 
      name: 
    string  
    The name of the icon 
    } 

  appName: 
   string  
   The name of the app 

  url: 
   string  
   The URL of the app 
   NOTE: The URL can be null 

  color: { 
      kind: 
    integer  
    The type of color used  

   value: 
    string  
    The hex value for the color. 
    NOTE: This field is present only     
    when the color kind is  
    custom.(Kind=1) 

    } 
} 
, 
  … 
] 

401, 403

Authentication failure

 

404

Validation issue

ApiErrorResponse

500

Internal server error

  

Example request

GET https://workspace365instance.url/example/api/users/userone@example.com/apps
Authorization: Workspace365 00000000-0000-0000-0000-000000000000

Example response

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

[
 { 
   "appId": 34,
   "type": 21,
   "icon": {
     "name": "Computer Desktop"
   },
   "appName": "TestClientlessRDP",
   "url": "https://workspace365instance.url/example/AppLink/Go/00000000-0000-0000-0000-000000000000",
   "color": {
     "kind": 1,
     "value": "#ff0000"
   }
  }
]


Mapping

NONE
App Kind Mapping

App Kind Integer Value

Color Kind Integer Value

0

Shortcut

1

Email

2

Document

15

Citrix App

20

Azure App

35

Local App

36

Windows Virtual desktop
NONE
Color Kind Mapping

Color Kind Integer Value

Color Kind Integer Value

1

Custom

2

Primary

3

Header

Back to top

 

Announcements

Quick reference:
Settings -> Integrations -> API settings -> Announcements API


Endpoint

POST
/{EnvironmentName}/api/announcements
Creates new Announcement

Name

Located in

Description

Required

Schema

Environment name

Path

Name of the environment

Yes

string

Announcement

Body

Announcement to create

Yes

Announcement

 

Authentication response codes

The API responds with the following HTTP status codes in case of authentication failure:

Responses

Code

Description

Schema

200

The announcement is created

 
{
id:
  integer
The id of the announcement which is created
}

400

Validation issue

ApiErrorResponse

401, 403

Authentication failure

 

500

 Internal server error  

Error response

When an action cannot be performed because of incorrect input data, the response will be an HTTP status code 400 containing an JSON object having a “globalError” and “fieldErrors” property.

Property “globalError” will be set to a non-null object in case of a validation error which is not connected to a single specific field. It is a JSON object with a “message” property containing potentially human-readable error description.

Property “fieldErrors” will be set if some field values failed the validation. For every such a field there would be a property named the same as in the input, containing a JSON object with a “message” property containing potentially human-readable error description.

Human readable messages can be given in one of the languages supported by Workspace 365 if the request contains a corresponding Accept-Language header.

 

Example request

POST https://workspace365instance.url/example/api/announcements HTTP/1.1
Accept: application/json
Content-Length: 9082
Content-Type: application/json
Host: workspace365instance.url
Authorization: Workspace365 00000000-0000-0000-0000-000000000000

{
  "Title": "My announcement",
  "Description": "This is my <b>announcement</b>",
  "Media":
  {
     "MediaKind": 1,
     "Image":
    {
      "Filename": "Minions.jpg",
      "Uri": "data:image/jpeg;base64,/--base 64 image data here --"
   }
  },
  "Category":
  {
     "Id": 2
   },
   "ShowPopupDirectlyToUser": true,
   "AllowComments": true,
   "StartTime": "2021-04-15T00:00Z",
   "EndTime": "2021-04-18T00:00Z"
}

Example response

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

{
   "id": 916
}

 

Schemas

NONE
Announcement schema
{
"Title": "My announcement",
"Description": "This is my announcement",
"Media": Media,
"Category": Category,
"ShowPopupDirectlyToUser": true,
"AllowComments": true,
"StartTime": "2021-04-15T00:00Z",
"EndTime": "2021-04-18T00:00Z"
}

Property

Type

Optional/Required

Description
Title String Required

Specifies the title of the announcement.
Description String Optional

Specifies the description of the announcement.
Media Media Optional

Specifies the media to be added to the announcement.
Category Category Optional

Specifies the category of the announcement. If left empty, the announcement will be added to the "Uncategorized" section
ShowPopupDirectlyToUser Boolean Optional

Specifies whether to show the announcement as a popup. The default value is false.
AllowComments Boolean Optional

Specifies whether comments are enabled for the announcement. The default value is true.
StartTime DateTimeOffset Optional

Specifies the start date and time for the announcement.
EndTime DateTimeOffset Optional

Specifies the end date and time for the announcement.
NONE
Media schema
{
  "MediaKind": 1,
  "Image": Image
}

OR

{
  "MediaKind": 2,
   "VideoEmbedCode": "<iframe width=\"424\" height=\"238\" src=\"https://www.youtube.com/embed/1uDQQVnrDqI\" title=\"YouTube video player\"
frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture\"
allowfullscreen></iframe>"
}

Property

Type

Optional/Required

Description
MediaKind Integer Optional

Specifies the type of media to be attached. Can be 0 (none), 1 (image) or 2 (video).
Image Image

Required when MediaKind=1

Specifies the details of the image to be added. To be provided only if MediaKind = 1.

VideoEmbedCode

 String

Required when MediaKind=2

Specifies the embed code of the video to be added. To be provided only if MediaKind = 2.
NONE
Image schema
{
  "Filename": "Minions.jpg",
  "Uri": "data:image/jpeg;base64,/--base 64 image data here --"
}

Property

Type

Optional/Required

Description
Filename String Required

Specifies the name of the image.

Uri

 String Required

Specifies the base 64 URI of the image.
NONE
Category schema
{
  "Id": 1,
  "Name": “Company"
}

Property

Type

Optional/Required

Description
Id Integer

Optional*

Specifies the id of the category.

Name

 String

Optional*

Specifies the name of the category.

* Only one of the options should be passed. If none are passed, then the announcement is added to “Uncategorized” by default.

Back to top

 

App icons

Quick reference:
Settings -> Integrations -> API settings -> App icons API
This endpoint for images is an extension to the User available apps API (available from V3.30).


Endpoints

GET
/{EnvironmentName}/api/appicons/{Source}
Gets a list of all the global app icons

Name

Located in

Description

Required

Schema

Environment name

Path

Name of the environment

Yes

string

Source

Path

 Source of the icon. Possible values are global or environment

Yes

String

 

 

Code

Description

Schema

200

The available icons are returned

 
[{
  id:
   integer 
   The app icon id
  kind:
   integer 
   The icon kind
  name:
   string 
   The name of the app icon
}
,
 ...
]

400

The requested app icon is not found, check error response data format

ApiErrorResponse

401, 403

Authentication failure

 

500

 Internal server error  

Example request

GET https://workspace365instance.url/example/api/appicons/global
Authorization: Workspace365 00000000-0000-0000-0000-000000000000

Example response

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

[
  {
   "id": 1,
   "kind":0,
   "name":"Box"
 },
 {
   "id": 36,
   "kind":2,
   "name":"Computer Desktop"
  }
]
GET
/{EnvironmentName}/api/appicons/{Source}/{Id}
Gets information about a specific app icon

Name

Located in

Description

Required

Schema

Environment name

Path

Name of the environment

Yes

string

Source

Path

 Source of the icon. Possible values are global or environment

Yes

String

Id

path

 Id app icon

Yes

Integer

 

 

Code

Description

Schema

200

The app icon info is returned

 
{
  id:
   integer 
   The app icon id
  kind:
   integer 
   The icon kind
  name:
   string 
   The name of the app icon
}

400

The requested app icon is not found, check error response data format

ApiErrorResponse

401, 403

Authentication failure

 

500

 Internal server error  

Example request

GET https://workspace365instance.url/example/api/appicons/global/36
Authorization: Workspace365 00000000-0000-0000-0000-000000000000

Example response

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

{
  "id": 36,
  "kind":2,
  "name":"Computer Desktop"
}
GET
/{EnvironmentName}/api/appicons/{Source}/{Id}/content
Gets the content of a specific app icon

Name

Located in

Description

Required

Schema

Environment name

Path

Name of the environment

Yes

string

Source

Path

 Source of the icon. Possible values are global or environment

Yes

String

Id

path

 Id app icon

Yes

Integer

 

 

Code

Description

Schema

200

The available icons are returned

 The content of the response contains the app icon data

400

The requested app icon is not found, check error response data format

ApiErrorResponse

401, 403

Authentication failure

 

500

 Internal server error  

Example request

GET https://workspace365instance.url/example/api/appicons/global/36/content
Authorization: Workspace365 00000000-0000-0000-0000-000000000000

Example response

HTTP/1.1 200 OK
Content-Type: image/svg+xml
Content-Length: 211

<svg fill="#fff" 
 xmlns="http://www.w3.org/2000/svg" viewBox="0 0 76 76">
 <path d="M6 57.126h64v6.742H6zm18.628-7.03h26.744v4.306H24.628zM10.444 15.99v30.588h55.112V15.99zm-4.026-3.858H69.58v37.666H6.418z"/>
</svg>

 

Icon kind

NONE
Icon kind

Icon Kind Integer Value

Meaning

0

Png image

1

Svg image

2

Svg image

Back to top

Integration credentials

Quick reference:
Settings -> Integrations -> API Settings -> Integration credentials API


Endpoints

POST
/{EnvironmentName}/IntegrationCredentialsApi/User/{Upn}/
Creates new Integration credentials for given user

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

 
string

Upn

Path

User principal name of the user to create the Integration credentials for

Yes

 
string

Integration credentials

Body

Integration credentials to create

Yes

 
{
        
        username:
        string (email)
        Username of the Integration credentials
        password: string
        Password of the Integration credentials 
        
}

Responses

Code

Description

Schema

200

The Integration credentials were created

 
{
        id:
            integer 
        The id of the Integration credentials which were created
}

400

Validation issue

ApiErrorResponse

401, 403

Authentication issue

 

404

The user was not found

 

Example request

POST https://workspace365instance.url/{EnvironmentName}/IntegrationCredentialsApi/User/userone@example.com/ HTTP/1.1
Accept: application/json
Content-Length: 68
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Workspace365 4613e4c6-aa59-45d0-88c9-c99feddf3959
 
{
  "username": "userone@example.com",
  "password": "qwerty"
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 8
 
{"id":8}
PUT
/{EnvironmentName}/IntegrationCredentialsApi/{Id}/
Updates the credentialset

Parameters

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string 

 

Id

Path

Id of the Integration credentials to update

Yes

integer

Integration credentials

Body

New properties of the Integration credentials

Yes

 
{
        username:
         string (email)
        Username of the Integration credentials
        password:
         string
        Password of the Integration credentials
}

 

Responses

Code

Description

Schema

200

The Integration credentials were updated

 

400

Validation issue

ApiErrorResponse

401, 403

Authentication issue

  

404

The Integration credentials were not found

  


Example request

PUT https://workspace365instance.url/{EnvironmentName}/IntegrationCredentialsApi/8/ HTTP/1.1
Accept: application/json
Content-Length: 68
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Workspace365 4613e4c6-aa59-45d0-88c9-c99feddf3959
 
{
  "username": "userone@example.com",
  "password": "qwerty_updated"
} 

Example response

HTTP/1.1 200 OK
Content-Length: 0

Back to top

 

ActiveDirectorySync

Quick reference:
Settings -> Users & groups -> Active Directory -> Sync API authentication token

Endpoints

PUT
/{EnvironmentName}/ActiveDirectorySyncAPI/Users/{ObjectId}/
Creates new user

Name

Located in

Description

Schema

EnvironmentName

Path

Name of the Environment

 
string

ObjectId

Path

ObjectId of the user

 
Guid

User Info

Body

User Info to create

 
{

"FirstName": "Sarah",
"LastName": "de Vries",
"UserPrincipalName": "sarah@w365support.onmicrosoft.com",
"Email": "sarah@365support.onmicrosoft.com",
"SecondaryEmail": "anthony@w365support.onmicrosoft.com",
"IsAdmin": "false",
"IsActive": "true",
"JobTitle": "",
"MobilePhone": ""

}

Responses

Code

Description

Schema

200

The user is created

  

400

Validation issue

ApiErrorResponse

401, 403

Authentication issue

 

Example request

PUT https://workspace365instance.url/{EnvironmentName}/ActiveDirectorySyncAPI/Users/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/ HTTP/1.1
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==
         
        {

"FirstName": "Sarah",
"LastName": "de Vries",
"UserPrincipalName": "sarah@w365support.onmicrosoft.com",
"Email": "sarah@365support.onmicrosoft.com",
"SecondaryEmail": "anthony@w365support.onmicrosoft.com",
"IsAdmin": "false",
"IsActive": "true",
"JobTitle": "",
"MobilePhone": ""

}

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DELETE
/{EnvironmentName}/ActiveDirectorySyncAPI/Users/{ObjectId}/
Deletes the given user

Name

Located

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

 
string

ObjectId

Path

ObjectId of the user

Yes

 
Guid

Responses

Code

Description

Schema

200

The user is deleted

  

400

Validation issue

ApiErrorResponse

401, 403

Authentication issue

 

Example request

DELETE https://workspace365instance.url/{EnvironmentName}/ActiveDirectorySyncAPI/Users/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/ HTTP/1.1
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==

Example response

HTTP/1.1 200 OK
PUT
/{EnvironmentName}/ActiveDirectorySyncAPI/Groups/{ObjectId}/
Creates new group

Name

Located in

Description

Schema

EnvironmentName

Path

Name of the Environment

 
string

ObjectId

Path

ObjectId of the group

 
Guid

Group info

Body

Group info to create

 
{

"Name": "Finance",
"Description": "Everyone from Finance"

}

Responses

Code

Description

Schema

200

The group is created

  

400

Validation issue

ApiErrorResponse

401, 403

Authentication issue

 

Example request

PUT https://workspace365instance.url/{EnvironmentName}/ActiveDirectorySyncAPI/Groups/9acasd74-0599-45ac-b0fe-a0aa0b9a00a/ HTTP/1.1
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==


{

"Name": "Finance",
"Description": "Everyone from Finance"

}

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DELETE
/{EnvironmentName}/ActiveDirectorySyncAPI/Groups/{ObjectId}/
Deletes the given group

Name

Located

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

 
string

ObjectId

Path

ObjectId of the group

Yes

 
Guid

Responses

Code

Description

Schema

200

The group is deleted

  

400

Validation issue

ApiErrorResponse

401, 403

Authentication issue

 

Example request

DELETE https://workspace365instance.url/{EnvironmentName}/ActiveDirectorySyncAPI/Groups/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/ HTTP/1.1
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==

Example response

HTTP/1.1 200 OK
PUT
/{EnvironmentName}/ActiveDirectorySyncAPI/Groups/{ObjectID}/Users/{ObjectID}
Put user in the given group

Name

Located

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

 
string

Group ObjectId

Path

ObjectId of the group

Yes

 
Guid
User ObjectId  Path ObjectId of the user  Yes 
Guid

Responses

Code

Description

Schema

200

The membership is created

  

400

Validation issue

ApiErrorResponse

401, 403

Authentication issue

 

Example request

PUT https://workspace365instance.url/{EnvironmentName}/ActiveDirectorySyncAPI/Groups/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/Users/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/ HTTP/1.1
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==

Example response

HTTP/1.1 200 OK
DELETE
/{EnvironmentName}/ActiveDirectorySyncAPI/Groups/{ObjectID}/Users/{ObjectID}
Delete user in the given group

Name

Located

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

 
string

Group ObjectId

Path

ObjectId of the group

Yes

 
Guid
User ObjectId  Path ObjectId of the user  Yes 
Guid

Responses

Code

Description

Schema

200

The membership is deleted

  

400

Validation issue

ApiErrorResponse

401, 403

Authentication issue

 

Example request

DELETE https://workspace365instance.url/{EnvironmentName}/ActiveDirectorySyncAPI/Groups/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/Users/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/ HTTP/1.1
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==

Example response

HTTP/1.1 200 OK
PUT
/{EnvironmentName}/ActiveDirectorySyncAPI/{ObjectID}/Groups/{ObjectID}
Put group in the given group

Name

Located

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

 
string

Target Group ObjectId

Path

ObjectId of the target group

Yes

 
Guid
Group ObjectId Path ObjectId of the group  Yes 
Guid

Responses

Code

Description

Schema

200

The membership is created

  

400

Validation issue

ApiErrorResponse

401, 403

Authentication issue

 

Example request

PUT https://workspace365instance.url/{EnvironmentName}/ActiveDirectorySyncAPI/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/Groups/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/ HTTP/1.1
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==

Example response

HTTP/1.1 200 OK
DELETE
/{EnvironmentName}/ActiveDirectorySyncAPI/{ObjectID}/Groups/{ObjectID}
Delete group in the given group

Name

Located

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

 
string

Target Group ObjectId

Path

ObjectId of the target group

Yes

 
Guid
Group ObjectId  Path ObjectId of the group  Yes 
Guid

Responses

Code

Description

Schema

200

The membership is deleted

  

400

Validation issue

ApiErrorResponse

401, 403

Authentication issue

 

Example request

DELETE https://workspace365instance.url/{EnvironmentName}/ActiveDirectorySyncAPI/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/Groups/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a HTTP/1.1
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==

Example response

HTTP/1.1 200 OK
PUT
/{EnvironmentName}/ActiveDirectorySyncAPI/Users/{ObjectID}/ProfilePicture
Put the profile picture of the user
Note: User Profile Picture is not tested/documented yet.

Multipart form

PUT https://{WorkspaceUrl}/{EnvironmentName}/ActiveDirectorySyncAPI/Users/{ObjectID}/ProfilePicture
DELETE
/{EnvironmentName}/ActiveDirectorySyncAPI/Users/{ObjectID}/ProfilePicture
Delete the profile picture of the user
Note: User Profile Picture is not tested/documented yet.

Multipart form

DELETE https://{WorkspaceUrl}/{EnvironmentName}/ActiveDirectorySyncAPI/Users/{ObjectID}/ProfilePicture


Authentication

Each request to the API should be authenticated with the token generated on the Active Directory settings page. Each environment requires its own token.

For authentication use the standard HTTP Authorization header with "Basic" authentication scheme and token base64 encoded as credentials:

Authorization: Basic base64({token}:)

E.g. Authorization:

Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==
Make sure to use the Sync API authentication token and encode this to Base64 formate e.g. here. Keep in mind that you need to encode the token including the semicolomn :. For example:
Token: 4613e4c6-aa59-45d0-88c9-c99feddf3959
Text to encode: 4613e4c6-aa59-45d0-88c9-c99feddf3959:
Result: NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==

Back to top

Was this article helpful?

Have more questions? Submit a request

Related articles

Contact


Phone: +31 (0)30 - 711 67 25
WhatsApp: +31 (0)6 -23 68 47 23

Berencamperweg 6D
3861MC Nijkerk

About us


Workspace 365
Terms and conditions
SLA
Latest version:

Follow us