Professional API ¶

The Minddistrict API to access and modify professional data is accessible under the sub-URL /p of the API.

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.

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: `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/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: `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/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.