Follow

API Documentation

 
  1. Introduction
  2. Prerequisites
    1. Enable API
    2. ProvisioningKey
  3. Endpoints
    1. Environment
    2. Licensing
    3. Template
    4. Users
    5. Email (Exchange)
    6. SharePoint
    7. Integration Credentials
    8. Domain
    9. ActiveDirectorySync
    10. ActivityFeed
    11. Business Apps (deprecated)

Introduction

The Workspace 365 Provisioning API is intended for provisioning and managing Workspace 365 resources. The 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.

Prerequisites The API needs to be enabled in Workspace 365. Some API's can be enabled via the GUI but most only via the config file on instance level.

 

Prerequisites

In order to access the Provisioning API, a so called Provisioning Key needs to be provided with each request. The Provisioning Key is provided via the value of a header called ProvisioningKey. An extra header is provided with every request X-Requested-With: XMLHttpRequest

There is no GUI or a way to view the API from the workspace. We describe the available endpoints and their data objects per resource type. Included in each endpoint is an example of the request. These examples assume Workspace 365 has the following settings:


Please note that this are example values. Please check your own values on your own instance.

Back to top

 

Provisioning API Enabled

Is used to indicate whether the Provisioning API is enabled. This option is only available if you're hosting workspace yourself.

This can be found in NDAW.Html.Front.config with the name ProvisioningApiEnabled and should be set to either TRUEor FALSE, e.g.:

<setting name="ProvisioningApiEnabled" serializeAs="String">
    <value>TRUE</value>
</setting>

 

ProvisioningKey

Is used to indicate the value of the Provisioning Key which is used to authenticate to the API.

This can be found in NDAW.Html.Front.config with the name ProvisioningKey and should be set to a non-empty string value, e.g.:

<setting name="ProvisioningKey" serializeAs="String">
       <value>00000000-0000-0000-0000-000000000000</value>
</setting>
Looking for the ProvisioningsKey and you're hosted? Please raise a ProvisioningsKey ticket and we'll help you out!

Back to top

 

Endpoints

Environment

POST
/Provisioning/Environment/?version=2.0
Creates an Environment and user with administrator privileges with temporary password. Version 2

Name

Located in

Description

Required

Environment

Body

Environment to create

Yes

 

Schema:
{ 
EmailAddress:
string (email)
Email address of the admin

EnvironmentName:
 string
Name of the environment

FirstName:
 string
First name of the admin

LastName:
 string
Last name of the admin
}

 

Code

Description

Schema

200

Name of the created Environment. This value can differ with the entered data since it is sanitized.

{
Id:
string (in GUID format)
Id of a newly created environment

EnvironmentName:
string
Name of the created environment.

TemporaryPassword:
string
Temporary password of created administrator
}

400

Array of Validation Results

[ValidationResult]

403

The Provisioning Key in the configuration is not defined or empty. The Provisioning API is not enabled in the configuration. The Provisioning Key in the header does not match the configured value  

500

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

 

 

Example

POST https://workspace365instance.url/Provisioning/Environment/?version=2.0 HTTP/1.1
Accept: application/json
Content-Length: 148
Content-Type: application/json
ProvisioningKey: 00000000-0000-0000-0000-000000000000
Host: yourworkspace365instance.url
X-Requested-With: XMLHttpRequest {
  "EnvironmentName": "{EnvironmentName}",
  "EmailAddress": "admin@example.com",
  "FirstName": "Admin",
  "LastName": "-"
}

 

POST
/Provisioning/Environment/Validate
Validates if the given Environment is valid for creating an Environment with Administrator user

 

Is NOT available when UseEmptyEnvironment or UseUserLicenses is set to TRUE

 

Name

Located in

Description

Required

Environment

Body

Environment to create

Yes

 

Schema

{
EmailAddress:
 string (email)
Email address of the admin
EnvironmentName:
 string

Name of the environment
FirstName:
 string

First name of the admin
LastName:
 string

Last name of the admin
Password:
 string (password)

Password of the admin }

 

Responses

Code

Description

Schema

200

Name of the created Environment

 string

400

Array of Validation Results

[ValidationResult]

403

The Provisioning Key in the configuration is not defined or empty.
The Provisioning API is not enabled in the configuration.
The Provisioning Key in the header does not match the configured value

 

500

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

 


Example

