Export API

Warning

This feature is not yet complete and might be subject to more minor changes.

The export API let you export data from the Minddistrict platform.

Security

To use the export API you need to authenticate with either:

  • a token from a regular platform user which has either the role data officer or data analyst in the application,

  • a token from an API user which has either the role data officer or data analyst.

Users with the data officer can export all available data. Users with the data analyst role can only export data that does not contain or may contain any privacy sensitive information. The detail of which information is classified as sensitive is available here.

Export Job JSON object

Information about a specific export job in the Minddistrict API is transferred as json objects containing the following information:

Name

Value

Explanation

Value type

Notes

created

When the job was created

-

Date with time

Required
started

When the job was started

-

Date with time

Required
completed

When the job was completed

-

Date with time

Required
description

Job description

Human readable description for the job

String

Required
state

Job state

-

Choice: archived, cancelled, completed, failed, queued or started

Required, Read-only
user_id

User who created this job

Internal database identifier of the user who created this job

String

Required
error

Error if the job failed

-

JSON object

filename

Filename

Output filename

String

content_type

Content type

Content type of the output file

String

content_encoding

Content encoding

Content encoded of the output file

String

content_length

Content length

Content length of the output file in bytes

Integer

downloaded_on

When was this job downloaded

List of dates and times on which the job was downloaded

List of date with time

Required, Read-only
options

Options used for the job

-

JSON object

Required, Read-only

The @type meta information for this object is: http://ns.minddistrict.com/export/job.

The json object error contains:

Name

Value

Explanation

Value type

Notes

message

Reason

-

String

Required
extra

Extra information

-

List of mapping

The json object options contains:

Name

Value

Explanation

Value type

Notes

name

Export name

Select type of entries to include in the output

String

Required
properties

Properties

List of properties for each entries to include in the output

List of string

filters

Filters

List of filters to limit entries in the output

List of json object

parameters

Parameters

List of parameters to configure entries in the output

List of json object

combine

Combined exports

Additional options to combine exports with the entries in the output

List of json object

output_format

Output format

-

Choice: json, csv or xlsx

allow_files

Allow files to be included in the output

This will generate a ZIP file with the files in it

Boolean

The list of json objects filters contains:

Name

Value

Explanation

Value type

Notes

name

Property

Property to filter or query on

String

Required
value

Value

Value to filter or query with

String

Required
operator

Operator

Operator used to compare value with

String

Required

The list of json objects parameters contains:

Name

Value

Explanation

Value type

Notes

name

Property

Property to filter or query on

String

Required
value

Value

Value to filter or query with

String

Required
operator

Operator

Operator used to compare value with

String

Required

The list of json objects combine contains:

Name

Value

Explanation

Value type

Notes

name

Export name

Export name to combine entries with

String

Required
properties

Properties

List of properties to use in the combination for each entry

List of string

When created, the state of an export job is pending. If the export fails, the state gets updated to failed. If the export succeed, the state gets updated to ready. At that moment the data can be downloaded. After 24 hours, the job will be archived: the data can no longer be downloaded, but the information about the job will stay available.

Note on the export job options JSON object

  • Available properties, filters, parameters and combined export varies for each individual available export. A detailed explanation of what is available for which export is available here.

  • More information about the output formats is available here.

Creating a new export job

To create the actually export job, send a POST request to the API base URL with /export. Insert a JSON object in the body of the request with the desired job options:

POST /api/2/export HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABgZBtQGT5-SuaUwo1fqjvJl3M36EtHGk69P-AdJqzV2_nPONZu_-051ybF1b3ez0mwJ8_QfGd1ltewjWedLOFUndTRWugtttJmJ8d-ZB0Tb34o8m-prIAPUj0uSCw2Mz2ABUOlEDz56sJ-MVqlZ4OZpIVgOsrl5nyGQum4v3KPPMeGFT6oR5fWWDk0jusJXPoZFvOW
Content-Length: 24
Content-Type: application/json

{
    "name": "client"
}

