Quick scripts and API examples

Here are practical examples of using Next Matter’s API for common automation tasks.

Start instance and complete a step (script)

Use this Python script to automatically create workflow instances and complete steps programmatically. Use case: Create a new employee onboarding workflow, automatically complete the first step by, for example, automatically filling in personal details, and advance to the next step.

The script creates an instance with process_id and tags. The name is created automatically as per Next Matter settings.
- Uses the API endpoint: https://core.nextmatter.com/api/instances/
- Returns:
  - Instance ID (for reference)
  - Instance URL (for navigation)
  - If an error occurs, it prints the error message.
Fills the step with the required input data and marks a step in the workflow as completed.
- Uses the API endpoint: https://core.nextmatter.com/api/instances//complete_step/
- Requires:
  - Instance ID (to specify the workflow instance)
  - Step ID (which step to complete)
  - List of form fields ( with input data required for the step to complete) If successful, shows a completion message.

Script

# Next Matter API Key (Replace with actual API Key)
API_KEY = "API_KEY_VALUE"

# Workfow and Step IDs (Replace with actual values)
PROCESS_ID = "WORKFLOW_ID_VALUE"
STEP_ID = "STEP_ID_VALUE"

# Next Matter API Base URL
BASE_URL = "https://core.nextmatter.com/api/"

# Headers for authentication
HEADERS = {
    "Authorization": f"Api-Key {API_KEY}",
    "Content-Type": "application/json"
}

def create_instance(process_id: str,  tags: list = None):
    """
    Creates a new instance of a Next Matter workflow. 
    The name of the instance will be automatically created by Next Matter.

    :param process_id: ID of the workflow to create an instance for.
    :param tags: Optional list of tags to assign to the instance.
    :return: Instance ID and Instance URL if successful, None otherwise.
    https://help.nextmatter.com/reference/instances_create
    """
    url = f"{BASE_URL}instances/"
    payload = {
        "process": f"https://core.nextmatter.com/api/processes/{process_id}/"
    }

    if tags:
        payload["tags"] = tags

    response = requests.post(url, json=payload, headers=HEADERS)

    if response.status_code == 201:
        instance_data = response.json()
        print(f"✅ Instance created successfully: {instance_data['id']}")
        return instance_data["id"], instance_data["url"]
    else:
        print(f"❌ Error creating instance: {response.text}")
        return None, None

def complete_step(instance_id: str, step_id: int, actions: list):
    """
    Completes a step in a given Next Matter instance.

    :param instance_url: URL of the instance where the step should be completed.
    :param step_id: ID of the step to be completed.
    :param actions: List of form fields (each containing an action_id and input_object).
    :return: API response data.
    https://help.nextmatter.com/reference/instances_complete_step
    """
    url = f"{BASE_URL}instances/{instance_id}/complete_step/"
    payload = {
        "step_id": step_id,
        "actions": actions
    }

    response = requests.post(url, json=payload, headers=HEADERS)

    if response.status_code == 200:
        print("✅ Step completed successfully.")
        return response.json()
    else:
        print(f"❌ Error completing step: {response.text}")
        return None

if __name__ == "__main__":
    # Example usage
    instance_id, instance_url = create_instance(PROCESS_ID, instance_name="Test Instance")

    if instance_url:
        # Modify the form field list according to your workflow's requirements
        actions = [
            {
                "action_id": 123456,  # Replace with actual action ID
                "input_object": {"inputValue": "Value 1"} # Key (i.e. inputValue) depends on the type of form field
            },
            {
                "action_id": 789012,  # Replace with actual action ID
                "input_object": {"itemSelected": "Value 2"}
            }
        ]

        complete_step(str(instance_id), STEP_ID, actions)

Filter instances by max total runtime

Use case: Find all workflow instances that completed within a specific time frame. You can use this API call to get filtered instances of a workflow. In the example below, we’re filtering for all instances with a maximum total runtime of 50 seconds.

https://core.nextmatter.com/api/processes/WORKFLOW_ID/instances/?total_runtime_max=00:50

Here are some other examples of values to use:

01 09:30 - 1 day and 9 minutes and 30 seconds
02:30:00 - 2 hours and 30 minutes (and 0 seconds)
PT50M - 50 minutes (as per ISO 8601 duration formats)
PT1H30S - 1 hour and 30 seconds (as per ISO 8601 duration formats)

Overview

API

No-code

Custom integrations

Start instance and complete a step (script)

Filter instances by max total runtime

Overview

API

No-code

Custom integrations

​Start instance and complete a step (script)

​Filter instances by max total runtime

Start instance and complete a step (script)

Filter instances by max total runtime