POST https://workspace365instance.url/Provisioning/Environment/Validate/ HTTP/1.1
Accept: application/json Content-Length: 148 Content-Type: application/json ProvisioningKey: 00000000-0000-0000-0000-000000000000 Host: yourworkspace365instance.url X-Requested-With: XMLHttpRequest  {   "EnvironmentName": "{EnvironmentName}",   "EmailAddress": "admin@example.com",   "Password": "qwerty",   "FirstName": "Admin",   "LastName": "-" }

 

PUT
/Provisioning/Environment/{EnvironmentName}/Activate
Activates the Environment

Name

Located in

Description

Required

EnvironmentName

Path

Name of the Environment

Yes

 

Schema

string 

 

Responses

Code

Description

Schema

200

The Environment was set to active

 string

403

The Provisioning Key in the configuration is not defined or empty.
The Provisioning API is not enabled in the configuration.
The Provisioning Key in the header does not match the configured value

[ValidationResult]

404

The resource is not found

 

411

The header “Content-Length: 0” is missing

 

500

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

 


Example

PUT https://workspace365instance.url/Provisioning/Environment/{EnvironmentName}/Activate/ HTTP/1.1
Accept: application/json
Content-Length: 0
ProvisioningKey: 00000000-0000-0000-0000-000000000000
Host: yourworkspace365instance.url
X-Requested-With: XMLHttpRequest

 

PUT
/Provisioning/Environment/{EnvironmentName}/Deactivate
Deactivates the Environment

Name

Located in

Description

Required

EnvironmentName

Path

Name of the Environment

Yes

 

Responses

Code

Description

Schema

200

The Environment was set to active

 string

403

The Provisioning Key in the configuration is not defined or empty.
The Provisioning API is not enabled in the configuration.
The Provisioning Key in the header does not match the configured value

[ValidationResult]

404

The resource is not found

 

411

The header “Content-Length: 0” is missing

 

500

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

 

 

Example

PUT https://workspace365instance.url/Provisioning/Environment/{EnvironmentName}/Deactivate/ HTTP/1.1
Accept: application/json
Content-Length: 0
ProvisioningKey: 00000000-0000-0000-0000-000000000000
Host: yourworkspace365instance.url
X-Requested-With: XMLHttpRequest

 

DELETE
/Provisioning/Environment/{EnvironmentName}/
Deletes the Environment

Name

Located in

Description

Required

EnvironmentName

Path

Name of the Environment

Yes

 

Schema

string 

 

Responses

Code

Description

Schema

200

The Environment was deleted

 string

403

The Provisioning Key in the configuration is not defined or empty.
The Provisioning API is not enabled in the configuration.
The Provisioning Key in the header does not match the configured value

[ValidationResult]

404

The resource is not found

 

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

 

Example

DELETE https://workspace365instance.url/Provisioning/Environment/{EnvironmentName}/ HTTP/1.1
Accept: application/json
ProvisioningKey: 00000000-0000-0000-0000-000000000000
Host: yourworkspace365instance.url
X-Requested-With: XMLHttpRequest
  

 

GET
/Provisioning/Environment/
Gets a list containing the environments

Responses

Code

Description

Schema

200

The environments

[
Environment {
name:
string
The name of the environment
isActive:
boolean
Whether the environment is active
creationDate:
date
When the environment was created
}
]
403 The Provisioning Key in the configuration is not defined or empty.
The Provisioning API is not enabled in the configuration.
The Provisioning Key in the header does not match the configured value
 

500

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

 

Example

GET https://workspace365instance.url/Provisioning/Environment/ HTTP/1.1
Accept: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

 

Back to top

 

Licensing

GET
/Provisioning/{EnvironmentName}/Licensing/?version=2.0
Gets the User Licenses summary

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

 

Responses

Code

Description

Schema

200

The Licenses summary

{
guest:
 integer
simplify:
 integer
adapt:
 integer
boost:
 integer
}

403

The Provisioning Key in the configuration is not defined or empty.
The Provisioning API is not enabled in the configuration.
The Provisioning Key in the header does not match the configured value

 

404

Resource is not found

 

500

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

 

 

Example

GET https://workspace365instance.url/Provisioning/{EnvironmentName}/Licensing/?version=2.0 HTTP/1.1
Accept: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

Back to top

 

Template

GET
/Provisioning/Environment/{EnvironmentName}/Export/
Exports environment workspace setup (installed apps, tile groups, etc)
If you want to import a template, no existing template should be present. So this is only applicable for new, not configured environments. Import and Export is only possible to the same hosting instance.