The response will be a export job object:

HTTP/1.0 201 Created
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Content-Length: 870
Content-Type: application/json;charset=UTF-8
Location: https://customer.minddistrict.com/api/2/export/1617173334642797

{
    "@links": [
        {
            "name": "cancel",
            "url": "https://customer.minddistrict.com/api/2/export/1617173334642797/cancel"
        }
    ],
    "@type": "http://ns.minddistrict.com/export/job",
    "@url": "https://customer.minddistrict.com/api/2/export/1617173334642797",
    "completed": null,
    "content_encoding": null,
    "content_length": 0,
    "content_type": null,
    "created": "2021-03-31T06:48:54",
    "description": "Export job for \"Clients\"",
    "downloaded_on": [],
    "error": null,
    "filename": null,
    "options": {
        "allow_files": false,
        "combine": null,
        "filters": null,
        "name": "client",
        "output_format": "json",
        "parameters": null,
        "properties": null
    },
    "started": null,
    "state": "queued",
    "user_id": "5dfc4b2b72d143c9beee89e9a0cb8c0f"
}

If you create an export job with invalid options, you will directly receive an error message:

POST /api/2/export HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABgZBtQGT5-SuaUwo1fqjvJl3M36EtHGk69P-AdJqzV2_nPONZu_-051ybF1b3ez0mwJ8_QfGd1ltewjWedLOFUndTRWugtttJmJ8d-ZB0Tb34o8m-prIAPUj0uSCw2Mz2ABUOlEDz56sJ-MVqlZ4OZpIVgOsrl5nyGQum4v3KPPMeGFT6oR5fWWDk0jusJXPoZFvOW
Content-Length: 176
Content-Type: application/json

{
    "combine": [
        {
            "name": "professional"
        }
    ],
    "name": "client",
    "properties": [
        "email",
        "sex",
        "bsn"
    ]
}

The response will be an error:

HTTP/1.0 400 Bad Request
Content-Length: 357
Content-Type: application/json;charset=UTF-8

{
    "code": 400,
    "extra": [
        {
            "message": "Unknown property",
            "name": "sex"
        },
        {
            "message": "Unknown property",
            "name": "bsn"
        },
        {
            "message": "Unknown combine",
            "name": "professional"
        }
    ],
    "message": "Invalid option input"
}

Listing existing export jobs

To get a list of all export job objects send a GET request to the API base URL with /export/items appended:

GET /api/2/export/items?start=0&limit=10 HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABgZBtQGT5-SuaUwo1fqjvJl3M36EtHGk69P-AdJqzV2_nPONZu_-051ybF1b3ez0mwJ8_QfGd1ltewjWedLOFUndTRWugtttJmJ8d-ZB0Tb34o8m-prIAPUj0uSCw2Mz2ABUOlEDz56sJ-MVqlZ4OZpIVgOsrl5nyGQum4v3KPPMeGFT6oR5fWWDk0jusJXPoZFvOW

The response will be a list of export job objects:

HTTP/1.0 200 Ok
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Content-Length: 1546
Content-Type: application/json;charset=UTF-8

{
    "@items": [
        {
            "@links": [
                {
                    "name": "archive",
                    "url": "https://customer.minddistrict.com/api/2/export/1617173334642797/archive"
                },
                {
                    "name": "download",
                    "url": "https://customer.minddistrict.com/api/2/export/1617173334642797/download"
                }
            ],
            "@type": "http://ns.minddistrict.com/export/job",
            "@url": "https://customer.minddistrict.com/api/2/export/1617173334642797",
            "completed": "2021-03-31T06:48:54",
            "content_encoding": "gzip",
            "content_length": 275,
            "content_type": "application/json; charset=utf-8",
            "created": "2021-03-31T06:48:54",
            "description": "Export job for \"Clients\"",
            "downloaded_on": [],
            "error": null,
            "filename": "client_2021-03-31_06-48-54.json",
            "options": {
                "allow_files": false,
                "combine": null,
                "filters": null,
                "name": "client",
                "output_format": "json",
                "parameters": null,
                "properties": null
            },
            "started": "2021-03-31T06:48:54",
            "state": "completed",
            "user_id": "5dfc4b2b72d143c9beee89e9a0cb8c0f"
        }
    ],
    "@links": [],
    "@paging": {
        "found": 1,
        "limit": 10,
        "start": 0,
        "total": 1
    }
}

