Skill Level: Beginner

How to utilize BPM rest API to start a process. Extra notes for bypassing SSO login procedures.




  1. Create and Test desired REST call

    IBM provides, out of the box, a REST ui that allows you to test example calls to verify they are working as expected. This can be accessed at https://exampleurl.com/bpmrest-ui. This will require logging in with your BPM credentials to access like normal, but shouldn’t require any additional authentication. Under “Process API” header, there should be an option to “Start Process”. 

    This will require 2 pieces of information:

    • BPD ID (25.xxx)
    • Snapshot ID (2064.xxx)

    The Branch ID (2063.xxx) and Process Application ID (2066.xxx) are not needed if Snapshot ID is provided.

    This information can be found using the same REST UI under “Exposed Processes”. If your process can not be found in this list, double check the settings on the process app in designer to make sure that the Process is exposed to your user (or a group you exist in). You may have to do some digging but the ID information should be there.

    Once the call returns successfully you should:

    • See a new process instance in process inspector
    • See a copy of the REST url displayed in the bpmrest-ui. Make a note, this will be the same rest call you use going forward. Note that the request is a POST call


    If your process has input parameters be sure to add them. More information on this can be found at: 



  2. Getting access token

    For the next step, you will likely be unable to access any BPM API functionality outside of the web interface, without getting an authentication token. The easiest way I have found to get a token programmatically is to make a POST call to the background endpoint BPM uses itself. If your usual BPM url is https://exampleurl.com then this endpoint can be called via a REST client at https://exampleurl.com/ProcessPortal/j_security_check. You will need to set the request cookies “j_username” and “j_password” with your BPM username and password, and be sure the call is a POST. Even if your BPM instance is configured to use SSO by default via the web UI, each user will still have a configured username and password in the BPM system that you will need to use here. The authentication token will be in the “Set-Cookie” response. Make sure your future REST calls include this token.


    If you are using Java to automate this process, libraries like java.net.CookieManager will make this simple by keeping track of the cookies for you automatically.


  3. Putting it all together

    Once you have the authentication token cookie, and the desired REST url, put them together and verify everything works as expected. This process is the same for any of the REST calls in the bpmrest-ui, so feel free to explore.

Join The Discussion