Skip to main content
POST
Create instance

Authorizations

Authorization
string
header
default:Api-Key YOUR_NM_API_KEY
required

Authentication is API key based. As an admin, you can generate an API key in Next Matter by going to Company > Next Matter API keys.

When sending requests to the API, authenticate by passing the API key in the "Authorization" HTTP header, prepended with the string "Api-Key ".

For example:

Authorization: Api-Key xyzabc.12fsfe242ubdgakew ".

Body

process
string<uri>
required

The related workflow resource URI. For example https://core.nextmatter.com/api/processes/[IDoftheworkflowinNM]/. To find the workflow ID, navigate to the respective workflow at app.nextmatter.com, and copy the number at the very end of the URL.

name
string | null
default:""

The name of the instance. If automatic naming has been enabled the name parameter needs to be an empty string, null, or completely left out.

Maximum string length: 255
deadline
string<date-time> | null

Time by which the instance should be completed

priority

The priority of the instance. If you don't send this parameter, the priority will be "Regular". Other options are V - "Very High" and H - "High".

  • V - Very high
  • H - High
Available options:
V,
H
tags
string[]

A list of string tags seperated by a comma

step_assignments
object[]

A list of user assignments per step. This is only required for workflows that have at least one step assignee set to "Select user at workflow start".

visibility_teams
integer[]

IDs of the teams that may see this instance. On start, list order is kept, and the field is accepted only when the workflow allows or requires a team selection; omit it to use the workflow's default audience. On update, sending this field sets the audience to exactly these teams and requires permission to manage instance visibility. Teams that were already selected stay in their current order; newly added teams are appended in the order given. Omit the field to leave the teams unchanged. An empty list clears the teams, except for restrictive instances, which must keep at least one.

Response

201 - application/json; version=v1
process
string<uri>
required

The related workflow resource URI. For example https://core.nextmatter.com/api/processes/[IDoftheworkflowinNM]/. To find the workflow ID, navigate to the respective workflow at app.nextmatter.com, and copy the number at the very end of the URL.

url
string<uri>
required
read-only

The instance resource URI. For example https://core.nextmatter.com/api/instances/[instance_id]/.

id
integer
required
read-only
started_time
string<date-time>
required
read-only
completed_time
string<date-time> | null
required
read-only
aborted_time
string<date-time> | null
required
read-only
last_updated_time
string<date-time>
required
read-only
process_snapshot
object
required
read-only

A snapshot of the workflow structure. If you set "inject_values" query parameter to "true", this will return the input values of the form fields., If you set "steps_time_frame" query parameter to "true", this will return the completion values of the form fields.

active_step_ids
integer[]
required
read-only

List of active step IDs of the instance

step_deadlines
object[]
required
read-only

List of instance step deadlines

public_url
string
required
read-only

The public URL of the instance (for status tracking), if enabled in the workflow settings

stage
string
required
read-only
visibility_mode
string
required
read-only

Who can see this instance. Set from the workflow when the instance starts and cannot be changed. One of public, involved, involved_plus, or restrictive.

name
string | null
default:""

The name of the instance. If automatic naming has been enabled the name parameter needs to be an empty string, null, or completely left out.

Maximum string length: 255
deadline
string<date-time> | null

Time by which the instance should be completed

priority

The priority of the instance. If you don't send this parameter, the priority will be "Regular". Other options are V - "Very High" and H - "High".

  • V - Very high
  • H - High
Available options:
V,
H
tags
string[]

A list of string tags seperated by a comma

step_assignments
object[]

A list of user assignments per step. This is only required for workflows that have at least one step assignee set to "Select user at workflow start".

visibility_teams
integer[]

IDs of the teams that may see this instance. On start, list order is kept, and the field is accepted only when the workflow allows or requires a team selection; omit it to use the workflow's default audience. On update, sending this field sets the audience to exactly these teams and requires permission to manage instance visibility. Teams that were already selected stay in their current order; newly added teams are appended in the order given. Omit the field to leave the teams unchanged. An empty list clears the teams, except for restrictive instances, which must keep at least one.