--- title: "Starting a Request via REST API" slug: "starting-a-request-via-rest-api" updated: 2025-10-21T03:00:14Z published: 2025-10-21T03:00:14Z canonical: "docs.processmaker.com/starting-a-request-via-rest-api" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.processmaker.com/llms.txt > Use this file to discover all available pages before exploring further. # Starting a Request via REST API This guide explains how to create a new Process instance—known as a **Request**—using the ProcessMaker 4 REST API. It assumes you already have an access token to authenticate your API calls. If you need a reminder on how to obtain one, see the previous guide [[here](/o/-LJ0aNaUl77b5HIzdH7-/s/PyTHGwZ0VereJkRNmGxE/~/changes/29/authentication/getting-an-access-token)]. PythonNode.jsPostmancURL ### Pre-requisites | Requirement | Function | Version | | --- | --- | --- | | 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](/o/-LJ0aNaUl77b5HIzdH7-/s/PyTHGwZ0VereJkRNmGxE/~/changes/29/authentication/getting-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`. > [!NOTE] > 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: ```python 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: ```python 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. If you need help obtaining the process id, you can look at the [Process API documentation](/o/-LJ0aNaUl77b5HIzdH7-/s/7PyIjqHDo60JXPLPD89h/platform-api-reference/processes) to get the id before making the request to initiate a new request. Here's how you can send the POST request and print the response: ```python # Make a request to the API to start a new process response = requests.post(    'https:///api/1.0/process_events/',    headers=headers,    json=request_body ) # Print the response print(response.json()) ``` 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. ### **Pre-requisites** | Requirement | Function | Version | | --- | --- | --- | | Node.js Dependencies: - `axios` | The programming language and modules we are using for this tutorial | - Nodejs 8+ - NPM 8-16 Note: this is the ProcessMaker compatible version, this tutorial should work with the latest versions as well | | Access token | For authenticating with the API | Instructions for obtaining from the [How to Get an Access Token](/o/-LJ0aNaUl77b5HIzdH7-/s/PyTHGwZ0VereJkRNmGxE/~/changes/29/authentication/getting-an-access-token) page | ## Step 1: Preparing Your Node.js Environment Before starting, ensure that you have Node.js and the `axios` library installed. You can verify your Node.js version by typing `node --version` in your command line. ## 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 need to 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 JavaScript, headers are represented as an object with the header names as keys and the corresponding values as object values. Here's how you would set up the headers: ```javascript const headers = {    'Authorization': `Bearer ${access_token}`, }; ``` Replace `${access_token}` with your actual access token. ### Preparing the Request Body Here's an example of an empty request body: ```javascript const requestBody = {}; ``` The body of a POST request contains the data we want to send to the server. In this case, we'll use an empty object (`{}`), however, this is dependent on your process, and you may require to send additional parameters to be used as request data within the request. ## 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. If you need help obtaining the process id, you can look at the [Process API documentation](/o/-LJ0aNaUl77b5HIzdH7-/s/7PyIjqHDo60JXPLPD89h/platform-api-reference/processes) to get the id before making the request to initiate a new request. Here's how you can send the POST request and print the response: ```javascript const axios = require('axios'); axios.post(  'https:///api/1.0/process_events/',  requestBody,  { headers: headers } ).then(response => {  console.log(response.data); }).catch(error => {  console.error(`Error: ${error}`); }); ``` This code will send the POST request and print the response data. If there's an error, it will print the error. That's it! You now know how to create a new process request using the ProcessMaker 4 REST API in Node.js. Remember to replace `<your-instance>`, `<your-access-token>`, and `<process_id>` with actual values. ### **Pre-requisites** | Requirement | Function | Version | | --- | --- | --- | | Postman | The tool we will use to make API calls to ProcessMaker 4 REST API | Latest | | Access token | For authenticating with the API | Instructions for obtaining from the [How to Get an Access Token](/o/-LJ0aNaUl77b5HIzdH7-/s/PyTHGwZ0VereJkRNmGxE/~/changes/29/authentication/getting-an-access-token) page | ## Step 1: Open Postman Start by opening Postman. If you haven't installed it yet, you can download it from the [official Postman website](https://www.postman.com/downloads/). ## Step 2: Create a New Request In Postman, click on the "+" tab to create a new request. ## Step 3: Configure the Request In the new request tab, you will need to set up the following: - **HTTP method:** Choose `POST` from the dropdown menu next to the URL bar. - **Request URL:** 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. - **Headers:** Click on the "Headers" tab and add a new header. For the name, enter `Authorization`, and for the value, enter `Bearer <your-access-token>`. Replace `<your-access-token>` with your actual access token. - **Body:** Click on the "Body" tab and choose the `raw` and `JSON` format. Here you can enter the data you want to send as the request body. In this case, you can use an empty JSON object (`{}`), but depending on your process, you may need to send additional parameters to be used as request data within the request. ## Step 4: Send the Request Once you have configured the request, you can press the "Send" button to send the request to the ProcessMaker 4 REST API. The server's response will appear in the section below. That's it! You now know how to create a new process instance using the ProcessMaker 4 REST API in Postman. Remember to replace `<your-instance>`, `<your-access-token>`, and `<process_id>` with actual values. ### **Pre-requisites** | Requirement | Function | Version | | --- | --- | --- | | Postman or a Terminal | The tool we will use to make API calls to ProcessMaker 4 REST API | Latest | | Access token | For authenticating with the API | Instructions for obtaining from the [How to Get an Access Token](/o/-LJ0aNaUl77b5HIzdH7-/s/PyTHGwZ0VereJkRNmGxE/~/changes/29/authentication/getting-an-access-token) page | ## Step 1: Setting Up Your API Request The ProcessMaker 4 REST API uses HTTP protocols. In this case, we will be sending a POST request to create a new request. ### Execute the following command in your terminal ```bash curl -X POST "https:///api/1.0/process_events/" \     -H "Authorization: Bearer " \     -d '{"key1":"value1", "key2":"value2", ...}' ``` > [!NOTE] > Don't forget! > > Replace: > > - `<your-instance>` with your actual ProcessMaker instance URL. > - `<process_id>` with the ID of the process you wish to start. > - `<access_token>` with your actual access token. > - `{"key1":"value1", "key2":"value2", ...}` with your actual payload data. ## Step 2: Review the Response After executing the command, you should receive a response from the server. This will provide details about the process instance you've started or any potential errors. ## Conclusion Using the `curl` command directly from the command line offers a swift and efficient method to interact with the ProcessMaker 4 REST API. By following the steps outlined in this guide, you can seamlessly initiate a Process instance, termed a Request, without the need for intermediary scripts or tools. This approach not only simplifies the process but also enhances the speed at which developers can test and integrate with the API. Always ensure you handle your access tokens with care, as they are crucial for secure communication with the API.