Use the Engage API

Endpoints

The Engage API currently supports the following endpoints.

Operation	Description
`Read Dashboard Data`	Gets global data values from all projects included in dashboard reports and all workflow ideas.
`Create File`	Creates a new project idea or a non-workflow project. Note Recommended over `Create Idea`.
`Create Idea`	Creates a new project idea. Note For extended functionality, use `Create File`.
`Get Job Status`	Gets the status information for a specified background job.

Read dashboard data

The Read Dashboard Data operation retrieves global project data for all projects included in dashboard reports and all workflow ideas. This endpoint uses the OData standard for querying data.

The following OData functions are not supported:

$filter
$apply
$orderby
$select
$expand
$count
$skip
$top

Request

The Read Dashboard Data request may be constructed as follows. Replace subscription-id with your subscription's ID.

Method	Request URL
`GET`	`https://engage.minitab.com/api/v1/subscription-id/export/odata`

Request headers

Header	Description
`Authorization`	Required. Provide an API token via the `Bearer` authorization scheme.

Sample request

Request: GET 
https://engage.minitab.com/api/v1/4906fcd496d94f738304dfcde754000a/export/odata 
HTTP/1.1

Headers: Authorization: Bearer token

Response

The response includes an HTTP status code, a set of response headers, and a body.

Status code

A successful request returns status code 200 (OK).

Response headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Header	Description
`Content-Type`	Indicates the media type of the response body.

Response body

The response body contains the requested data in JSON format, structured according to the OData standard. Below is an example of the response:

{
    "value": [
        {
            "ProjectId": "12345",
            "ProjectName": "Project A",
            "Status": "Active",
            "StartDate": "2025-01-01",
            "EndDate": "2025-12-31"
        },
        {
            "ProjectId": "67890",
            "ProjectName": "Project B",
            "Status": "Completed",
            "StartDate": "2024-01-01",
            "EndDate": "2024-12-31"
        }
    ]
}

Sample response

Response Status:
HTTP/1.1 200 OK

Response headers:
Content-Type: application/json

Response Body:
{
    "value": [
        {
            "ProjectId": "12345",
            "ProjectName": "Project A",
            "Status": "Active",
            "StartDate": "2025-01-01",
            "EndDate": "2025-12-31"
        },
        {
            "ProjectId": "67890",
            "ProjectName": "Project B",
            "Status": "Completed",
            "StartDate": "2024-01-01",
            "EndDate": "2024-12-31"
        }
    ]
}

Create file

The Create File operation initiates a job to create a new project idea or a non-workflow project in your subscription.

Request

You can construct the Create File request as shown here. Replace subscription-id with your subscription's ID.

Method	Request URL
`POST`	`https://engage.minitab.com/api/v2/subscription-id/Item`

Request headers

Header	Description
`Authorization`	Required. Provide an API token via the `Bearer` authorization scheme. The token is required to have the `Create Idea` permission.
`Content-Type`	Required. Must be `application/json`.

Request Body

The request body consists of a JSON object with three required properties: FileName, TemplateName, and CreateProjectType.

{
	"FileName": "name of idea"
	"TemplateName":"name of the project template to use for the project", #Only required for non-workflow projects. The name must match a project template in your subscription.
	"CreateProjectType": 0, #(0 Idea, 1 Non Workflow Project)
}

You may include any of the following options.

OwnerEmail: The email address of the user who will own this new file.
IncludeInDashboard: A true or false value to override the default value in the subscription settings.
Data: The object to set data field values in the file. Data consists of single-value category codenames mapped to objects of field codenames and values.
TableData: The object to set table data values in the file. TableData consists of data table category codenames mapped to objects of field codenames and value sets.
- For ideas, table data must be on the idea form.
- In table data, when the number of values for a field are unequal, the fields with fewer values are set to their default values in the remaining rows.
- Use null to get a blank value.
- Some data tables have required fields, such as [teammember / name]. When required fields are empty, a project is not created.
NotificationRecipients: Email addresses to receive a message when the Create File operation succeeds or fails.

{
	"FileName": "name of idea",
    "TemplateName":"Just Do It",
    "CreateProjectType":1,
    "OwnerEmail":"user@company.com",
    "IncludeInDashboard":false,
	"NotificationRecipients": ["fmae@mortgage.gov", "user@domain.com"],
	"Data": {
		"projectsummary": {
			"belt_level": "Green Belt",
			"critical_to": "Long text\r\nwith\r\nnewlines"
		},
		"annualized_financial": {
			"annualized_actual_hard_savings": 100
		}
	}
    "TableData":{
        "teammember":{
            "name":["John Q. Public","Fannie Mae","Freddie Mac"],
            "role":["Project Leader",null,"Mortgage Broker"],
            "email":[null,"fmae@mortgage.gov"]
        },
        "task":{
            "subject":["refinance","origination"]
            "startdate":["2025-04-24"]
        }
    }
}

Note

To see the list of valid data fields and category names available for sharing, data architects can download a CSV file from the Settings tab of the Engage web app.

Note

To set the name of a team member to a team role (Sponsor, Champion, Financial Analyst, etc.), connect the Team Member / Role field to the Role field. In the previous example, the Team Role / Project Leader will be set to "John Q. Public".

Note

The Create File operation does not support setting data values for all fields. Attempting to provide data for formula, rich text, or internal fields will result in an error.

Sample Request

Request:
POST https://engage.minitab.com/api/v2/4906fcd496d94f738304dfcde754000a/Item HTTP/1.1

Headers:
Authorization: Bearer token
Content-Type: application/json
Content-Length: 785