Name

Located in

Description

Schema

EnvironmentName

Path

Name of the Environment

string

 

Responses

Code

Description

Schema

200

The exported environment configuration

EnvironmentConfiguration

400

Validation issue, check error response data format

ApiErrorResponse

401, 403

  • The Provisioning Key in the configuration is not defined or empty.
  • The Provisioning API is not enabled in the configuration.
  • The Provisioning Key in the header does not match the configured value

 

404 The resource is not found  
500 Internal server error. This could be caused by passing an incorrect data object  

 

Example request:

GET https://workspace365instance.url/Provisioning/Environment/{EnvironmentName}/Export/ HTTP/1.1
Accept: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

 

Example response:

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

{
"exportImportInfo": {
"hostingInstanceId": "1cfaad2e-1b58-4dbe-5312-163bbd8a6bd8",
"version": 1,
"exportDateTime": "2019-10-30T15:25:58.9942878+01:00"
},
"appImages": [],
"tileGroups": [
{
"name": "How To",
"type": 2,
"order": 1,
"isNewTilesTarget": false,
"tiles": [
{
"installedAppId": 1,
"name": null,
"appImage": null,
"parameters": null,
"position": {
"column": 0,
"row": 0
},
"dimension": {
"columnSpan": 8,
"rowSpan": 8
},
"color": null
}
]
},
{
"name": "To-Do",
"type": 3,
"order": 1,
"isNewTilesTarget": false,
"tiles": [
{
"installedAppId": 2,
"name": null,
"appImage": null,
"parameters": null,
"position": {
"column": 0,
"row": 0
},
"dimension": {
"columnSpan": 8,
"rowSpan": 8
},
"color": null
}
]
}
],
"apps": [
{
"id": 1,
"appId": 1,
"type": null,
"name": null,
"parameters": null,
"image": null,
"color": null,
"everyoneHasAccess": true,
"maintenanceWindow": null,
"conditionalAccessPolicy": null
},
{
"id": 2,
"appId": 2,
"type": null,
"name": null,
"parameters": null,
"image": null,
"color": null,
"everyoneHasAccess": true,
"maintenanceWindow": null,
"conditionalAccessPolicy": null
}
]
}
PUT
/Provisioning/Environment/{EnvironmentName}/Import/
Imports an environment configuration
If you want to import a template, no existing template should be present. So this is only applicable for new, not configured environments. Import and Export is only possible to the same hosting instance.

Name

Located in

Description

Schema

EnvironmentName

Path

Name of the Environment

string
Configuration Body The configuration created during the export
EnvironmentConfiguration

 

 

Responses

Code

Description

Schema

200

Success

 

400

Validation issue, check error response data format

ValidationResult

401, 403

  • The Provisioning Key in the configuration is not defined or empty.
  • The Provisioning API is not enabled in the configuration.
  • The Provisioning Key in the header does not match the configured value

 

404 The resource is not found  
500 Internal server error. This could be caused by passing an incorrect data object  

Example request:

PUT https://workspace365instance.url/Provisioning/Environment/{EnvironmentName}/Import/ HTTP/1.1
Accept: application/json
Content-Length: 23965
Content-Type: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

Example response:

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

Back to top

 

Users

POST
/Provisioning/{EnvironmentName}/User/
Creates a User

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

User

Body

User to create

Yes

{
        EmailAddress:
         string (email)
        Email address of the user
        
        FirstName:
         string
        First name of the user
        
        IsAdministrator:
         boolean
        Whether the user is an Administrator
        
        LastName:
         string
        Last name of the user
        
        Password:
         string (password)
        Password of the user
        
        CreateInOffice365:
         boolean
        Whether the user should be created in Office 365
}

 

Responses

Code

Description

Schema

200

The id of the created User

integer

400

Array of Validation Results

[ValidationResult]

403

The Provisioning Key in the configuration is not defined or empty.
The Provisioning API is not enabled in the configuration.
The Provisioning Key in the header does not match the configured value

 

404

Resource is not found

 

500

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

 

 

Example

POST https://workspace365instance.url/Provisioning/{EnvironmentName}/User/ HTTP/1.1
Accept: application/json
Content-Length: 176
Content-Type: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