All existing export jobs from the platform will be listing, created by any user. The most recent job will be listed first.

Checking a specific export job

To retrieve the status of a job, send a GET request to its URL.:

GET /api/2/export/1617173334642797 HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABgZBtQGT5-SuaUwo1fqjvJl3M36EtHGk69P-AdJqzV2_nPONZu_-051ybF1b3ez0mwJ8_QfGd1ltewjWedLOFUndTRWugtttJmJ8d-ZB0Tb34o8m-prIAPUj0uSCw2Mz2ABUOlEDz56sJ-MVqlZ4OZpIVgOsrl5nyGQum4v3KPPMeGFT6oR5fWWDk0jusJXPoZFvOW

The response will be a export job object:

HTTP/1.0 200 Ok
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Content-Length: 1118
Content-Type: application/json;charset=UTF-8

{
    "@links": [
        {
            "name": "archive",
            "url": "https://customer.minddistrict.com/api/2/export/1617173334642797/archive"
        },
        {
            "name": "download",
            "url": "https://customer.minddistrict.com/api/2/export/1617173334642797/download"
        }
    ],
    "@type": "http://ns.minddistrict.com/export/job",
    "@url": "https://customer.minddistrict.com/api/2/export/1617173334642797",
    "completed": "2021-03-31T06:48:54",
    "content_encoding": "gzip",
    "content_length": 275,
    "content_type": "application/json; charset=utf-8",
    "created": "2021-03-31T06:48:54",
    "description": "Export job for \"Clients\"",
    "downloaded_on": [],
    "error": null,
    "filename": "client_2021-03-31_06-48-54.json",
    "options": {
        "allow_files": false,
        "combine": null,
        "filters": null,
        "name": "client",
        "output_format": "json",
        "parameters": null,
        "properties": null
    },
    "started": "2021-03-31T06:48:54",
    "state": "completed",
    "user_id": "5dfc4b2b72d143c9beee89e9a0cb8c0f"
}

This endpoint can be used to pull the status of a job and retrieve the download when it is ready.

Cancelling a specific export job

To cancel a job send a POST request to the cancel URL you will find in its @links while it is pending:

POST /api/2/export/1617173334642797/cancel HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABgZBtQGT5-SuaUwo1fqjvJl3M36EtHGk69P-AdJqzV2_nPONZu_-051ybF1b3ez0mwJ8_QfGd1ltewjWedLOFUndTRWugtttJmJ8d-ZB0Tb34o8m-prIAPUj0uSCw2Mz2ABUOlEDz56sJ-MVqlZ4OZpIVgOsrl5nyGQum4v3KPPMeGFT6oR5fWWDk0jusJXPoZFvOW

You can only cancel an export job with the same user that was used to create it and if the job is pending. If you use a different user, or if the job is not pending you will get a 401 error.

Downloading a specific export job

To download a job send a GET request to the download URL you will in its @links when it is ready:

GET /api/2/export/1617173334642797/download HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABgZBtQGT5-SuaUwo1fqjvJl3M36EtHGk69P-AdJqzV2_nPONZu_-051ybF1b3ez0mwJ8_QfGd1ltewjWedLOFUndTRWugtttJmJ8d-ZB0Tb34o8m-prIAPUj0uSCw2Mz2ABUOlEDz56sJ-MVqlZ4OZpIVgOsrl5nyGQum4v3KPPMeGFT6oR5fWWDk0jusJXPoZFvOW

You can only download an export job with the same user that was used to create it and if the job is ready. If you use a different user, or if the job is not ready you will get a 401 error.