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