{
  "EmailAddress": "userone@example.com",
  "Password": "qwerty",
  "FirstName": "User",
  "LastName": "One",
  "IsAdministrator": false,
  "CreateInOffice365": false
}
POST
/Provisioning/{EnvironmentName}/User/Validate/
Validates if the given User is valid for creating

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

User

Body

User to create

Yes

{
        EmailAddress:
         string (email)
        Email address of the user
        
        FirstName:
         string
        First name of the user
        
        IsAdministrator:
         boolean
        Whether the user is an Administrator
        
        LastName:
         string
        Last name of the user
        
        Password:
         string (password)
        Password of the user
        
        CreateInOffice365:
         boolean
        Whether the user should be created in Office 365
} 

 

Responses

Code

Description

Schema

200

The id of the created User

integer

400

Array of Validation Results

[ValidationResult]

403

The Provisioning Key in the configuration is not defined or empty.
The Provisioning API is not enabled in the configuration.
The Provisioning Key in the header does not match the configured value

 

404

Resource is not found

 

500

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

 

 

Example

POST https://workspace365instance.url/Provisioning/{EnvironmentName}/User/ HTTP/1.1
Accept: application/json
Content-Length: 176
Content-Type: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

{
  "EmailAddress": "userone@example.com",
  "Password": "qwerty",
  "FirstName": "User",
  "LastName": "One",
  "IsAdministrator": false,
  "CreateInOffice365": false
}
PUT
/Provisioning/{EnvironmentName}/User/{EmailAddress}/
Updates a User

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

EmailAddress

Path

Email address of the User

Yes

string

User

Body

User to create

Yes

{
        EmailAddress:
         string (email)
        Email address of the user
        
        FirstName:
         string
        First name of the user
        
        IsAdministrator:
         boolean
        Whether the user is an Administrator
        
        LastName:
         string
        Last name of the user
        
        Password:
         string (password)
        Password of the user
}

 

Responses

Code

Description

Schema

200

The User was updated

 

400

Array of Validation Results

[ValidationResult]

403

The Provisioning Key in the configuration is not defined or empty.
The Provisioning API is not enabled in the configuration.
The Provisioning Key in the header does not match the configured value

 

404

The resource is not found

 

500

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

 


Example

PUT https://workspace365instance.url/Provisioning/{EnvironmentName}/User/userone@example.com/ HTTP/1.1
Accept: application/json
Content-Length: 145
Content-Type: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

{
  "EmailAddress": "userone@example.com",
  "Password": "qwert",
  "FirstName": "User",
  "LastName": "Once",
  "IsAdministrator": false
}
PUT
/Provisioning/{EnvironmentName}/User/{EmailAddress}/Validate/
Validates if the given User is valid for update

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

EmailAddress

Path

Email address of the User

Yes

string

User

Body

User to update

Yes

{
        EmailAddress:
         string (email)
        Email address of the user
        
        FirstName:
         string
        First name of the user
        
        IsAdministrator:
         boolean
        Whether the user is an Administrator
        
        LastName:
         string
        Last name of the user
        
        Password:
         string (password)
        Password of the user
}

 

Responses

Code

Description

Schema

200

The entered User is valid for update

 

400

Array of Validation Results

[ValidationResult]

403

The Provisioning Key in the configuration is not defined or empty.
The Provisioning API is not enabled in the configuration.
The Provisioning Key in the header does not match the configured value

 

404

The resource is not found

 

500

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

 


Example

PUT https://workspace365instance.url/Provisioning/{EnvironmentName}/User/userone@example.com/ HTTP/1.1
Accept: application/json
Content-Length: 145
Content-Type: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

{
  "EmailAddress": "userone@example.com",
  "Password": "qwert",
  "FirstName": "User",
  "LastName": "Once",
  "IsAdministrator": false
}
PUT
/Provisioning/{EnvironmentName}/User/{EmailAddress}/Activate/
Activates the User

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

EmailAddress

Path

Email address of the User

Yes

string

 

Responses

Code

Description

Schema

200

The user was set to Active

 

400

Array of Validation Results

[ValidationResult]

403

The Provisioning Key in the configuration is not defined or empty.
The Provisioning API is not enabled in the configuration.
The Provisioning Key in the header does not match the configured value

 

404

The resource is not found

 

411

The header “Content-Length: 0” is missing

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

 

Example

