Starting a Request via REST API

Learn how to start an instance of a Process called a Request.


This guide walks you through the steps to create a new Process instance, called a Request, using the ProcessMaker 4 REST API programmatically. The guide assumes that you already have an access token for authenticating your API requests. If you need a refresher on obtaining an access token, you can refer to the previous guide here.



Python Dependencies:

  • requests

The programming language and modules we are using for this tutorial

Python 3+ Requests will install default latest version which is fine.

Access token

For authenticating with the API.

instructions for obtaining from the How to Get an Access Token page

Step 1: Preparing Your Python Environment

Before starting, ensure that you have Python 3 and the requests library installed. You can verify your Python version by typing python --version in your command line. The requests library can be installed via pip, Python's package manager, with the command pip install requests.

If the command python returns an error, it may be installed as python3, depending on your environment.

Step 2: Setting Up Your API Request

The ProcessMaker 4 REST API uses HTTP protocols, and in this case, we will be sending a POST request to create a new request. For this, we must prepare the headers and the body of our request.

Preparing the Headers

The headers of an HTTP request provide additional parameters that the request needs to fulfill. In our case, we need to provide the Authorization header with our access token to authenticate our request.

In Python, headers are represented as a dictionary with the header names as keys and the corresponding values as dictionary values.

Here's how you would set up the headers:

headers = {
    'Authorization': f'Bearer {access_token}',

Replace {access_token} with your actual access token.

Preparing the Request Body

The body of a POST request contains the data we want to send to the server. In this case, we'll use a blank dictionary ({}) however this is dependent on your process, you may require to send additional parameters to be used as request data within the request.

Here's an example of a blank request body:

request_body = {}

Step 3: Sending the Request to the API

Now that we have our headers and request body ready, we can send our POST request to the ProcessMaker 4 REST API.

The URL for creating a new process instance is https://<your-instance>/api/1.0/process_events/<process_id>. Replace <your-instance> with your actual ProcessMaker instance and <process_id> with the ID of the process you want to start.

Here's how you can send the POST request and print the response:

# Make a request to the API to start a new process
response =

# Print the response

The response.json() function converts the server's response from a JSON format to a Python dictionary for easier handling.

That's it! You now know how to create a new process instance using the ProcessMaker 4 REST API in Python. Remember to replace <your-instance>, <your-access-token>, and <process_id> with actual values.

Last updated