Body:
{
	"FileName": "file name",
	"TemplateName":"DMAIC Project",
	"CreateProjectType": 1,
	"OwnerEmail":"user@yourcompany.com",
	"IncludeInDaashboard":true,
	"Data": {
		"_category1": {
			"_text_field": "text value",
			"_date_field": "2025-03-20",
			"_number_field": 3.1415
		},
		"_category2": {
			"_text_field": "text value",
			"_date_field": "2025-03-20",
			"_number_field": 3.1415
		}
	},
	"TableData": {
		"_tableCategory1": {
			"_text_field": ["text value","text_value2","text_value"],
			"_date_field": ["2025-03-20","2025-04-21","2024-03-20"],
			"_number_field": [3.1415,2.73,1.414]
		},
		"_tableCategory2": {
			"_text_field": ["text value",null,"text_3"],
			"_date_field": ["2025-03-20","2025-08-23"], 
			"_number_field": [3.1415,null]
		}
	}
}

Response

The response includes an HTTP status code, a set of response headers, and a body.

Status code

A successful operation returns status code 202 (Accepted).

Response headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Header	Description
`Location`	A URL that may be used to retrieve the status of the job.

Response body

The response for the Create File operation contains the identifier of the job that will create the project or idea. The JSON format is shown below:

{
	"JobId": "479f6bea-360f-40ba-be0a-bd06c032c4fb"
}

Create idea

The Create Idea operation initiates a job to create a project idea in your subscription.

Note

When creating a new project idea, you can use Create Idea, but Create File is recommended.

Request

You can construct the Create Idea request as shown here. Replace subscription-id with your subscription's ID.

Method	Request URL
`POST`	`https://engage.minitab.com/api/v1/subscription-id/Item`

Request Headers

Header	Description
`Authorization`	Required. Provide an API token via the `Bearer` authorization scheme. The token is required to have the `Create Idea` permission.
`Content-Type`	Required. Must be `application/json`.

Request Body

The request body consists of a JSON object with one required property FileName.

{
    "FileName": "name of idea"
}

You may optionally include a Data object to set data field values in the idea. Data consists of single-value category codenames mapped to objects of field codenames and values.

{
    "FileName": "name of idea",
    "Data": {
        "projectsummary": {
            "belt_level": "Green Belt",
            "critical_to": "Long text\r\nwith\r\nnewlines"
        },
        "annualized_financial": {
            "annualized_actual_hard_savings": 100
        }
    }
}

Note

To see the list of valid data fields and category names available for sharing, data architects can download a CSV file from the Settings tab of the Engage web app.

Note

Only data fields that are shared to controls on the idea form may be specified in the Create Idea operation request. Additionally, specifying rich text, formula, read-only, or data table fields is not supported. Attempting to provide data for fields not shared to controls on the idea form or rich text, formula, read-only, or data table fields will result in an error.

Sample Request

Request:
POST https://engage.minitab.com/api/v1/4906fcd496d94f738304dfcde754000a/Item HTTP/1.1

Headers:
Authorization: Bearer token
Content-Type: application/json
Content-Length: 287

Body:
{
    "FileName": "idea name",
    "Data": {
        "_category1": {
            "_text_field": "text value",
            "_date_field": "2025-03-20",
            "_number_field": 3.1415
        },
        "_category2": {
            "_text_field": "text value",
            "_date_field": "2025-03-20",
            "_number_field": 3.1415     
        }
    }   
}

Response

The response includes an HTTP status code, a set of response headers, and a body.

Status code

A successful operation returns status code 202 (Accepted).

Response headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Header	Description
`Location`	A URL that may be used to retrieve the status of the job.

Response body

The response for the Create Idea operation contains the identifier of the job that will create the project idea. The JSON format is shown below:

{
    "JobId": "479f6bea-360f-40ba-be0a-bd06c032c4fb"
}

Sample response

Response Status:
HTTP/1.1 202 ACCEPTED

Response headers:
Location: /api/v1/4906fcd496d94f738304dfcde754000a/job/479f6bea-360f-40ba-be0a-bd06c032c4fb
Content-Type: application/json

Response Body:
{
    "JobId": "479f6bea-360f-40ba-be0a-bd06c032c4fb"
}

Get job status

The Get Job Status operation retrieves the status of the specified job.

Request

The Get Job Status request may be constructed as follows. Replace subscription-id with your subscription's ID and job-id with a valid job identifier.

Method	Request URL
`GET`	`https://engage.minitab.com/api/v1/subscription-id/job/job-id`

Request headers

Header	Description
`Authorization`	Required. Provide an API token via the `Bearer` authorization scheme.

Sample request

Request:
GET https://engage.minitab.com/api/v1/4906fcd496d94f738304dfcde754000a/job/479f6bea-360f-40ba-be0a-bd06c032c4fb HTTP/1.1

Headers:
Authorization: Bearer token

Response

The response includes an HTTP status code and a body.

Status code

A successful request returns status code 200 (OK).

Response body

The response for the Get Job Status operation contains a Status integer property representing the various possible states of a job as shown in the following example.

{
    "Status": 1
}

Job Status	Description
0	Job not started yet
1	Job has started; in progress
2	Job is complete
3	Job has failed
4	Job could not be found
5	Job was canceled

Sample response

Response Status:
HTTP/1.1 200 OK

Response headers:
Content-Type: application/json

Response Body:
{
    "Status": 2
}

In This Topic

Endpoints

Note

Note

Read dashboard data

Request

Response

Create file

Request

Note

Note

Note

Response

Create idea

Note

Request

Note

Note

Response

Get job status

Request

Response