PUT https://workspace365instance.url/Provisioning/{EnvironmentName}/User/userone@example.com/Activate/ HTTP/1.1
Accept: application/json
Content-Length: 0
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest
PUT
/Provisioning/{EnvironmentName}/User/{EmailAddress}/Deactivate/
Deactivates the User

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

EmailAddress

Path

Email address of the User

Yes

string

 

Responses

Code

Description

Schema

200

The user was set to Deactivate

 

403

The Provisioning Key in the configuration is not defined or empty.
The Provisioning API is not enabled in the configuration.
The Provisioning Key in the header does not match the configured value

 

404

The resource is not found

 

411

The header “Content-Length: 0” is missing

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

 

Example

PUT https://workspace365instance.url/Provisioning/{EnvironmentName}/User/userone@example.com/Deactivate/ HTTP/1.1
Accept: application/json
Content-Length: 0
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest
DELETE
/Provisioning/{EnvironmentName}/User/{EmailAddress}/
Deletes the User

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

EmailAddress

Path

Email address of the User

Yes

string

 

Responses

Code

Description

Schema

200

The user was Deleted

 

403

The Provisioning Key in the configuration is not defined or empty.
The Provisioning API is not enabled in the configuration.
The Provisioning Key in the header does not match the configured value

 

404

The resource is not found

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

 

Example

DELETE https://workspace365instance.url/Provisioning/{EnvironmentName}/User/userone@example.com/ HTTP/1.1
Accept: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

Back to top

 

Email (Exchange)

PUT
/Provisioning/{EnvironmentName}/ExchangeSettings/
Sets the exchange services settings
Please be aware that the PowerShellUrl is deprecated. This endpoint will remain working, but without ability of setting the PowerShellUrl. See this article for more info.

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string
Settings Body Exchange settings to use Yes
{
PowerShellUrl:
  string (url)
Url of the Exchange server (the EWS endpoint)
ServerType:
  enum
The server type of the exchange server.
-	Office365
-	OnPremises
DefaultEwsUrl:
  string (url)
Default EWS address used when performing 
“Auto discover”.
 When left out this property is ignored
}

 

Responses

Code

Description

Schema

200

Success

 

400

Array of Validation Results

[ValidationResult]

403

The Provisioning Key in the configuration is not defined or empty.
The Provisioning API is not enabled in the configuration.
The Provisioning Key in the header does not match the configured value

 

404

Resource is not found

 

500

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

 

 

Example

PUT https://workspace365instance.url/Provisioning/{EnvironmentName}/ExchangeSettings/ HTTP/1.1
Accept: application/json
Content-Length: 178
Content-Type: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

{
  "PowerShellUrl": "https://outlook.office365.com/powershell-liveid/",
  "ServerType": "Office365",
  "DefaultEwsUrl": "https://outlook.office365.com/ews/exchange.asmx"
}

Back to top

 

SharePoint

PUT
/Provisioning/{EnvironmentName}/SharePointSettings/
Sets the SharePoint services settings

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string
Settings Body SharePoint settings to use Yes
{
  DefaultUrl:
    string (url)
  Default SharePoint address used when 
  performing “Auto discover”. 
  When left out this property is ignored
  
  AuthenticationType:
    enum
  The authentication type used when 
  connecting to SharePoint.
  -	Online
  -	ActiveDirectoryFederationServices
  -	OnPremisesMixed
  -	OAuth2
}

 

Responses

Code

Description

Schema

200

Success

 
400 Array of Validation Results
[ValidationResult]

403

The Provisioning Key in the configuration is not defined or empty.
The Provisioning API is not enabled in the configuration.
The Provisioning Key in the header does not match the configured value

 

404

Resource is not found

 

500

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

 

 

Example

PUT https://workspace365instance.url/Provisioning/{EnvironmentName}/SharePointSettings/ HTTP/1.1
Accept: application/json
Content-Length: 72
Content-Type: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

{
  "DefaultUrl": "https://example.sharepoint.com",
  "AuthenticationType": "Online"
}

Back to top

 

Integration Credentials

Quick reference:
Settings -> API Settings -> Integration credentials API
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 4613e4c6-aa59-45d0-88c9-c99feddf3959
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, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

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, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

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

 

Domain

GET
/Provisioning/{EnvironmentName}/Domain/
Gets a list containing the domains registered with Office 365

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

 

Responses

Code

Description

Schema

200

The domains registered with Office 365

[
Domain 
{
isDefault:
  boolean
Whether it is the default domain

name:
  string
The domain name
}
]

