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:

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.

File

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

-

List of 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: therapists, secretaries, supervisors, application-managers, data-analysts or data-officers

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: ith.Secretary, ith.Therapist, ith.Supervisor or ith.ApplicationManager

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.