Next Matter Public RESTful API

• Setup

• Header configuration

• /instances

• /complete_step

• Sample request bodies for all action types

• Responses from the Next Matter API

• Getting information about an instance

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 für die Vervollständigung eines String Input Felds

{
  "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 via GET Request.

Additional prerequisites for a successful call:

• Active step

• 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 around integrating your existing (propietary) apps seamlessly with Next Matter.

During our onboarding we usually guide our customers to setup 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:

{"step_id":70954,
  "actions":[
  {
    "action_id":200997,
    "input_object":{
      "allItems": [
        {"name": "Option A", "value": 1, "checked": true}, 
        {"name": "Option B", "value": 2}
      ],
      "itemsChecked": ["Option A"],
      "itemsNotChecked": ["Option B"],
      "numberOfItemsChecked": 1,
      "numberOfItemsNotChecked": 1
    }
  }]
}

Date:

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

Multi-Value Dropdown:

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

Radio:

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

Single Value Dropdown:

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

String:

{
  "step_id":70962,
  "actions":[
    {
      "action_id":201004,
      "input_object":
        {
          "inputValue": "Example"
        }
    }
  ]
}

Text:

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

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.

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,
      ...