403

The Provisioning Key in the configuration is not defined or empty.
The Provisioning API is not enabled in the configuration.
The Provisioning Key in the header does not match the configured value

 

404

Resource is not found

 

500

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

 

 

Example

GET https://workspace365instance.url/Provisioning/{EnvironmentName}/Domain/ HTTP/1.1
Accept: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

Back to top

 

ActiveDirectorySync

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

Prerequisites

To be able to use the API, the following conditions should be met:

  • Active Directory Sync token is enabled in the Workspace 365 environment

The environment administrator can get the API token on the Active Directory settings page, and the authentication token will be generated.

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==

Authentication response codes

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

Responses

Code

Description

Schema

401

One of the following applies:

Authorization header is missing
Authentication scheme is incorrect
Token is invalid for the environment

 

403

The Integration credentials API is not enabled for the environment

 

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.

 

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, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

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, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

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, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

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, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

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, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

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, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

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, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

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, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

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

Back to top

 

ActivityFeed API

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

Prerequisites

To be able to use the API, the following conditions should be met:

  • At least one Activity Feed API setting is configured in Workspace 365 environment

Environment administrator can configure the API on the API settings page.

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

Authentication response codes

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

Responses

Code

Description

Schema

401

One of the following applies:

Authorization header is missing
Authentication scheme is incorrect
Token is invalid for the environment

 

403

The Activity Feed API is not configured for the environment, or the environment is inactive.

 

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.

ActivitySchema

{
"User": {
  "upn": "userone@example.com",
  "id": 1"
},
"Icon": {
  "Name": "my icon"
},
"Title": "Test activity",
"Url": "https://workspace365.net",
"Color": {
  "Kind": "Custom",
  "Value": "#00ff00"
  }
}

Property

Type

Optional/Required

Description

User

User

Required

Specifies the user for the activity. Upn or id should be supplied.

Icon

Icon

Optional

Specifies the icon which is displayed in the activity. The default icon is displayed when no icon is specified. We make use of the icon name which can be found in the app store.

Title

String

Required

The title which is displayed in the activity feed.

Url

String

Required

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

Color

Color Object

Optional

The default color is used when not specified. Options are Primary, Header and Custom.

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.

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.

Color schema

{
  "Kind": "Custom",
  "Value": "#00ff00"
}

Property

Type

Optional/Required

Description

Kind

String

Required

Options are Primary, Header and Custom.

Value

String

Required when Kind is Custom

The Value property specifies a html color. The field is required when the Kind is Custom.

 

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

Authorization header is missing
Authentication scheme is incorrect
Token is invalid for the environment

 

500

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

 


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://workspace365.net",
  "Color": {
      "Kind": "Custom",
      "Value": "#00ff00"
  }
}


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

Authorization header is missing
Authentication scheme is incorrect
Token is invalid for the environment

 

500

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

 


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": "AllUsers"
  },
  "Data": {
      "Title": "Workspace 365 Website Activity",
      "Url": "https://workspace365.net",      
      "Icon": {
          "Name": "Phone"
      },
      "Color": {
          "Kind": "Custom",
          "Value": "#00ff00"
      }
  }
}


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"
        }
    },
    …
]

Back to top

 

Business Apps (deprecated)

POST
/Provisioning/{EnvironmentName}/BusinessAppApi/{BusinessAppName}
Create new Business App record

200

A record has been created successfully; check response data format

400

Validation issue; check error response data format

401, 403

Authentication issue, check potential reasons

404

  • Cannot find a business app with supplied name
  • Business app is not installed
  • Business app is not enabled

 

Input data structure

Business App record properties are to be supplied in the JSON format, with property names corresponding to field names configured for the business app in Business App Builder:

{
        "{property name 1}": {value 1},
        "{property name 2}": {value 2},
        ...
        "{property name N}": {value N},
}

 

Extra properties supplied but not present on the business app will be ignored without any validation errors. It is possible to omit properties, provided the corresponding business app fields are not required. Currently, the default values configured in the business app are NOT applied in that case.

Fields of the following types should not be supplied to the API and will have empty values in the created record:

  • Link to a single business app record (Combobox (parent) in Business App Builder)
  • Link to multiple business app records (Gridview (child) in Business App Builder)
  • E-mail link
  • Folder link
  • User
  • Calculation

