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 API

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.

Professional API ¶

Professional JSON object ¶

Listing professionals ¶

Adding a new professional ¶

View a professional ¶

Editing a professional ¶

Managing the groups of a professional ¶

View the group memberships of a professional ¶

Set the group membership of a professional ¶

Managing the roles of a professional ¶

View the roles of a professional ¶

Set the roles of a professional ¶

Activating a professional ¶

Table of Contents

Previous topic

Next topic