Professional API¶
The Minddistrict API to access and modify professional data is accessible
under the sub-URL /p
of the API.
Contents
Professional JSON object¶
Information about professionals in the Minddistrict API is transferred as json objects containing the following information:
Name |
Value |
Explanation |
Value type |
Notes |
---|---|---|---|---|
first_name |
First name |
- |
String |
Required |
infix |
Infix |
- |
String |
|
last_name |
Last name |
- |
String |
Required |
active |
Active |
Uncheck to deactivate the user acount. The user can not log in to the platform as long as the account is inactive. |
Boolean |
Required |
external_source |
External source of information |
Name of the external information source or API user identifier. Can be empty. Should not be set by users nor API interaction. Based on this value and the corresponding configuration setting manual updates can be disallowed. |
String |
Read-only |
email |
Email address |
The email address is used as login name for the platform. It should be unique in the platform. It may not contain uppercase characters. |
String |
Required |
picture |
Profile picture |
You can upload a profile picture. |
Setting-dependent | |
id |
Professional identification |
Field for identification of the professional in the institution. This ID has to be unique within the platform. |
String |
Setting-dependent |
description |
Description |
Here you can introduce yourself. This text will be shown to your clients. |
String |
|
labels |
Labels |
- |
Setting-dependent | |
name |
Name |
- |
String |
Required, Read-only |
The @type
meta information for this object is: http://ns.minddistrict.com/professional
.
Listing professionals¶
To get a list of all professional objects send a GET request
to the API base URL with /p/items
appended:
GET /api/2/p/items HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsoGR1vEpJy1YxruDLmSE4j8aygZJM2ub-VkHaqu6feWX5kg4xGxpki5IBDsBZ-IZ5yNUp-7h4sJWgkPGB7URUflP5COCD2VKrZhVju7FS6tsfRwQUJ-9U9ITuEZyHxAIA7XMbRLZmPx-EJ8Gtmojya_bzmFwFXbX40YYtQHl4GXTV7lBY1aMwRfDewbzCeEkG8
The response will be a list of professional objects:
HTTP/1.0 200 Ok
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Content-Length: 2509
Content-Type: application/json;charset=UTF-8
{
"@items": [
{
"@changes": {
"creation_time": "2020-12-01T08:13:29",
"modification_time": "2020-12-01T08:13:30"
},
"@type": "http://ns.minddistrict.com/professional",
"@url": "https://customer.minddistrict.com/api/2/p/064f0d41ca2548fcb2ecdfebd70d6438",
"active": true,
"description": null,
"email": "percy@example.com",
"external_source": null,
"first_name": "Percy",
"id": "p1234",
"infix": "",
"labels": null,
"last_name": "Porker",
"name": "Percy Porker",
"picture": null
},
{
"@changes": {
"creation_time": "2020-12-01T08:13:28",
"modification_time": "2020-12-01T08:13:30"
},
"@type": "http://ns.minddistrict.com/professional",
"@url": "https://customer.minddistrict.com/api/2/p/35fb5c76bdf446f79aef960da609a39b",
"active": true,
"description": null,
"email": "peter@example.com",
"external_source": null,
"first_name": "Peter",
"id": null,
"infix": "",
"labels": [
"be6e40f0-a3b4-486b-a1c7-f9b97b483b00"
],
"last_name": "Pan",
"name": "Peter Pan",
"picture": null
},
{
"@changes": {
"creation_time": "2020-12-01T08:13:28",
"modification_time": "2020-12-01T08:13:28"
},
"@type": "http://ns.minddistrict.com/professional",
"@url": "https://customer.minddistrict.com/api/2/p/d07a8277bbd643deae28cc6348d2b7ff",
"active": true,
"description": null,
"email": "otto@example.com",
"external_source": null,
"first_name": "Otto",
"id": null,
"infix": "",
"labels": null,
"last_name": "Datum",
"name": "Otto Datum",
"picture": {
"@type": "link",
"content_type": "image/jpeg",
"filename": "../../fixtures/profile.jpg",
"size": 4488,
"url": "https://customer.minddistrict.com/api/2/p/d07a8277bbd643deae28cc6348d2b7ff/preferences/picture/picture/2a66eabe8ffd46989550fee2b0e5201a"
}
}
],
"@links": []
}
Adding a new professional¶
To add a new professional send a POST request to the API base
URL with /p
appended. Put the JSON encoded data for the
new professional in the body of the request:
POST /api/2/p HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsoGR1vEpJy1YxruDLmSE4j8aygZJM2ub-VkHaqu6feWX5kg4xGxpki5IBDsBZ-IZ5yNUp-7h4sJWgkPGB7URUflP5COCD2VKrZhVju7FS6tsfRwQUJ-9U9ITuEZyHxAIA7XMbRLZmPx-EJ8Gtmojya_bzmFwFXbX40YYtQHl4GXTV7lBY1aMwRfDewbzCeEkG8
Content-Length: 133
Content-Type: application/json
{
"active": true,
"email": "tinker@example.com",
"first_name": "Tinker",
"id": "thinker45",
"last_name": "Bell"
}
The response will return the newly created professional object:
HTTP/1.0 201 Created
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Content-Length: 572
Content-Type: application/json;charset=UTF-8
Location: https://customer.minddistrict.com/api/2/p/64a32e7107034b39affb715414c0892e
{
"@changes": {
"creation_time": "2020-12-01T08:13:34",
"modification_time": "2020-12-01T08:13:34"
},
"@type": "http://ns.minddistrict.com/professional",
"@url": "https://customer.minddistrict.com/api/2/p/64a32e7107034b39affb715414c0892e",
"active": true,
"description": null,
"email": "tinker@example.com",
"external_source": "35fb5c76bdf446f79aef960da609a39b",
"first_name": "Tinker",
"id": "thinker45",
"infix": "",
"labels": null,
"last_name": "Bell",
"name": "Tinker Bell",
"picture": null
}
View a professional¶
To view a professional send a GET request to the URL of the professional:
GET /api/2/p/35fb5c76bdf446f79aef960da609a39b HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsoGR1vEpJy1YxruDLmSE4j8aygZJM2ub-VkHaqu6feWX5kg4xGxpki5IBDsBZ-IZ5yNUp-7h4sJWgkPGB7URUflP5COCD2VKrZhVju7FS6tsfRwQUJ-9U9ITuEZyHxAIA7XMbRLZmPx-EJ8Gtmojya_bzmFwFXbX40YYtQHl4GXTV7lBY1aMwRfDewbzCeEkG8
The response will be the corresponding professional object:
HTTP/1.0 200 Ok
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Content-Length: 1657
Content-Type: application/json;charset=UTF-8
{
"@changes": {
"creation_time": "2020-12-01T08:13:28",
"modification_time": "2020-12-01T08:13:30"
},
"@links": [
{
"name": "activation",
"url": "https://customer.minddistrict.com/api/2/p/35fb5c76bdf446f79aef960da609a39b/activation"
},
{
"name": "application",
"url": "https://customer.minddistrict.com/api/2"
},
{
"name": "groups",
"url": "https://customer.minddistrict.com/api/2/p/35fb5c76bdf446f79aef960da609a39b/groups"
},
{
"name": "logout",
"url": "https://customer.minddistrict.com/api/2/p/35fb5c76bdf446f79aef960da609a39b/logout"
},
{
"name": "roles",
"url": "https://customer.minddistrict.com/api/2/p/35fb5c76bdf446f79aef960da609a39b/roles"
},
{
"name": "tasks",
"url": "https://customer.minddistrict.com/api/2/p/35fb5c76bdf446f79aef960da609a39b/tasks"
},
{
"name": "tasks.items",
"url": "https://customer.minddistrict.com/api/2/p/35fb5c76bdf446f79aef960da609a39b/tasks/items"
}
],
"@type": "http://ns.minddistrict.com/professional",
"@url": "https://customer.minddistrict.com/api/2/p/35fb5c76bdf446f79aef960da609a39b",
"active": true,
"description": null,
"email": "peter@example.com",
"external_source": null,
"first_name": "Peter",
"id": null,
"infix": "",
"labels": [
"be6e40f0-a3b4-486b-a1c7-f9b97b483b00"
],
"last_name": "Pan",
"name": "Peter Pan",
"picture": null
}
This endpoint is also reachable via auxiliary URLs.
Editing a professional¶
To modify a professional’s data send a PATCH request to the URL of the professional with the modification contained in the body:
PATCH /api/2/p/35fb5c76bdf446f79aef960da609a39b HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsoGR1vEpJy1YxruDLmSE4j8aygZJM2ub-VkHaqu6feWX5kg4xGxpki5IBDsBZ-IZ5yNUp-7h4sJWgkPGB7URUflP5COCD2VKrZhVju7FS6tsfRwQUJ-9U9ITuEZyHxAIA7XMbRLZmPx-EJ8Gtmojya_bzmFwFXbX40YYtQHl4GXTV7lBY1aMwRfDewbzCeEkG8
Content-Length: 29
Content-Type: application/json
{
"first_name": "Harry"
}
This endpoint is also reachable via auxiliary URLs.
Managing the groups of a professional¶
A professional can be a member of one or more groups in the Minddistrict platform. These can be modified through the API.
The groups are encoded in a json object that has these values:
Name |
Value |
Value type |
Notes |
---|---|---|---|
groups |
Groups |
List of choice: |
The @type
meta information for this object is: http://ns.minddistrict.com/user/groups
.
View the group memberships of a professional¶
To view the current group membership of a professional
send a GET request to the URL of the professional with
/groups
appended:
GET /api/2/p/35fb5c76bdf446f79aef960da609a39b/groups HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsoGR1vEpJy1YxruDLmSE4j8aygZJM2ub-VkHaqu6feWX5kg4xGxpki5IBDsBZ-IZ5yNUp-7h4sJWgkPGB7URUflP5COCD2VKrZhVju7FS6tsfRwQUJ-9U9ITuEZyHxAIA7XMbRLZmPx-EJ8Gtmojya_bzmFwFXbX40YYtQHl4GXTV7lBY1aMwRfDewbzCeEkG8
The response will be a groups object:
HTTP/1.0 200 Ok
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Content-Length: 271
Content-Type: application/json;charset=UTF-8
{
"@links": [],
"@type": "http://ns.minddistrict.com/user/groups",
"@url": "https://customer.minddistrict.com/api/2/p/35fb5c76bdf446f79aef960da609a39b/groups",
"groups": [
"application-managers",
"secretaries",
"therapists"
]
}
Set the group membership of a professional¶
To set the groups of a professional send a PATCH
request to the URL of the professional with /groups
appended. Insert a JSON object in the body of the
request containing the new list of groups for that
professional. Those groups will replace the current
groups.:
PATCH /api/2/p/35fb5c76bdf446f79aef960da609a39b/groups HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsoGR1vEpJy1YxruDLmSE4j8aygZJM2ub-VkHaqu6feWX5kg4xGxpki5IBDsBZ-IZ5yNUp-7h4sJWgkPGB7URUflP5COCD2VKrZhVju7FS6tsfRwQUJ-9U9ITuEZyHxAIA7XMbRLZmPx-EJ8Gtmojya_bzmFwFXbX40YYtQHl4GXTV7lBY1aMwRfDewbzCeEkG8
Content-Length: 79
Content-Type: application/json
{
"groups": [
"application-managers",
"secretaries"
]
}
One group is special: if the professional should be in the
group "counter-operators"
then they must also be a member
of one of "secretaries"
, "therapists"
or
"supervisors"
. If you try to add them to only the
"counter-operators"
group:
PATCH /api/2/p/35fb5c76bdf446f79aef960da609a39b/groups HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsoGR1vEpJy1YxruDLmSE4j8aygZJM2ub-VkHaqu6feWX5kg4xGxpki5IBDsBZ-IZ5yNUp-7h4sJWgkPGB7URUflP5COCD2VKrZhVju7FS6tsfRwQUJ-9U9ITuEZyHxAIA7XMbRLZmPx-EJ8Gtmojya_bzmFwFXbX40YYtQHl4GXTV7lBY1aMwRfDewbzCeEkG8
Content-Length: 53
Content-Type: application/json
{
"groups": [
"counter-operators"
]
}
The response is a 400 Bad Request error:
HTTP/1.0 400 Bad Request
Content-Length: 168
Content-Type: application/json;charset=UTF-8
{
"code": 400,
"extra": [
{
"message": "Unknown value.",
"name": "groups"
}
],
"message": "Invalid JSON input"
}
Managing the roles of a professional¶
Warning
Modifying the roles of a professional will be removed in a future version of the API. Please use the Groups functionality.
The concept of professional group memberships replaces the concept of roles in the Minddistrict platform. To retain backwards compatibility for current uses of the roles API, the API will translate the input and output of roles information into the corresponding groups.
The roles are encoded in a json object that has these values:
Name |
Value |
Value type |
Notes |
---|---|---|---|
roles |
Roles |
List of choice: |
Required |
additional_roles |
Additional roles |
List of choice: |
Required |
The @type
meta information for this object is: http://ns.minddistrict.com/user/roles
.
View the roles of a professional¶
To view the current roles of a professional send a GET
request to the URL of the professional with /roles
appended:
GET /api/2/p/35fb5c76bdf446f79aef960da609a39b/roles HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsoGR1vEpJy1YxruDLmSE4j8aygZJM2ub-VkHaqu6feWX5kg4xGxpki5IBDsBZ-IZ5yNUp-7h4sJWgkPGB7URUflP5COCD2VKrZhVju7FS6tsfRwQUJ-9U9ITuEZyHxAIA7XMbRLZmPx-EJ8Gtmojya_bzmFwFXbX40YYtQHl4GXTV7lBY1aMwRfDewbzCeEkG8
The response will be a role object:
HTTP/1.0 200 Ok
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Content-Length: 278
Content-Type: application/json;charset=UTF-8
{
"@links": [],
"@type": "http://ns.minddistrict.com/user/roles",
"@url": "https://customer.minddistrict.com/api/2/p/35fb5c76bdf446f79aef960da609a39b/roles",
"additional_roles": [],
"roles": [
"ith.Secretary",
"ith.ApplicationManager"
]
}
Set the roles of a professional¶
To set the roles of a professional send a PATCH request
to the URL of the professional with /roles
appended. Insert a JSON object in the body of the
request containing the new list of roles for that
professional. Those roles will replace the current
roles.:
PATCH /api/2/p/35fb5c76bdf446f79aef960da609a39b/roles HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsoGR1vEpJy1YxruDLmSE4j8aygZJM2ub-VkHaqu6feWX5kg4xGxpki5IBDsBZ-IZ5yNUp-7h4sJWgkPGB7URUflP5COCD2VKrZhVju7FS6tsfRwQUJ-9U9ITuEZyHxAIA7XMbRLZmPx-EJ8Gtmojya_bzmFwFXbX40YYtQHl4GXTV7lBY1aMwRfDewbzCeEkG8
Content-Length: 82
Content-Type: application/json
{
"roles": [
"ith.ApplicationManager",
"ith.Secretary"
]
}
Activating a professional¶
To activate or deactivate a professional send a POST request
to the URL of the professional with /activation
appended.
Insert a JSON object in the body of the request with the
relevant attributes:
POST /api/2/p/35fb5c76bdf446f79aef960da609a39b/activation HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsoGR1vEpJy1YxruDLmSE4j8aygZJM2ub-VkHaqu6feWX5kg4xGxpki5IBDsBZ-IZ5yNUp-7h4sJWgkPGB7URUflP5COCD2VKrZhVju7FS6tsfRwQUJ-9U9ITuEZyHxAIA7XMbRLZmPx-EJ8Gtmojya_bzmFwFXbX40YYtQHl4GXTV7lBY1aMwRfDewbzCeEkG8
Content-Length: 23
Content-Type: application/json
{
"active": false
}
The activation endpoint accepts the following parameters in the body of its request:
Name |
Value |
Explanation |
Value type |
Notes |
---|---|---|---|---|
active |
Active |
Uncheck to deactivate the user acount. The user can not log in to the platform as long as the account is inactive. |
Boolean |
Required |
When activating and deactivating a professional an email will be sent to inform them of this.