Fields of the following types should not be supplied to the API, and will have correctly generated values in the created record:

  • Autonumber

For properties which are not required, null can be used to indicate that a value is not present.

 

String properties

Values for the following fields are passed as a string according to the JSON specification:

  • Single line text
  • Multiline text
  • Rich text
  • Email

For example:

"Workspace 365"
"user@example.com"
"Some <b>bold</b> rich text"

 

Numeric properties

Integer field values are passed as a JSON number without fractional part, and is expected to be in the range of 32-bit signed integer:

42

Decimal field values are passed as JSON number, valid range and precision corresponds to that of a IEEE 754 double-precision floating point:

12.34

Percentage field values format is the same as decimal, e.g. 15.5% should be

15.5

 

Currency

Currency fields are to be passed as a JSON object having “Amount” property (a number), and a “Currency” property indicating an ISO 4217 currency code as a string. Currency should be in the list of currencies supported by Workspace 365.

Amount should be in the range of System.Decimal CLS type.

Example:

{"Amount": 499.99, "Currency": "EUR"}

 

Date and time properties

Date fields having ‘Date and time’ mode set in Business App Builder are expected to be strings in ISO 8601 format. If time zone is not specified, server time zone is assumed.

Examples:

"2017-03-30T08:25:21"
"2017-03-30T08:25:21+04:00"
"2017-03-30T08:25:21Z"

Date fields having ‘Date only’ mode set in Business App Builder are expected to be passed as a string in ISO 8601 format without a time portion. If the passed value has a time part, it will not result in error, but the time part will not be taken into account.

Example:

"2017-03-30"

Date fields having ‘Time only’ mode set in Business App Builder are expected to be strings in ISO 8601 without a date part. It implies 24-hours format.

Example:

"20:13:14"

 

Dropdown

Values for fields of type “Dropdown menu” are supplied as a JSON string corresponding to the text value of a desired item.

If no value needs to be selected, empty string (“”) shall be provided.
Examples (assuming “New”, “Approved”, “Done” dropdown configuration):

"Approved"
""

 

Checkbox

Values for fields of type “Checkbox list” are provided as a JSON array of strings corresponding to the text values of checked items.

If no values are selected, empty array shall be provided.

Examples (assuming “New”, “Approved”, “Done” dropdown configuration):

["New", "Approved"]
[]

 

Successful response

If Business App record has been created successfully, the response will be a JSON object containing a single property “id” which contains a Workspace 365 identifier of the created record. The identifier is a signed 32-bit integer number.

Example:

{“id”: 1034}

 

Error response

If a Business App record has not been created due to an incorrect input data, response will be a JSON object having “globalError” and “fieldErrors” properties.

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:

{
"globalError": null,
 "fieldErrors": {
  "Joining date": {
  "message": "Date format is incorrect"
  },
  "State": {
  "message": "Dropdown value not found"
  },
  "Lastname": {
  "message": "Is required"
  },
  "Email": {
  "message": "The email address is invalid"
  }
 }
}

 

 

Request and response examples

Successful request and response

Request:

POST https://workspace365instance.url/environment/BusinessAppApi/Employee HTTP/1.1
Host: yourworkspace365instance.url
Content-Type: application/json; charset=utf-8
Authorization: Workspace365 4613e4c6-aa59-45d0-88c9-c99feddf3959
{
      "Firstname": "John",
      "Lastname": "Doe",      
      "Email": "johndoe@example.com",      
      "Joining date": "2012-02-13",      
      "Capacity": 60,      
      "Rate": {     
      "Amount": 15.00,
      "Currency": "USD"
      },    
      "State": "Active",
      "Equipment": [ "Monitor", "Desktop" ],
      "Comments": "<p>something</p><b>bold<b>"
}

Response:

HTTP/1.1 200 OK
        Cache-Control: private
        Content-Type: application/json; charset=utf-8
        Server: Microsoft-IIS/10.0
        X-Powered-By: ASP.NET
        X-Frame-Options: SAMEORIGIN
        Date: Thu, 06 Apr 2017 14:39:54 GMT
        
{"id":5}

 

Successful request and response with some null values

Request:

