Setup

Next Matter provides a RESTful API to customers and the full technical documentation can be found at https://nextmatter.readme.io/reference/getting-started

All Next Matter processes can be accessed in full to push data from other systems or retrieve information. A custom process endpoint, deployed live!

To get started you need an API-Key, which customers can request from our support team. The API-Key can be either tied to an individual user in your workspace or to a Bot User that is created for that purpose.

The two most popular endpoints are

  • /instances

  • /complete_step

Header configuration

In order to use any endpoint you need to pass along the API key as a header like this:

Content-Type: application/json
Authorization: Api-Key <PROVIDEDKEY>

/instances

Endpoint: https://core.nextmatter.com/api/instances/

Simple sample body to launch a new instance of a process without tags, priority or deadline set.

{
"process": "https://core.nextmatter.com/api/processes/<IDoftheprocessinNM>",
"name": "<Name of the instance>"
}

/complete_step

Endpoint: https://core.nextmatter.com/api/instances/<instance_id>/complete_step/

The instance id can be retrieved in various ways, for example

  • URL of the instance in the Browser

  • Data referencing variable directly in Next Matter via {{instance id}} in the editor

  • GET requests or a response from the creation of an instance like in the previous example

Sample Body for completing one string input field:

{
"step_id": 20111,
"actions": [
{
"action_id": 50222,
"input_object": {
"inputValue": "STRING"
}
}
]
}

The step IDs can be retrieved directly in the URL of the executor or the editor. The action ids can be retrieved as seen in the below screenshot or via GET Request on the process.

Additional prerequisites for a successful call:

  • The step is active

  • Step ownership of the user API-Key

Customers are making these calls also with third-party integration layers like Zapier or Integromat.

This is an advanced functionality of Next Matter that is only sketched briefly in this article. Please reach out to us directly if you have any further questions about integrating your existing (proprietary) apps seamlessly with Next Matter.

During our onboarding, we usually guide our customers to set up their integrations with existing systems.

Sample request bodies for all action types

Address:

{
"step_id":70938,
"actions": [
{
"action_id":200952,
"input_object": {
"city":"city",
"street": "street",
"zipCode": "zipCode"
}
}
]
}

Checklist (one of the following options):

Specifying which items are checked:

{
"step_id":70954,
"actions":[
{
"action_id":200997,
"input_object":{
"itemsChecked": ["Option A"]
}
}]
}

Specifying which items are not checked:

{
"step_id":70954,
"actions":[
{
"action_id":200997,
"input_object":{
"itemsNotChecked": ["Option B", "Option C"]
}
}]
}

Date:

{
"step_id":70955,
"actions":[
{
"action_id":200998,
"input_object":
{
"date": "2021-06-16T10:00:00.000Z"
}
}
]
}

Single Value Dropdown:

{
"step_id":70961,
"actions":[
{
"action_id":201005,
"input_object":
{
"itemSelected": "Option A"
}
}
]
}

Multi-Value Dropdown (one of the following options):

Specifying which items are selected:

{
"step_id":70959,
"actions":[
{
"action_id":201007,
"input_object":
{
"itemsSelected": ["Option A", "Option B"]
}
}
]
}

Specifying which items are not selected:

{
"step_id":70959,
"actions":[
{
"action_id":201007,
"input_object":
{
"itemsNotSelected": ["Option B]
}
}
]
}

Radio:

{
"step_id":70960,
"actions":[
{
"action_id":201006,
"input_object":
{
"radioItemSelected": "Option A"
}
}
]
}

Text:

{
"step_id":70963,"actions":[
{
"action_id":201003,
"input_object":
{
"inputValue": "Lorem Ipsum"
}
}
]
}

URL:

{
"step_id":70964,
"actions":[
{
"action_id":201002,
"input_object":
{
"url": "http://nextmatter.com"
}
}
]
}

Instruction:

{
"step_id":71896,
"actions":[
{
"action_id":203710,
"input_object": {}
}
]
}

The instruction action does allow an empty input object.

User selection:

{
"step_id":203048,
"actions":[
{
"action_id":491996,
"input_object":{
"selection": {
"user_email":"john.doe@email.com"
}
}
}
]
}

Decision:

A decision step can be completed as follows. The decision can be either "return" or "continue". "continue" means the same as using "Confirm and continue" in the UI. The comment is for the text box for Adjustments required that appears when selecting return.

{
"step_id":203048,
"actions":[
{
"action_id":491996,
"input_object":{
"comment":"",
"decision":"return"
}
}
]
}

Sample request body for multiple actions in one step

In general steps have multiple actions inside. The samples of the previous step consider only one action in the step.

{
"step_id":203048,
"actions":[
*** Here we need to include all the actions of the step ***
]
}

Let's see an example. Here we have a step with:

  • An instruction

  • A Text input

  • A user selection

The body request would be:

{
"step_id":203048,
"actions":[
{
"action_id":203710,
"input_object": {}
},
{
"action_id":201003,
"input_object": {
"inputValue": "Lorem Ipsum"
}
},
{
"action_id":491996,
"input_object":{
"selection": {
"user_email":"john.doe@email.com"
}
}
},

]
}

Responses from the Next Matter API

The response to any API call regarding an instance is always the full data set of the instance and looks similar to this (abbreviated) JSON:

{
"url": "https://core.nextmatter.com/api/instances/281931/",
"id": 281931,
"started_time": "2021-06-18T12:21:48.138028+02:00",
"completed_time": null,
"aborted_time": null,
"last_updated_time": "2021-06-18T12:22:11.023101+02:00",
"process_snapshot": {
"id": 6300,
"name": "Complete Step",
"description": null,
"steps": [
{
"id": 71896,
...

This can be used to read back any of the information that is already part of the instance. And works similar to the next feature.

Getting information about an instance

With a GET request to the instance resource you can get the full set of information about it:

GET https://core.nextmatter.com/api/instances/281931/

returns (abbrev.)

{
"url": "https://core.nextmatter.com/api/instances/281931/",
"id": 281931,
"started_time": "2021-06-18T12:21:48.138028+02:00",
"completed_time": null,
"aborted_time": null,
"last_updated_time": "2021-06-18T12:22:11.023101+02:00",
"process_snapshot": {
"id": 6300,
"name": "Complete Step",
"description": null,
"steps": [
{
"id": 71896,
...

Did this answer your question?