Professional API¶
The Minddistrict API to access and modify professional data is accessible
under the sub-URL /p
of the API. In addition to the basic
user account API, the Professional API
provides:
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
.
Note
Depening on per-platform configuration, some fields are not available. Or, if made available they can be set to required as well. The presence of fields in the object serialization and what fields and values are allowed in the add and modification requests follow the platform’s configuration.
In other words, the examples below may contain not all fields that a specific platform enabled or requires or may contain fields that have bee n disabled in a certain platform configuration.
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 gAAAAABgZBtPh6WxHk6ZVMRNlpozycJz0NO6OoHPDWTOK5IJPue55hF3EB829TOwvNYKu6sORVhTg1O8C4JRat_r7c_s3b7cXT4ZmuWGHsQ-c9MH-2MSyu1wbBeHDlm03ZahY37mNoLaiJ_mL5p0EjYs2vROcJboy0_KMu944oIf6mLmf-7GCu5tsobjm-qxj9M_dev04440
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: 3204
Content-Type: application/json;charset=UTF-8
{
"@items": [
{
"@changes": {
"creation_time": "2021-03-31T06:48:49",
"modification_time": "2021-03-31T06:48:49"
},
"@type": "http://ns.minddistrict.com/professional",
"@url": "https://customer.minddistrict.com/api/2/p/25a4dd7130d14824a7b97eb5b6a2633c",
"active": true,
"description": null,
"email": "tina@example.com",
"external_source": null,
"first_name": "Tina",
"id": "tina123456",
"infix": "",
"labels": null,
"last_name": "Turner",
"name": "Tina Turner",
"picture": null
},
{
"@changes": {
"creation_time": "2021-03-31T06:48:47",
"modification_time": "2021-03-31T06:48:49"
},
"@type": "http://ns.minddistrict.com/professional",
"@url": "https://customer.minddistrict.com/api/2/p/3db8f91e6bf34ea3987997051ad08dc4",
"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": "2021-03-31T06:48:48",
"modification_time": "2021-03-31T06:48:49"
},
"@type": "http://ns.minddistrict.com/professional",
"@url": "https://customer.minddistrict.com/api/2/p/501428e2f3e34bf2a9b49cc9f22e1ddb",
"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": "2021-03-31T06:48:47",
"modification_time": "2021-03-31T06:48:48"
},
"@type": "http://ns.minddistrict.com/professional",
"@url": "https://customer.minddistrict.com/api/2/p/5dfc4b2b72d143c9beee89e9a0cb8c0f",
"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/5dfc4b2b72d143c9beee89e9a0cb8c0f/preferences/picture/picture/61368575c0f24c7e9c996455fa02dc1c"
}
}
],
"@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 gAAAAABgZBtPh6WxHk6ZVMRNlpozycJz0NO6OoHPDWTOK5IJPue55hF3EB829TOwvNYKu6sORVhTg1O8C4JRat_r7c_s3b7cXT4ZmuWGHsQ-c9MH-2MSyu1wbBeHDlm03ZahY37mNoLaiJ_mL5p0EjYs2vROcJboy0_KMu944oIf6mLmf-7GCu5tsobjm-qxj9M_dev04440
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/e0c33886e9cf4c3096621abb43d94d91
{
"@changes": {
"creation_time": "2021-03-31T06:48:56",
"modification_time": "2021-03-31T06:48:56"
},
"@type": "http://ns.minddistrict.com/professional",
"@url": "https://customer.minddistrict.com/api/2/p/e0c33886e9cf4c3096621abb43d94d91",
"active": true,
"description": null,
"email": "tinker@example.com",
"external_source": "3db8f91e6bf34ea3987997051ad08dc4",
"first_name": "Tinker",
"id": "thinker45",
"infix": "",
"labels": null,
"last_name": "Bell",
"name": "Tinker Bell",
"picture": null
}
Note
Contrary to the Add client endpoint, no welcome email is sent when adding a professional. You can use the basic user account API endpoint to trigger an welcome email explicitely.
View a professional¶
To view a professional send a GET request to the URL of the professional:
GET /api/2/p/3db8f91e6bf34ea3987997051ad08dc4 HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABgZBtPh6WxHk6ZVMRNlpozycJz0NO6OoHPDWTOK5IJPue55hF3EB829TOwvNYKu6sORVhTg1O8C4JRat_r7c_s3b7cXT4ZmuWGHsQ-c9MH-2MSyu1wbBeHDlm03ZahY37mNoLaiJ_mL5p0EjYs2vROcJboy0_KMu944oIf6mLmf-7GCu5tsobjm-qxj9M_dev04440
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: 1825
Content-Type: application/json;charset=UTF-8
{
"@changes": {
"creation_time": "2021-03-31T06:48:47",
"modification_time": "2021-03-31T06:48:49"
},
"@links": [
{
"name": "activation",
"url": "https://customer.minddistrict.com/api/2/p/3db8f91e6bf34ea3987997051ad08dc4/activation"
},
{
"name": "application",
"url": "https://customer.minddistrict.com/api/2"
},
{
"name": "conversations",
"url": "https://customer.minddistrict.com/api/2/p/3db8f91e6bf34ea3987997051ad08dc4/conversations"
},
{
"name": "groups",
"url": "https://customer.minddistrict.com/api/2/p/3db8f91e6bf34ea3987997051ad08dc4/groups"
},
{
"name": "logout",
"url": "https://customer.minddistrict.com/api/2/p/3db8f91e6bf34ea3987997051ad08dc4/logout"
},
{
"name": "roles",
"url": "https://customer.minddistrict.com/api/2/p/3db8f91e6bf34ea3987997051ad08dc4/roles"
},
{
"name": "tasks",
"url": "https://customer.minddistrict.com/api/2/p/3db8f91e6bf34ea3987997051ad08dc4/tasks"
},
{
"name": "tasks.items",
"url": "https://customer.minddistrict.com/api/2/p/3db8f91e6bf34ea3987997051ad08dc4/tasks/items"
}
],
"@type": "http://ns.minddistrict.com/professional",
"@url": "https://customer.minddistrict.com/api/2/p/3db8f91e6bf34ea3987997051ad08dc4",
"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/3db8f91e6bf34ea3987997051ad08dc4 HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABgZBtPh6WxHk6ZVMRNlpozycJz0NO6OoHPDWTOK5IJPue55hF3EB829TOwvNYKu6sORVhTg1O8C4JRat_r7c_s3b7cXT4ZmuWGHsQ-c9MH-2MSyu1wbBeHDlm03ZahY37mNoLaiJ_mL5p0EjYs2vROcJboy0_KMu944oIf6mLmf-7GCu5tsobjm-qxj9M_dev04440
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/3db8f91e6bf34ea3987997051ad08dc4/groups HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABgZBtPh6WxHk6ZVMRNlpozycJz0NO6OoHPDWTOK5IJPue55hF3EB829TOwvNYKu6sORVhTg1O8C4JRat_r7c_s3b7cXT4ZmuWGHsQ-c9MH-2MSyu1wbBeHDlm03ZahY37mNoLaiJ_mL5p0EjYs2vROcJboy0_KMu944oIf6mLmf-7GCu5tsobjm-qxj9M_dev04440
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/3db8f91e6bf34ea3987997051ad08dc4/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/3db8f91e6bf34ea3987997051ad08dc4/groups HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABgZBtPh6WxHk6ZVMRNlpozycJz0NO6OoHPDWTOK5IJPue55hF3EB829TOwvNYKu6sORVhTg1O8C4JRat_r7c_s3b7cXT4ZmuWGHsQ-c9MH-2MSyu1wbBeHDlm03ZahY37mNoLaiJ_mL5p0EjYs2vROcJboy0_KMu944oIf6mLmf-7GCu5tsobjm-qxj9M_dev04440
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/3db8f91e6bf34ea3987997051ad08dc4/groups HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABgZBtPh6WxHk6ZVMRNlpozycJz0NO6OoHPDWTOK5IJPue55hF3EB829TOwvNYKu6sORVhTg1O8C4JRat_r7c_s3b7cXT4ZmuWGHsQ-c9MH-2MSyu1wbBeHDlm03ZahY37mNoLaiJ_mL5p0EjYs2vROcJboy0_KMu944oIf6mLmf-7GCu5tsobjm-qxj9M_dev04440
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/3db8f91e6bf34ea3987997051ad08dc4/roles HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABgZBtPh6WxHk6ZVMRNlpozycJz0NO6OoHPDWTOK5IJPue55hF3EB829TOwvNYKu6sORVhTg1O8C4JRat_r7c_s3b7cXT4ZmuWGHsQ-c9MH-2MSyu1wbBeHDlm03ZahY37mNoLaiJ_mL5p0EjYs2vROcJboy0_KMu944oIf6mLmf-7GCu5tsobjm-qxj9M_dev04440
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/3db8f91e6bf34ea3987997051ad08dc4/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/3db8f91e6bf34ea3987997051ad08dc4/roles HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABgZBtPh6WxHk6ZVMRNlpozycJz0NO6OoHPDWTOK5IJPue55hF3EB829TOwvNYKu6sORVhTg1O8C4JRat_r7c_s3b7cXT4ZmuWGHsQ-c9MH-2MSyu1wbBeHDlm03ZahY37mNoLaiJ_mL5p0EjYs2vROcJboy0_KMu944oIf6mLmf-7GCu5tsobjm-qxj9M_dev04440
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/3db8f91e6bf34ea3987997051ad08dc4/activation HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABgZBtPh6WxHk6ZVMRNlpozycJz0NO6OoHPDWTOK5IJPue55hF3EB829TOwvNYKu6sORVhTg1O8C4JRat_r7c_s3b7cXT4ZmuWGHsQ-c9MH-2MSyu1wbBeHDlm03ZahY37mNoLaiJ_mL5p0EjYs2vROcJboy0_KMu944oIf6mLmf-7GCu5tsobjm-qxj9M_dev04440
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.