POST https://workspace365instance.url/environment/BusinessAppApi/Employeee HTTP/1.1
        Host: yourworkspace365instance.url
        Content-Type: application/json; charset=utf-8
        Authorization: Workspace365 4613e4c6-aa59-45d0-88c9-c99feddf3959
        
        {
              "Firstname": "John",
              "Lastname": "Doe",
              "Email": "johndoe@example.com",
              "Joining date": null,
              "Capacity": 60,
              "Rate": null,
              "State": null,
              "Equipment": [ "Monitor", "Desktop" ],
              "Comments": "<p>something</p><b>bold<b>"
        }

Response:

HTTP/1.1 200 OK
        Cache-Control: private
        Content-Type: application/json; charset=utf-8
        Server: Microsoft-IIS/10.0
        X-Powered-By: ASP.NET
        X-Frame-Options: SAMEORIGIN
        Date: Tue, 11 Apr 2017 09:31:06 GMT
        
        {"id":8}

 

Failed global validation response

Request:

POST https://workspace365instance.url/environment/BusinessAppApi/Employee HTTP/1.1
        Host: yourworkspace365instance.url
        Content-Type: application/json; charset=utf-8
        Authorization: Workspace365 4613e4c6-aa59-45d0-88c9-c99feddf3959
        
        {
              "Firstname": "John",
              "Lastname": "Doe",
              "Email": "johndoe@example.com",
              "Joining date": "2012-02-13",
              "Capacity": 60,
              "Rate": {
                "Amount": 15.00,
                "Currency": "USD"
              },
              "State": "Active",
              "Equipment": [ "Monitor", "Desktop" ],
              "Comments": "<p>something</p><b>bold<b>"
        }

Response:

HTTP/1.1 403 Forbidden
        Cache-Control: private
        Content-Type: application/json; charset=utf-8
        Server: Microsoft-IIS/10.0
        X-Powered-By: ASP.NET
        X-Frame-Options: SAMEORIGIN
        Date: Thu, 06 Apr 2017 14:42:20 GMT
        
        {"globalError":{"message":"Business App isn't enabled"},"fieldErrors":null}

 

Failed fields validation response

Request:

POST https://workspace365instance.url/environment/BusinessAppApi/Employee HTTP/1.1
        Host: yourworkspace365instance.url
        Content-Type: application/json; charset=utf-8
        Authorization: Workspace365 4613e4c6-aa59-45d0-88c9-c99feddf3959
        
        {
              "Firstname": "John",
              "Email": "johndoe at example.com",
              "Joining date": "2012-13-13",
              "Capacity": 60,
              "Rate": {
                "Amount": 15.00,
                "Currency": "USD"
              },
              "State": "Invalid",
              "Equipment": [ "Monitor", "Desktop" ],
              "Comments": "<p>something</p><b>bold<b>"
        }

Response:

HTTP/1.1 400 Bad Request
        Cache-Control: private
        Content-Type: application/json; charset=utf-8
        Server: Microsoft-IIS/10.0
        X-Powered-By: ASP.NET
        X-Frame-Options: SAMEORIGIN
        Date: Thu, 06 Apr 2017 14:46:19 GMT
        
        {"globalError":null,"fieldErrors":{"Joining date":
{"message":"Error during converting data '2012-13-13' to type 'DateTime'"},
"State":{"message":"_ValueNotFound"},"Lastname":{"message":"Is required"},
"Email":{"message":"The email address is invalid"}}}

 

Failed fields validation response in a requested language

Request:

POST https://workspace365instance.url/environment/BusinessAppApi/Employee HTTP/1.1
        Host: yourworkspace365instance.url
        Content-Type: application/json; charset=utf-8
        Accept-Language: nl
        Authorization: Workspace365 4613e4c6-aa59-45d0-88c9-c99feddf3959
        
        {
              "Firstname": "John",
              "Email": "johndoe at example.com",
              "Joining date": "2012-11-13",
              "Capacity": 60,
              "Rate": {
                "Amount": 15.00,
                "Currency": "USD"
              },
              "State": "",
              "Equipment": [],
              "Comments": "<p>something</p><b>bold<b>"
        }

Response:

HTTP/1.1 400 Bad Request
        Cache-Control: private
        Content-Type: application/json; charset=utf-8
        Server: Microsoft-IIS/10.0
        X-Powered-By: ASP.NET
        X-Frame-Options: SAMEORIGIN
        Date: Thu, 06 Apr 2017 14:52:11 GMT
        
        {"globalError":null,"fieldErrors":{"Lastname":{"message":"Is vereist"},
"Email":{"message":"Dit e-mailadres is ongeldig"}}}

Back to top