REST API Administration

Overview

The following are the REST endpoints available for the Administration section of the ProcessMaker REST API 1.0:

• Users

• Groups

• Departments

• Roles

• PM Tables

• Categories

• Calendars

All these endpoints and their methods are explained below.

Users

The following REST endpoints are used to manage users in ProcessMaker.

1. Get the list of all users

2. Get information of a specific user

3. Create user

4. Upload an image for a user

5. Update the information of a user

6. Delete user

Available methods:

Get Users List: GET /users

Returns a list of all users in the workspace, including users with "INACTIVE" and "VACATION" status. The users are returned in the order which they appear in the wf_<WORKSPACE>.USERS table.

GET /api/1.0/{workspace}/users?filter={filter}&start={start}&limit={limit}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name

Optional GET Parameters:

Name	Type	Description
filter	string	Case insensitive string to search for in the user's first name, last name or username. For example, "api/1.0/workspace/users?filter=mit" would return the users "smith", "Mitter" and "solmit".
start	integer	The number of users where the list begins. The counting starts from number 0, which is always the "admin" user. For example, "api/1.0/workspace/users?start=3" would start the list of users with the fourth user.
limit	integer	The maximum number of users which are returned in the list. For example if wanting to return 10 users at a time and there are 25 users in total, then call this endpoint 3 times: "api/1.0/workspace/users?limit=10" (returns users 0-9) "api/1.0/workspace/users?start=10&limit=10" (returns users 10-19) "api/1.0/workspace/users?start=20&limit=10" (returns users 20-24)

Result:

If a successful request, the HTTP status code is 200 and it returns a JSON array of user objects with the following structure:

Element	Description	Example
[	Start array
{	Start user object
"usr_uid"	User's unique ID.	"11826545154db794ca22b52025081429"
"usr_username"	The username, which is unique and is used to login to ProcessMaker	"jdoe"
"usr_password"	The MD5 hash for the user's password.	"21232f297a57a5a743894a0e4a801fc3"
"usr_firstname"	The user's first name.	"John Jake"
"usr_lastname"	The user's last name.	"Doe"
"usr_email"	The user's email address.	"jdoe@example.com"
"usr_due_date"	The date in "YYYY-MM-DD" when the user's account will expire. After this date, the user will not be able to login to ProcessMaker.	"2020-01-01"
"usr_create_date"	The datatime in "YYYY-MM-DD HH:MM:SS" format when the user was created.	"2005-11-30 08:11:57"
"usr_update_date"	The datetime in "YYYY-MM-DD HH:MM:SS" format when the user's record was last updated.	"2014-05-23 18:36:19"
"usr_status"	The user's status, which can be "ACTIVE", "INACTIVE" or "VACATION"	"ACTIVE"
"usr_country"	Two letter ISO country code. See the wf_<WORKSPACE>.ISO_COUNTRY table in the database.	"US" (United States)
"usr_city"	One or two letter code to identify the region, state or province. Note: This field is misnamed. See the wf_<WORKSPACE>.ISO_SUBDIVISION table in the database.	"FL" (Florida in the US)
"usr_location"	Code which is 1 to 3 letters to identify the city or locality. See the wf_<WORKSPACE>.ISO_LOCATION table in the database.	"MMK" (Miami Lakes in Florida)
"usr_address"	The user's address. This field may contain line breaks (\n).	"540 Mytle Lane"
"usr_phone"	The user's phone number.	"1-305-402-1234"
"usr_fax"	The user's fax number.	"1-305-402-0282"
"usr_cellular"	The user's cellular telephone number.	"1-305-675-1400"
"usr_zip_code"	The user's zip or postal code	"46135"
"dep_uid"	The unique ID of the user's department. If the user isn't a member of a department then an empty string "".	"54883398754db7993002ae1030708956"
"usr_position"	The user's position.	"Accountant"
"usr_resume"	Always set to "" since the resume is no longer used.	""
"usr_birthday"	The user's birthday in "YYYY-MM-DD" format.	"1973-02-25"
"usr_role"	The user's role, which can be "PROCESSMAKER_ADMIN", "PROCESSMAKER_OPERATOR", "PROCESSMAKER_MANAGER" or a custom role.	"PROCESSMAKER_ADMIN"
"usr_reports_to"	The unique ID of the manager to whom the user reports. This is used when using a Reports To assignment rule. If the user is not a member of a department, then an empty string "".	"14680180454ca4477335a27034362107"
"usr_replaced_by"	Unique ID of another user who will replace this user if status changes to "INACTIVE" or "VACATION". Set to empty string "" if there is no replacement user.	"14680180454ca4477335a27034362107"
"usr_ux"	The user experience, which is the type of interface seen by the user. It can be "NORMAL", "SWITCHABLE", "MOBILE" or "SINGLE".	"NORMAL"
},	End user object.
...	Additional user objects.
]	End array.

If a bad request, than the HTTP status code is set to 400 or greater and it returns a JSON error object.

Example in JavaScript:
This JavaScript example creates a array of active users. It obtains the list of all the users for the workspace and stores it in an array named aUsers. Then it loops through the array and checks whether the user's status is "ACTIVE". If so, it adds the user's UID and username to an new array named aActiveUsers.

Example in PHP:

This PHP example creates a array of active users. It obtains the list of all the users for the workspace and stores it in an array named $aUsers. Then it loops through the array and checks whether the user's status is "ACTIVE". If so, it adds the user's UID and username to an new array named $aActiveUsers.

Get User Information: GET /user/{usr_uid}

Get information about a specified user.

GET /api/1.0/{workspace}/user/{usr_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
usr_uid	String	User UID

Result:

Returns the HTTP status code 200 and the same user object as the GET /users endpoint. For example:

If a bad request, then it returns the HTTP status code 400 and an error object like the following:

Example in PHP:

Create User: POST /user

Create a new user.

POST /api/1.0/{workspace}/user

URL Parameters:

Name	Type	Description
workspace	String	Workspace name

POST Parameters:

Name	Type	Description
usr_username	String	Username which is used to login to ProcessMaker and is unique.
usr_firstname	String	User's first name
usr_lastname	String	User's last name
usr_email	String	User's email address
usr_due_date	String	The date in "YYYY-MM-DD" when the user's account will expire. After this date, the user will not be able to login to ProcessMaker. Ex: "2020-12-31"
usr_status	String	The user's status, which can be "ACTIVE", "INACTIVE" or "VACATION".
usr_role	String	The user's role, which can be "PROCESSMAKER_ADMIN", "PROCESSMAKER_OPERATOR", "PROCESSMAKER_MANAGER" or a custom role.
usr_new_pass	String	The user's password. Remember that passwords should adhere to the password security policies.
usr_cnf_pass	String	Enter the password a second time to confirm it.
usr_address	String	Optional. The user's address. Use \n to include line breaks in the address. Ex: "345 Radcliff Drive\nC/O Brad Williams"
usr_zip_code	String	Optional. User's zip or postal code.
usr_country	String	Optional. Two letter ISO country code. See the wf_<WORKSPACE>.ISO_COUNTRY table in the database.
usr_city	String	Optional. One or two letter code to identify the region, state or province. Note: This field is misnamed. See the wf_<WORKSPACE>.ISO_SUBDIVISION table in the database.
usr_location	String	Optional. Code which is 1 to 3 letters long to identify the city or locality. See the wf_<WORKSPACE>.ISO_LOCATION table in the database.
usr_phone	String	Optional. The user's telephone number.
usr_position	String	Optional. The user's position in the organization.
usr_replaced_by	String	Optional. Unique ID of another user who will replace this user if his/her status changes to "INACTIVE" or "VACATION".
usr_calendar	String	Optional. The unique ID of the calendar which is used to calculate the due dates of tasks which the user is assigned to work on. To get the UID of a calendar, see the wf_<WORKSPACE>.CALENDAR_DEFINITION.CALENDAR_UID field in the database.

Result:

If a user was successfully created, the HTTP status code will be set to 200 and a JSON object with information about the new user is returned:

If an error occurred, the HTTP status code will be set to 400 or greater and a JSON object will be returned like the following:

PHP Example:

Upload User Image: POST /user/{usr_uid}/image-upload

Upload an image of the specified user, which will appear in the user's profile screen.

POST /api/1.0/{workspace}/user/{usr_uid}/image-upload

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
usr_uid	String	User UID

POST Parameters:

Name	Type	Description	Examples
USR_PHOTO	string	The full path on the ProcessMaker server where the image file is located. The image file must be JPEG, PNG or GIF format. Note: If using PHP, make sure to place @ in front of the path to suppress error messages. Otherwise, this endpoint will not work.	"/home/bob/images/myphoto.jpg" "C:\Users\bob\images\myphoto.gif"

Result:
Returns an HTTP status code of 200 if the image was uploaded correctly. Otherwise, returns 0.

PHP Example:

If needing to upload image files which are not located on the ProcessMaker server, first use ssh2_scp_send() to copy the files to the ProcessMaker server, then use the code above to call the /api/1.0/{workspace}/user/{usr_uid}/image-upload endpoint.

Update User Information: PUT /user/{usr_uid}

Update the information about a specified user.

PUT /api/1.0/{workspace}/user/{usr_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
usr_uid	String	User UID

PUT Parameters:

Only set the fields which need to be updated. PUT parameters need to be URL-encoded. In PHP, place the parameters in an associative array and use http_build_query() to encode it. In JavaScript, place the parameters in an object and then use encodeURIComponent() to encode it.

Name	Type	Description
usr_username	String	Optional. Username which is used to login to ProcessMaker and is unique.
usr_firstname	String	Optional. User's first name
usr_lastname	String	Optional. User's last name
usr_email	String	Optional. User's email address
usr_due_date	String	Optional. The date in "YYYY-MM-DD" when the user's account will expire. After this date, the user will not be able to login to ProcessMaker. Ex: "2020-12-31"
usr_status	String	Optional. The user's status, which can be "ACTIVE", "INACTIVE" or "VACATION".
usr_role	String	Optional. The user's role, which can be "PROCESSMAKER_ADMIN", "PROCESSMAKER_OPERATOR", "PROCESSMAKER_MANAGER" or a custom role.
usr_address	String	Optional. The user's address. Use \n to include line breaks in the address. Ex: "345 Radcliff Drive\nC/O Brad Williams"
usr_zip_code	String	Optional. User's zip or postal code.
usr_country	String	Optional. Two letter ISO country code. See the wf_<WORKSPACE>.ISO_COUNTRY table in the database.
usr_city	String	Optional. One or two letter code to identify the region, state or province. Note: This field is misnamed. See the wf_<WORKSPACE>.ISO_SUBDIVISION table in the database.
usr_location	String	Optional. Code which is 1 to 3 letters long to identify the city or locality. See the wf_<WORKSPACE>.ISO_LOCATION table in the database.
usr_phone	String	Optional. The user's telephone number.
usr_cellular	String	Optional. The user's cellular phone number.
usr_fax	String	Optional. The user's fax number.
usr_position	String	Optional. The user's position in the organization.
usr_birthday	String	Optional. The user's birthday in "YYYY-MM-DD" format. Ex: "1984-08-23"
usr_replaced_by	String	Optional. Unique ID of another user who will replace this user if his/her status changes to "INACTIVE" or "VACATION".
usr_new_pass	String	Optional. The user's password. Remember that passwords should adhere to the password security policies.
usr_cnf_pass	String	Optional. Enter the password a second time to confirm it. If this password doesn't match the one in usr_new_pass, then an error will occur.

Result:

If the user account was updated, the HTTP status code is set to 200 and it returns the following object with the updated information about the user:

If an error occurred, the HTTP status code is set to 400 and an error object like the following is returned:

PHP Example:
The following example, changes the status to "VACATION" and sets the user who will replace this user when she goes on vacation.

Note that the following line sets the request to be a PUT request:

Also note that the POST parameters need to be passed to http_build_query() to generate a URL-encoded query string which can be used with PUT requests.

Delete User: DELETE /user/{usr_uid}

Delete a specified user.

DELETE /api/1.0/{workspace}/user/{usr_uid}

Note: This endpoint sets the wf_<WORKSPACE>.USERS.USR_USERNAME field to "" (empty string) in the database, so that the user can no longer be used, but it does NOT delete the user's record from the database.

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
usr_uid	String	User UID

Result:

If the user was successfully deleted, then the HTTP response code will be 200. If an error occurs, then the HTTP response code is set to 400 and an object like the following is returned:

PHP Example:

Groups

The following REST endpoints are used to manage groups, as well as their member users in ProcessMaker.

1. Get a list of all groups

2. Get a single group

3. Create a group

4. Update group

5. Delete a group

Groups - Users

6. List all assigned users to a group

7. List available users to assign to a group

8. Assign users to a group

9. Unassign a user from a group

Available methods:

Get Groups List: GET /groups

Get a list of all the groups in the workspace (including groups with "INACTIVE" status). The groups are returned in alphabetical order.

GET /api/1.0/{workspace}/groups?filter={filter}&start={start}&limit={limit}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name

Optional GET Parameters:

Name	Type	Description
filter	string	Case insensitive string to search for in the group name. For example, "api/1.0/workspace/groups?filter=sal" would return the groups "Sales" and "Condiments & salts".
start	integer	The number of groups where the list begins. The counting starts from the number 0. For example, "api/1.0/workspace/groups?start=3" would start the list of groups with the fourth group.
limit	integer	The maximum number of groups which are returned in the list. For example if wanting to return 10 groups at a time and there are 25 groups in total, then call this endpoint 3 times: "api/1.0/workspace/groups?limit=10" (returns groups 0-9) "api/1.0/workspace/groups?start=10&limit=10" (returns groups 10-19) "api/1.0/workspace/groups?start=20&limit=10" (returns groups 20-24)

Result:

Returns an HTTP status code of 200 and the following array of group objects:

Element	Description
[	Start array
{	Start group object
grp_uid	The group's unique ID.
grp_title	The group's title.
grp_status	The group's status, which can be "ACTIVE" or "INACTIVE".
grp_users	The number of users who are members of the group, including users who have "INACTIVE" and "VACATION" status.
grp_tasks	The number of tasks to which the group is assigned. Note that this number includes tasks which are in deactivated processes, but it does not include ad hoc assignment to tasks.
},	End group object.
...	Additional group objects.
]	End array.

For example:

If there is are no groups, then an empty array is returned. If an error occurs, then

PHP Example: The following example creates an array of the active groups which are assigned to one or more tasks.

Get Group Information: GET /group/{grp_uid}

Get information about a specified group.

GET /api/1.0/{workspace}/group/{grp_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
grp_uid	String	Group UID

Result:

Returns the HTTP status code 200 and the same group object as the GET /groups endpoint. For example:

If a bad request, then it returns the HTTP status code 400 and an error object like this:

PHP Example:

This example prints out how many users are in a group with the ID "47113834154e4a6c5cd1f11014216675":

Create Group: POST /group

Create a new group.

POST /api/1.0/{workspace}/group

URL Parameters:

Name	Type	Description
workspace	String	Workspace name

POST Fields:

Name	Type	Description
grp_title	String	The name of the group.
grp_status	String	The group's status, which can be "ACTIVE" or "INACTIVE". If the group is assigned to a task and its status is "INACTIVE", then members of the group will NOT be assigned to the task when cases are run.

Result:

If a new group was created, then the HTTP status code is 201 and a JSON object with information about the new group is returned. For example:

If a bad request, then the HTTP status code is 400 or greater and a JSON object like the following is returned:

PHP Example:

Update Group: PUT /group/{usr_uid}

Update information about a specified group.

PUT /api/1.0/{workspace}/group/{grp_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
grp_uid	String	Group unique ID.

Optional Fields:

Name	Type	Description
grp_title	String	The group's title.
grp_status	String	Group status, which can be "ACTIVE" or "INACTIVE". If the group is assigned to a task and its status is "INACTIVE", then members of the group will NOT be assigned to the task when cases are run.

Result:

If the group was successfully updated, the HTTP status code is 200 and there is nothing returned.

If it is a bad request, then the HTTP status code is set to 400 or greater, and a JSON object like the following is returned:

PHP Example:
The following example changes the group title to "Accounting" and sets its status to "INACTIVE":

Note that the following line sets the request to be a PUT request:

Also note that the POST parameters need to be passed to http_build_query() to generate a URL-encoded query string which can be used with PUT requests.

Delete Group: DELETE /group/{grp_uid}

Delete a specified group. Note that this endpoint deletes the group's record from the GROUPWF table and its title from the CONTENT table in the database, but it doesn't delete the group's membership list from the GROUP_USER table.

DELETE /api/1.0/{workspace}/group/{grp_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
grp_uid	String	Group unique ID.

Result:

If the group was deleted, then the HTTP status code is 200. Otherwise, the HTTP status code is 400 or greater and a JSON object is returned like the following:

PHP Example:

GROUPS - USERS

Get Group Members: GET /group/{grp_uid}/users

List the assigned users to a specified group.

GET /api/1.0/{workspace}/group/{grp_uid}/users?filter={filter}&start={start}&limit={limit}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
grp_uid	String	Group UID

Optional GET Parameters:

Name	Type	Description
filter	string	Case insensitive string to search for in the user's first name, last name or username. For example, "api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?filter=mit" would return the users "smith", "Mitter" and "solmit".
start	integer	The number of users where the list begins. The counting starts from number 0. For example, "api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?start=3" would start the list of users with the fourth user.
limit	integer	The maximum number of users which are returned in the list. For example if wanting to return 10 users at a time and there are 25 users in total, then call this endpoint 3 times: "api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?limit=10" (returns users 0-9) "api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?start=10&limit=10" (returns users 10-19) "api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?start=20&limit=10" (returns users 20-24)

Result:

If a successful request, the HTTP status code is set to 200 and a JSON array of user objects is returned, like the following one:

If a bad request, then the HTTP status code is 400 or greater and a JSON error object is returned, like this one:

PHP Example:
This PHP example creates a list of active users who are members of a group with the unique ID of "47113834154e4a6c5cd1f11014216675" and places them in the array $aActiveUsers.

Get Available Users: GET /group/{grp_uid}/available-users

Get a list of available users, which can be assigned to a specified group. All users which aren't yet assigned to the group will be listed, including users with "INACTIVE" and "VACATION" status.

GET /api/1.0/{workspace}/group/{grp_uid}/available-users?filter={filter}&start={start}&limit={limit}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
grp_uid	String	Group unique ID.

Optional GET Parameters:

Name	Type	Description
filter	string	Case insensitive string to search for in the user's first name, last name or username. For example, "api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?filter=mit" would return the users "smith", "Mitter" and "solmit".
start	integer	The number of users where the list begins. The counting starts from number 0. For example, "api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?start=3" would start the list of users with the fourth user.
limit	integer	The maximum number of users which are returned in the list. For example if wanting to return 10 users at a time and there are 25 users in total, then call this endpoint 3 times: "api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?limit=10" (returns users 0-9) "api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?start=10&limit=10" (returns users 10-19) "api/1.0/workspace/group/47113834154e4a6c5cd1f11014216675/users?start=20&limit=10" (returns users 20-24)

Result:

If a successful request, the HTTP status code is set to 200 and a JSON array of user objects is returned, like the following one:

If a bad request, then the HTTP status code is 400 or greater and a JSON error object is returned, like this one:

PHP Example:

This example gets a list of the first 10 available users to be assigned to a group with the ID ""47113834154e4a6c5cd1f11014216675":

Assign User to Group: POST /group/{grp_uid}/user

Assign a user to a specified group.

POST /api/1.0/{workspace}/group/{grp_uid}/user

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
grp_uid	String	The group's unique ID

POST Fields:

Name	Type	Description
usr_uid	String	The unique ID of the user who will be added to the group as a member. Note that it is possible to add a user with "INACTIVE" or "VACATION" status to a group, but that user will not be assigned to any cases until his/her status changes to "ACTIVE" status.

Optional Fields:

These fields may be included, but they will be ignored by the REST endpoint.

Name	Type	Description
usr_username	String	Username
usr_firstname	String	User first name
usr_lastname	String	User last name
usr_email	String	User email
usr_status	String	User status

Result:

If the user was assigned to the group, then the HTTP status code is 201 (Created) and there is no return object. Otherwise, it is 400 or greater and returns a JSON error object like:

PHP Example:

Unassign User from Group: DELETE /group/{grp_uid}/user/{usr_uid}

Unassign (remove) a user from a group so no longer a member of the group.

DELETE /api/1.0/{workspace}/group/{grp_uid}/user/{usr_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
grp_uid	String	Group UID
usr_uid	String	Group UID

Result:

If the user was removed from the group, then the HTTP status code is 200 and there is no return object. Otherwise, the HTTP status code is 400 or greater and a JSON error object is returned, such as:

PHP Example:

Departments

These are the REST endpoints to manage departments in ProcessMaker:

1. Get a list of departments
2. Get data of a department
3. Create a department
4. Update a department
5. Delete a department
6. Get the list of assigned users
7. Get a list of available users in a department.
8. v.2.8: Assign a user to a department
9. v.3.0+: Assign a user to a department
10. Unassign a user from a department
11. Set manager user to department

Get Departments List: GET /departments

Get a list of all the departments in the workspace, including departments with "INACTIVE" status.

GET /api/1.0/{workspace}/departments

URL Parameters:

Name	Type	Description
workspace	String	Workspace name

Result:

If successful, the HTTP status code is set to 200 and it returns a JSON array of department objects with the following structure:

Element	Description	Example
[	Start array.
{	Start department object
dep_uid,	The department's unique ID.	"11826545154db794ca22b52025081429"
dep_parent,	The unique ID of the parent department. If this is a top-level deparment, then set to "" (empty string).	""
dep_title,	The department's title.	"Human Resources"
dep_status,	The department's status, which can be "ACTIVE" or "INACTIVE".	"ACTIVE"
dep_manager,	The department's supervisor, to whom the other members of the department and the supervisors of the subdepartments report. By default, the supervisor is the first user assigned to the department.	"14680180454ca4477335a27034362107"
dep_ldap_dn,	The user's distinguished name if imported from LDAP. If a normal user whose account wasn't imported, then then set to "" (empty string).	""
dep_last,	If the last department object in the current array, then set to 1. If not the last, then set to 0.	1
dep_manager_username,	The username of the department's supervisor.	"liliana"
dep_manager_firstname,	The first name of the department's supervisor.	"Liliana"
dep_manager_lastname,	The last name of the department's supervisor.	"Ortiz"
has_children,	The number of subdepartments of this department.	"2"
dep_children	A array of subdepartment objects for this department. If there are no subdepartments, then an empty array.	[]
},	End the department object
{...}	Any additional department objects.
]	End array.

For example:

PHP Example:

This example prints out the directory structure of an organization with the supervisor's name in parentheses.

For the departments shown in the example above, this script would print out:

Get Department Information: GET /department/{dep_uid}

Get information about a specified department.

GET /api/1.0/{workspace}/department/{dep_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
dep_uid	String	Department UID

Result:

If successful, the HTTP status code is 200 and a department object is returned like the GET departments endpoint, but it doesn't include the dep_children array. For example:

If unsuccessful, the HTTP status code is 400 or greater and a JSON error object is returned, such as:

PHP Example:

This example prints out the department's title and its supervisor's full name:

Create Department: POST /department

Create a new department.

POST /api/1.0/{workspace}/department

URL Parameters:

Name	Type	Description
workspace	String	Workspace name

POST Fields:

Name	Type	Description
dep_title	String	Department's title (name). Note that the department's title must be unique, so an error will occur if trying to create a department title which already exists.
dep_parent	String	Optional. Parent department's unique ID. If not included or set to "" (empty string), then this is a top-level department.
dep_manager	String	Optional. Department supervisor's unique ID. Users may only be assigned to ONE department, so the supervisor may NOT be a member of another department.
dep_status	String	Optional. Department status, which can be "ACTIVE" or "INACTIVE". If not included, then "ACTIVE" by default.

Result:

If the new department was created, the HTTP status code is 201 (Created) and a department object is returned, like the following:

Note: The dep_last element in the returned object is always set to 0 and is not correct. To check whether the new department is the last department at the current level, call the GET /departments or GET /department/{dep_uid} endpoint and check the value of the dep_last element.

If an error occurred, the HTTP status code is 400 or greater and an error object is returned, like the following:

PHP Example:

Update Department: PUT /department/{dep_uid}

Update the information about a department.

PUT /api/1.0/{workspace}/department/{dep_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
dep_uid	String	Department UID.

Optional Fields:

Name	Type	Description
dep_title	String	The department title (name), which must be unique.
dep_parent	String	Unique ID of the parent department. Set to "" (empty string) to make a top-level department.
dep_manager	String	Unique ID of the department supervisor, to whom the members of the department [[1]], as well as the supervisors of subdepartments.
dep_status	String	Department status, which can be "ACTIVE" or "INACTIVE".

Result:

If the department was successfully updated, then the HTTP status code is set to 200 and there is no return object. Otherwise, it is set to 400 and greater and returns an error object, such as:

PHP Example:

Delete Department: DELETE /department/{dep_uid}

Delete a specified department. Note that it is not possible to delete a department while it has assigned users, so all the users must be unassigned from the department before deleting it.

DELETE /api/1.0/{workspace}/department/{dep_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
dep_uid	String	Unique ID of the department to be deleted.

Result:

If the department was deleted, the HTTP status code is set to 200 and nothing is returned. Otherwise, it is set to 400 or greater and an error object is returned like the following:

PHP Example:

Departments - Users:

Get Users List for Department: GET /department/{dep_uid}/assigned-user

Get a list of the users assigned to a specified department.

GET /api/1.0/{workspace}/department/{dep_uid}/assigned-user

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
dep_uid	String	Unique ID of department.

Result:

If successful, the HTTP status code is 200 and an array of user objects is returned, like the following:

PHP Example:

This example cycles through all the departments, looking for the username "janedoe" and prints out her department. First it calls the GET /departments endpoint to get a list of departments, then it calls the GET /department/{dep_uid}/assigned-user endpoint for each department and searches for the user.

Available Users List for Department: GET /department/{dep_uid}/available-user

Get a list of the available users, which can be assigned to a specified department. The list contains all users which aren't yet assigned to any department (including users which have "INACTIVE" and "VACATION" status).

GET /api/1.0/{workspace}/department/{dep_uid}/available-user

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
dep_uid	String	Unique ID of department.

Result:

If successful, the HTTP status code is set to 200 and it returns an array of user objects, like the following:

Note that the user objects are not arranged in any particular order.

If an error occurred, the HTTP status code is set to 400 or greater, and an error object is returned, such as:

PHP Example:

Get a list of available users and sort them in alphabetical order according to their full names and print them. All the user objects are placed in the $aUsersWithKeys array which has the full names as the keys and then they are sorted using the ksort() function.

v.2.8: Assign User to Department: PUT /department/{dep_uid}/assign-user/{usr_uid}

Assign a user to a specified department in version 2.8. If using version 3.0 or later, see POST /department/{dep_uid}/assign-user. If the user is already a member of another department, the user will be transfered to the specified department. If reassigning a user who is a supervisor of another department, see this bug.

PUT /api/1.0/{workspace}/department/{dep_uid}/assign-user/{usr_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
dep_uid	String	Unique ID of department.
usr_uid	String	Unique ID of user to assign to the department.

Result:

If the user was assigned to the department, the HTTP status code is 200 and there is no return object. Otherwise, the HTTP status code is 400 or greater and there is a return object such as:

PHP Example:

v.3.0+: Assign User to Department: POST /department/{dep_uid}/assign-user

Assign a user to a specified department in version 3.0 and later. If the user is already a member of another department, the user will be transfered to the specified department. If reassigning a user who is a supervisor of another department, see this bug.

POST /api/1.0/{workspace}/department/{dep_uid}/assign-user

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
dep_uid	String	Unique ID of department.

POST Fields:

Name	Type	Description
usr_uid	String	Unique ID of a user to assign to the department.

Result:

If the user was assigned to the department, the HTTP status code is 201 and there is no return object. Otherwise, the HTTP status code is 300 or greater and there is a return object such as:

PHP Example:

Unassign User from Department: PUT /department/{dep_uid}/unassign-user/{usr_uid}

Unassign a user from a department, so no longer a member of the department. If unassigning a supervisor from a department, see this bug.

PUT /api/1.0/{workspace}/department/{dep_uid}/unassign-user/{usr_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
dep_uid	String	Unique ID of department.
usr_uid	String	Unique ID of the user to unassign from the department.

Result:

If the user was unassigned from the department, the HTTP status code is 200 and there is no return object. Otherwise, the HTTP status code is 400 or greater and there is a return object such as:

PHP Example:

Set Manager for Department: PUT /department/{dep_uid}/set-manager/{usr_uid}

Set a user to be the manager (supervisor) for a department. The other members of the department will report to the manager, as well as the managers of subdepartments. Note that this endpoint has a number of outstanding bugs.

PUT /api/1.0/{workspace}/department/{dep_uid}/set-manager/{usr_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
dep_uid	String	Unique ID of the department.
usr_uid	String	Unique ID of the user to become the the manager of the department.

Result:

If the manager was successfully set, then the HTTP status code is 200 and there is no return object. Otherwise, the HTTP status code is 400 or greater and an error object is returned, like the following:

PHP Example:

Roles

The following REST endpoints are used to manage roles in ProcessMaker.

Roles

1. Get a list of all roles

2. Get a single role

3. Create a role

4. Update a role

5. Delete a role

Roles - Users

6. List assigned users to a role

7. List available users to assign to a role

8. Assign users to a role

9. Unassign user from a role

Roles - Permissions

10. List assigned permissions to a role

11. List available permissions to assign to a role

12. Assign permissions to a role

13. Unassign permissions from a role

Get Roles List: GET /roles

Get a list of the roles in the workspace.

GET /api/1.0/{workspace}/roles

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/roles
Optional filters
filter={text}	Case insensitive text to search for in the role codes (but not the role names). Remember to URL encode in UTF-8, if it contains spaces, symbols or non-ASCII characters, using a function such as urlencode() in PHP or encodeURIComponent() in JavaScript.	/api/1.0/workflow/roles?filter=reviewer
start={number}	Integer which indicates the initial position of the role.	/api/1.0/workflow/roles?start=20&limit=10
limit={number}	Integer which limits the number of roles returned	/api/1.0/workflow/roles?start=30&limit=10

Result:

If successful, the HTTP status is 200 (OK) and an array of role objects is returned, such as:

PHP example

Print out a list of the roles with "ACTIVE" status and the number of users assigned to each role.

Get Role Information: GET /role/{rol_uid}

Get information about a specified role.

GET /api/1.0/{workspace}/role/{rol_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
rol_uid	String	Role UID

Result:

If successful, the HTTP status is set to 200 and an object with information about the role is returned, such as

Create Role: POST /role

Create a new role.

POST /api/1.0/{workspace}/role

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/role

POST fields:

Name	Description
rol_code	The role code, which is an identifier consisting of letters, numbers and underscores ("_"). It may not contain any spaces or special characters.
rol_name	The role name, which is any identifier which can contain any type of characters and is displayed in the ProcessMaker.
rol_status	Optional. Role status, which may be "ACTIVE" or "INACTIVE". If not specified, then set to "ACTIVE" by default. If set to "INACTIVE", any users assigned to the role will not be able to login to ProcessMaker, nor may any cases be assigned to those users.

Result:

If the role was created, then the HTTP status code is set to 201 (Created) and an object containing information about the new role is returned, such as:

Update Role: PUT /role/{rol_uid}

Update information about a specified role.

PUT /api/1.0/{workspace}/role/{rol_uid}

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/role/14539701455e9bf5e9dfc40009566988
rol_uid	Unique ID of role	/api/1.0/workflow/role/14539701455e9bf5e9dfc40009566988

POST fields:

Name	Description
rol_code	Optional. The role code, which is an identifier consisting of letters, numbers and underscores ("_"). It may not contain any spaces or special characters.
rol_name	Optional. The role name, which is any identifier which can contain any type of characters and is displayed in the ProcessMaker.
rol_status	Optional. Role status, which may be "ACTIVE" or "INACTIVE". If set to "INACTIVE", any users assigned to the role will not be able to login to ProcessMaker, nor may any cases be assigned to those users.

Result:

If the information about a case has been updated, then the HTTP status is set to 200 (OK) and there is no return object.

PHP example:

Delete Role: DELETE /role/{rol_uid}

Delete a specified role. Note that it is not possible to delete a role which still has assigned users, so all users must be assigned to different roles before deleting the role.

DELETE /api/1.0/{workspace}/role/{rol_uid}

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/role/14539701455e9bf5e9dfc40009566988
rol_uid	Unique ID of role	/api/1.0/workflow/role/14539701455e9bf5e9dfc40009566988

Result:

If the role is deleted, the HTTP status code is set to 200 and there is no return object. If the HTTP status code is 300 or greater than an error occurred and a error object will usually be returned, such as:

PHP example:

ROLES - USERS

Get Users with Role: GET /role/{rol_uid}/users

Get a list of the users assigned to a role.

GET /api/1.0/{workspace}/role/{rol_uid}/users

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/role/00000000000000000000000000000003/users
rol_uid	Unique ID of role	/api/1.0/workflow/role/00000000000000000000000000000003/users
Optional filters:
filter={text}	Case insensitive text to search for users in their first name, last name or username. Remember to URL encode in UTF-8, if it contains spaces, symbols or non-ASCII characters, using a function such as urlencode() in PHP or encodeURIComponent() in JavaScript.	/api/1.0/workflow/role/00000000000000000000000000000003/users?filter=mary
start={number}	Integer which indicates the initial position of the user in the list.	/api/1.0/workflow/role/00000000000000000000000000000003/users?start=20&limit=10
limit={number}	Integer which limits the number of users returned.	/api/1.0/workflow/role/00000000000000000000000000000003/users?start=30&limit=10

Result:

If successful, the HTTP status code is set to 200 (OK) and an array of user objects is returned, such as:

If no users are assigned to the role, then an empty array will be returned.

Available Users for Role: GET /role/{rol_uid}/available-users

Get a list of users who currently are assigned to other roles and are available to be reassigned to the specified role.

GET /api/1.0/{workspace}/role/{rol_uid}/available-users

Note: The "admin" user may be returned by this endpoint, but the "admin" user cannot be reassigned to another role.

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/role/00000000000000000000000000000003/available-users
rol_uid	Unique ID of role	/api/1.0/workflow/role/00000000000000000000000000000003/available-users
Optional filters:
filter={text}	Case insensitive text to search for in the first name, last name or username of users. Remember to URL encode in UTF-8, if it contains spaces, symbols or non-ASCII characters, using a function such as urlencode() in PHP or encodeURIComponent() in JavaScript.	/api/1.0/workflow/role/00000000000000000000000000000003/available-users?filter=mary
start={number}	Integer which indicates the initial position of the user in the list.	/api/1.0/workflow/role/00000000000000000000000000000003/available-users?start=20&limit=10
limit={number}	Integer which limits the number of users returned.	/api/1.0/workflow/role/00000000000000000000000000000003/available-users?start=30&limit=10

Result:

If successful, the HTTP status code is set to 200 (OK) and an array of user objects is returned, such as:

If no users are assigned to other roles, then an empty array will be returned.

Assign User to Role: POST /role/{rol_uid}/user

Assign a user to a role.

POST /api/1.0/{workspace}/role/{rol_uid}/user

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/role/00000000000000000000000000000003/user
rol_uid	Unique ID of role. The 3 predefined roles in ProcessMaker are Administrator '00000000000000000000000000000002', Operator '00000000000000000000000000000003', and Manager '00000000000000000000000000000004'.	/api/1.0/workflow/role/00000000000000000000000000000003/user

POST Fields:

Name	Type	Description
usr_uid	String	Unique ID of user to be assigned to a role.

Result:

If the user has been successfully assigned to a role, then the HTTP status is set to 201 (Created) and there is no return object.

Note that the "admin" user may not be reassigned to a different role, which generates the following error:

PHP example

Unassign User from Role: DELETE /role/{rol_uid}/user/{usr_uid}

Unassign (remove) a user from a role. It is not recommended to call this endpoint, unless wishing for the user to have no role and be unable to login or be used in any capacity in ProcessMaker. The user will need to be reassigned to another role in order to have any function inside ProcessMaker.

DELETE /api/1.0/{workspace}/role/{rol_uid}/user/{usr_uid}

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/role/00000000000000000000000000000003/user/55625662755e0e42fe83f41018778834
rol_uid	Unique ID of role. The 3 predefined roles in ProcessMaker are Administrator '00000000000000000000000000000002', Operator '00000000000000000000000000000003', and Manager '00000000000000000000000000000004'.	/api/1.0/workflow/role/00000000000000000000000000000003/user/55625662755e0e42fe83f41018778834
usr_uid	Unique ID of user	/api/1.0/workflow/role/00000000000000000000000000000003/user/55625662755e0e42fe83f41018778834

Result:

If unassigned from the role, the HTTP status code is set to 200 (OK) and there is no return object. Otherwise, the HTTP status code is set to 300 or greater and an error object is often returned, such as:

PHP Example

ROLES - PERMISSIONS

Permissions List for Role: GET /role/{rol_uid}/permissions

Get a list of the permissions assigned to a specified role.

GET /api/1.0/{workspace}/role/{rol_uid}/permissions

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/role/00000000000000000000000000000002/permissions
rol_uid	Unique ID of the Role. The 3 predefined roles in ProcessMaker are Administrator '00000000000000000000000000000002', Operator '00000000000000000000000000000003', and Manager '00000000000000000000000000000004'.	/api/1.0/workflow/role/00000000000000000000000000000002/permissions
Optional filters:
filter={text}	Case-insensitive text to search for in the permission codes.	/api/1.0/workflow/role/00000000000000000000000000000002/permissions?filter=setup
start={number}	Position of the initial permission be returned	/api/1.0/workflow/role/00000000000000000000000000000002/permissions?start=5&limit=5
limit={number}	Number of permissions to be returned.	/api/1.0/workflow/role/00000000000000000000000000000002/permissions?start=5&limit=5

Result:

If successful the HTTP status code is 200 and the response is an array of permission objects for the role, such as:

PHP example:

Print out the list of permissions in the PROCESSMAKER_ADMIN role:

Available Permissions for Role: GET /role/{rol_uid}/available-permissions

Get a list of the available permissions, which can be assigned to a specified role.

GET /api/1.0/{workspace}/role/{rol_uid}/available-permissions

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/role/00000000000000000000000000000003/available-permissions
rol_uid	Unique ID of the Role. The 3 predefined roles in ProcessMaker are Administrator '00000000000000000000000000000002', Operator '00000000000000000000000000000003', and Manager '00000000000000000000000000000004'.	/api/1.0/workflow/role/00000000000000000000000000000003/available-permissions
Optional filters:
filter={text}	Case-insensitive text to search for in the permission codes.	/api/1.0/workflow/role/00000000000000000000000000000003/available-permissions?filter=setup
start={number}	Position of the initial permission be returned	/api/1.0/workflow/role/00000000000000000000000000000003/available-permissions?start=5&limit=5
limit={number}	Number of permissions to be returned.	/api/1.0/workflow/role/00000000000000000000000000000003/available-permissions?start=5&limit=5

Result:

If successful the HTTP status code is 200 and the response is an array of available permission objects for the role, such as:

PHP example:

Search through the list of available permissions for the Operator role to see whether it includes the PM_DASHBOARD permission. If available, then assign it to the Operator role:

Assign Permission to Role: POST /role/{rol_uid}/permission

Assign a permission to a role.

POST /api/1.0/{workspace}/role/{rol_uid}/permission

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/role/00000000000000000000000000000003/permission
rol_uid	Unique ID of the Role. The 3 predefined roles in ProcessMaker are Administrator '00000000000000000000000000000002', Operator '00000000000000000000000000000003', and Manager '00000000000000000000000000000004'.	/api/1.0/workflow/role/00000000000000000000000000000003/permission

POST Fields:

Name	Type	Description
per_uid	String	Unique ID of the permission to assign to a role.

Result:

If the permission is successfully assigned to the role, then the HTTP status code is set to 201 (Created) and there is no response.

PHP example:

This example assigns the PM_REASSIGNCASE permission to the Operator role.

Unassign Permission from Role: DELETE /role/{rol_uid}/permission/{per_uid}

Unassign (remove) a permission from a role.

DELETE /api/1.0/{workspace}/role/{rol_uid}/permission/{per_uid}

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/role/00000000000000000000000000000003/permission/00000000000000000000000000000007
rol_uid	Unique ID of the Role. The 3 predefined roles in ProcessMaker are Administrator '00000000000000000000000000000002', Operator '00000000000000000000000000000003', and Manager '00000000000000000000000000000004'.	/api/1.0/workflow/role/00000000000000000000000000000003/permission/00000000000000000000000000000007
per_uid	Unique ID of the permission to unassign from the role.	/api/1.0/workflow/role/00000000000000000000000000000003/permission/00000000000000000000000000000007

Result:

If the permission is successfully unassigned from the role, then the HTTP status code is set to 200 (OK) and there is no response.

Note: Permissions may not be unassigned from the Administrator role (PROCESSMAKER_ADMIN). Trying to unassign from this role will cause the following error:

PHP example:

This example unassigns the PM_REASSIGNCASE permission from the Operator role.

PM Tables

The following REST endpoints are used to manage PM tables in ProcessMaker:

1. Get a list of PM Tables

2. Get a single PM Table

3. Get the data of a PM Table

4. Create a new PM Table

5. Create data in a PM Table

6. Update a PM Table

7. Update data of a PM Table

8. Delete a PM Table

9. Delete data of a PM Table

PM Tables:

Name	Description	Type	Value
pmt_tab_name	PM Table name	String	"name" o "pmt_NAME"(String)
pmt_tab_dsc	PM Table description	String	"PM table description"(String)
fields	PM Table fields	Array
fld_dyn	Field name known in a DynaForm	String	"Acceptance"(String)
fld_name	Field name for the MySQL table creation	String	"ACCEPTED" (String)
fld_label	Field label in the PM graphic	String	"PM Table description"(String)
fld_type	MySQL field type, which may be: "BOOLEAN", "TINYINT", "SMALLINT", "INTEGER", "BIGINT", "DOUBLE", "FLOAT", "REAL", "DECIMAL", "CHAR", "VARCHAR", "LONGVARCHAR", "DATE", "TIME" or "DATETIME"	String	"VARCHAR"(String MySQL type field)
fld_size	MySQL field size	Integer	23 (Numeric)

Available methods:

PM Tables List: GET /pmtable

Get a list of the PM tables in the workspace. It does not include any Report Tables.

GET /api/1.0/{workspace}/pmtable

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/pmtable

Result:

If successful, the HTTP status is set to 200 (OK) and an array of PM Table objects is returned:

[	Start array.
{	Start PM Table object.
"pmt_uid",	Unique ID of the PM Table.
"pmt_tab_name",	Table in the wf_{workspace} database.
"pmt_tab_description",	Description of the PM Table.
"pmt_tab_class_name",	PHP class name for the PM Table.
"pmt_num_rows",	Number of records in the PM Table.
"fields": [	An array of fields in the PM Table.
{	Start Field object.
"fld_uid",	Unique ID of the field.
"fld_index":	Index number of the field, counting from the number 0.
"fld_name":	Name of the field in the database.
"fld_description":	Label of the field.
"fld_type":	Type of the field.
"fld_size":	Field size.
"fld_null":	Set to "1" if a NULL (empty) value is allowed. Otherwise, set to "0".
"fld_auto_increment":	Set to "1" if the field will be auto-incremented. Otherwise, set to "0".
"fld_key":	Set to "1" if a key field, meaning that its values are unique. Otherwise, set to "0".
"fld_table_index":	Set to "1" if the field will be indexed. Otherwise, set to "0".
},	End Field object.
...	Any additional Field objects.
]	End array of Field objects.
},	End PM Table object.
...	Any additional PM Table objects.
]	End array of PM Table objects.

For example:

PHP Example:

Print out the PM Tables and the fields in each table.

Get PM Table Structure: GET /pmtable/{pmt_uid}

Get the structure from a specified PM Table, including a list of its fields and their properties.

GET /api/1.0/{workspace}/pmtable/{pmt_uid}

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/pmtable/33532851355ef56860e8297082884997
pmt_uid	Unique ID of the PM Table	/api/1.0/workflow/pmtable/33532851355ef56860e8297082884997

Result:

If successful, the HTTP status is set to 200 (OK) and a PM Table object is returned, such as:

PHP Example:

Print out the number of records in a PM Table and list the fields in the PM Table.

Get PM Table Data: GET /pmtable/{pmt_uid}/data

Get the data (records) from a PM table.

GET /api/1.0/{workspace}/pmtable/{pmt_uid}/data

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/pmtable/33532851355ef56860e8297082884997/data
pmt_uid	Unique ID of the PM Table	/api/1.0/workflow/pmtable/33532851355ef56860e8297082884997/data

Result:

If successful, the HTTP status is set to 200 (OK) and an object is returned with the rows of data in the PM Table and the number of rows.

For example:

Note: The field names are automatically converted to lowercase.

Note: Integers, floating-point numbers (real numbers) and boolean values are converted to strings. In the above example, the id is an integer and the has_contract is a boolean in MySQL. Also, the __index__ field is automatically created by MySQL to index the PM Table.

PHP Example:

Print out the records in a PM Table in an HTML table. First get the structure of the PM Table with GET /api/1.0/workflow/pmtable/{pmt_uid} in order to print out the label (description) of each field in the headers of the HTML table. Then, get the records with GET /api/1.0/workflow/pmtable/{pmt_uid}/data and print out each record as a record in the HTML table.

Create PM Table: POST /pmtable

Create a new PM Table.

POST /api/1.0/{workspace}/pmtable

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/pmtable

POST Fields:

Name	Description
{	Start object.
"pmt_tab_name",	The name of the PM Table, which only consists of ASCII letters, numbers and underscores ("_"). It will automatically be converted to UPPERCASE. It is strongly recommended that it begin with "PMT_".
"pmt_tab_dsc",	Optional. Description of the PM Table.
"fields"	An array of field objects.
[	Start the array.
{	Start object defining field.
"fld_name",	The field name, which should only contain ASCII letters, numbers and underscores ("_"). It will automatically be converted to UPPERCASE. It is recommended that it be in UPPERCASE.
"fld_label,	The field's label.
"fld_type",	The field type, which can be: BIGINT: An integer of 8 bytes between -9223372036854775808 and 9223372036854775807. BOOLEAN: A binary value of either 1 (true) or 0 (false), but this stored as an INTEGER in the database. CHAR: A string of a characters between 0 and 255 in length. The number of characters stored in the database is fixed. If the field size is 100, then 100 characters are stored in the database, even if the value in the field has fewer characters. DATE: A date in the 'YYYY-MM-DD' format. The supported range is '1000-01-01' to '9999-12-31'. DATETIME: A datetime in the 'YYYY-MM-DD HH:MM:SS' format. The supported range is '1000-01-01 00:00:00' to '9999-12-31 23:59:59'. DECIMAL: A decimal number, which has exactly 2 decimal digits. This is the recommended type when using currency. DOUBLE: A decimal number of 8 bytes. The supported range is -1.7976931348623157E+308 to -2.2250738585072014E-308, 0, and 2.2250738585072014E-308 to 1.7976931348623157E+308. FLOAT: A decimal number of 4 bytes. The supported range is -3.402823466E+38 to -1.175494351E-38, 0, and 1.175494351E-38 to 3.402823466E+38. INTEGER: An integer of 4 bytes between -2147483648 and 2147483647. LONGVARCHAR: A string of a variable number of characters, between 0 and 16,777,215 characters long. This is a synonym for a MEDIUMTEXT field. REAL: A synonym for DOUBLE (unless the REAL_AS_FLOAT SQL mode is enabled). SMALLINT: An integer of 2 bytes between -32768 and 32767. TIME: The time in 'HH:MM:SS' format. TIMESTAMP: A synonym for DATETIME. TINYINT: An integer of 1 byte between -128 and 127. VARCHAR: A string of a variable number of characters, between 0 and 255 characters in length before MySQL 5.0.3 and between 0 and 65,535 characters in MySQL 5.0.3 and later.
"fld_size",	The field size is required for CHAR and VARCHAR fields, where it sets the maximum number of allowed characters. The field size is optional for BOOLEAN, TINYINT, SMALLINT, INTEGER and BIGINT fields, where it sets the maximum number of allowed digits. It is also optional for FLOAT, REAL and DECIMAL fields, where it sets the maximum number of digits before the decimal point. The number of decimal digits cannot be specified, although it is automatically set to 2 in DECIMAL fields. For example, setting fld_size to 4 allows numbers between -9999.X and 9999.X with the number of decimals determined by the maximum for the data type. The fld_size should NOT be included in DOUBLE, DATE, TIME, DATETIME, TIMESTAMP and LONGVARCHAR fields or it will cause a 400 error with no response object. Likewise, a 400 error will be caused if the fld_size is set to a value larger than the allowed size, such as 50 for an INTEGER.
"fld_null",	Optional. Set to 1 if this field may have a value of NULL, meaning "no data". Otherwise, set to 0, meaning that the field must have a value. If not included, then set to 1 by default.
"fld_autoincrement",	Optional. Set to 1 if this field will be auto-incremented, meaning that the value will be automatically inserted as the maximum existing value in the field plus 1. This option is recommended for ID fields. Otherwise set to 0, which is the default.
"fld_key"	Optional. Set to 1 if this field should be a primary key field, meaning that its value will be unique and it will used to index the table. Otherwise set to 0, which is the default if not included.
}	End of object defining the field.
...	Any additional field objects.
]	End array of field objects.
}	End object.

Result:

If the table is created, then the HTTP status code is set to 201 (Created) and a object is returned with information about the new PM Table. See the JSON example below.

JSON example:

Request:

Response:

PHP example:

Note: If using PHP, the POST variables will need to be passed through the http_build_query() which will cause problems with fields which include the fld_size. The ProcessMaker source code needs to be changed to avoid an error.

Add PM Table Data: POST /pmtable/{pmt_uid}/data

Add a new record to a PM Table.

POST /api/1.0/{workspace}/pmtable/{pmt_uid}/data

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/pmtable/22815673755f209dd749c90081062413/data
pmt_uid	Unique ID of PM Table	/api/1.0/workflow/pmtable/22815673755f209dd749c90081062413/data

POST Fields:

The following object where the member variables have the same names as the fields in the PM Table and their values will be inserted in a new record in the PM Table.

For example:

Result:

If successful, the HTTP status is set to 201 (Created) and the new record which has been inserted in the PM Table is returned, with the field names in lowercase.

PHP example:

'; }

Note: Remember that ProcessMaker's MySQL database stores character data in the UTF-8 character set, so any strings should be converted to UTF-8 if they are in another character set, using a function such as iconv() in PHP.

Update PM Table Structure: PUT /pmtable/{pmt_uid}

Update the structure of a PM table.

PUT /api/1.0/{workspace}/pmtable/{pmt_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
pmt_uid	String	PM Table UID

Optional Fields:

Name	Type	Description
pmt_tab_dsc	String	PM Table description
fields	Array

Result:

Type	Description
empty	No return

Example:
Request

Response

Update PM Table Data: PUT /pmtable/{pmt_uid}/data

Update the data of an existing record in a PM table.

PUT /api/1.0/{workspace}/pmtable/{pmt_uid}/data

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
pmt_uid	String	PM Table UID

POST Fields:

An object where the member variables have the same names as the fields in the PM Table and their values will be inserted in an existing record in the PM Table.

Result:

Type	Description
empty	No return

Example:
Request

Response

Delete PM Table: DELETE /pmtable/{pmt_uid}

Delete a specified PM table and all its data.

DELETE /api/1.0/{workspace}/pmtable/{pmt_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
pmt_uid	String	PM Table UID

Result:

Type	Description
empty	No return

Example
Response

Delete PM Table Data: DELETE /pmtable/{pmt_uid}/data/...

Delete a record from a PM table, by specifying its primary key(s). The PM Table can have up to 3 primary key fields.

DELETE /api/1.0/{workspace}/pmtable/{pmt_uid}/data/{key1}/{value1}

(/api/1.0/{workspace}/pmtable/{pmt_uid}/data/{key1}/{value1}/{key2}/{value2})

(/api/1.0/{workspace}/pmtable/{pmt_uid}/data/{key1}/{value1}/{key2}/{value2}/{key3}/{value3})

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
pmt_uid	String	PM Table UID
key1/key2/key3	String	Name of the PM Table primary key field (depending on the number of key fields in the table)
value1/value2/value3	String	Value of the PM Table primary key field (depending on the number of key fields in the table)

Result:

Type	Description
empty	No return

Example:
Response

Categories

The following REST endpoints are used to manage process categories in ProcessMaker.

1. Get a list of categories

2. Get a category

3. Create a category

4. Update category

5. Delete a category

Category:

Name	Description	Type	Value
cat_uid	Category UID	String	"9541049475298f190420f51086854718" String of 32 characters
cat_name	Category name	String	"Other categories"
cat_total_processes	Total number of processes that belong to the Category	Integer	10
Other Parameters
filter	Search filter	String	"a,b,c..."
start	Indicates the initial position of the records returned	String	0,...
limit	Restricts the size of records returned	String	25,...

Available methods:

Get Categories List: GET /project/categories

Get a list of the categories in the workspace.

GET /api/1.0/{workspace}/project/categories?filter={filter}&start={start}&limit={limit}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name

Optional Parameters:

Name	Type	Description
filter	String	Search filter
start	Integer	Indicates the initial position of the records returned
limit	Integer	Restricts the size of records returned

Result:

Type	Description
array	Returns an array of objects with categories

Example:
Response

Get Category Information: GET /project/category/{cat_uid}

Get the information about a category.

GET /api/1.0/{workspace}/project/category/{cat_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
cat_uid	String	Category UID

Result:

Returns an object with information about the specified category.

Example:
Response

Create Category: POST /project/category

Create a new process category.

POST /api/1.0/{workspace}/project/category

URL Parameters:

Name	Type	Description
workspace	String	Workspace name

POST Fields:

Name	Type	Description
cat_name	String	Category name

Optional POST Fields:

Name	Type	Description
cat_total_processes	Integer	Total number of processes that belong to the category

Result:

Returns an object with data about the new category.

Example:
Request

Response

Update Category: PUT /project/category/{cat_uid}

Update an existing category.

PUT /api/1.0/{workspace}/project/category/{cat_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
cat_uid	String	Category UID

Optional Fields:

Name	Type	Description
cat_name	String	Category name
cat_total_processes	Total number of processes that belong to the category	Integer

Result:

Type	Description
empty	No return

Example:
Request

Response

Delete Category: DELETE /project/category/{cat_uid}

Delete a category.

DELETE /api/1.0/{workspace}/project/category/{cat_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
cat_uid	String	Category UID

Result:

Type	Description
empty	No return

Example:
Response

Calendars

The following REST endpoints are available to manage calendars in ProcessMaker.

1.Get a list of calendars

2.Get a calendar

3.Create a calendar

4.Update calendar

5.Delete calendar

Calendar:

Name	Description	Type	Value
cal_uid	Calendar UID	String	"9541049475298f190420f51086854718" String of 32 characters
cal_name	Calendar name	String	"Default calendar"
cal_description	Calendar description	String	"Description"
cal_work_days	Work days	Array	[1, 2, 3, 4, 5, 6, 7]
cal_status	Status	String	"ACTIVE", "INACTIVE" (Unique values)
cal_work_hour	Work hours	object	Object array
cal_work_hour . day	Day	Integer	0, 1, 2, 3, 4, 5, 6, 7 (Unique values) 0: All, 1: Monday, 2: Tuesday, 3: Wednesday, 4: Thursday, 5: Friday, 6: Saturday, 7: Sunday
cal_work_hour . hour_start	Start hour	String	"00:00"
cal_work_hour . hour_end	End hour	String	"23:59"
cal_holiday	Holidays	Object	Object array
cal_holiday . name	Holiday name	String	"Name"
cal_holiday . date_start	Holiday start date	String	"2014-04-01"
cal_holiday . date_end	Holiday end date	String	"2014-04-01"
cal_create_date	Creation date (According to setting in "Global Date Format")	Datetime	"2012-10-22 14:51:11"
cal_update_date	Update date (According to setting in "Global Date Format")	Datetime	"2012-10-22 14:51:11"
cal_total_users	Total number of users according to the calendar	Integer	0,1,...
cal_total_processes	Total number of processes according to the calendar	Integer	0,1,...
cal_total_tasks	Total number of tasks according to the calendar	Integer	0,1,...
filter	Search filter	String	"abc"
start	Indicates the initial position of the records returned	Integer	0,1,...
limit	Restricts the number of records returned	Integer	25,...

Available methods:

Get Calendar List: GET /calendars

Get a list of calendars in the workspace.

GET /api/1.0/{workspace}/calendars?filter={filter}&start={start}&limit={limit}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name

Optional Parameters:

Name	Type	Description
filter	String	Search filter
start	Integer	Indicates the initial position of the records returned
limit	Integer	Restricts the number of records returned

Result:

Type	Description
array	Returns an array of objects with each calendar

Example:
Response

Get Calendar Information: GET /calendar/{cal_uid}

Get information about a specified calendar.

GET /api/1.0/{workspace}/calendar/{cal_uid}

Parameters

Name	Type	Description
workspace	String	Workspace name
cal_uid	String	Calendar UID

Result

Type	Description
object	Returns an object with data of the calendar

Response

Create Calendar: POST /calendar

Create a new calendar.

POST /api/1.0/{workspace}/calendar

URL Parameters:

Name	Type	Description
workspace	String	Workspace name

POST Fields:

Name	Type	Description
cal_name	String	Calendar name
cal_work_days	Array	Work days

Optional POST Fields:

Name	Type	Description
cal_description	Description	String
cal_status	String	Calendar status
cal_work_hour	Object	Work hours
cal_work_hour . day	Integer	Calendar days
cal_work_hour . hour_start	String	Start hour
cal_work_hour . hour_end	String	End hour
cal_holiday	Object	Holidays
cal_holiday . name	String	Holiday name
cal_holiday . date_start	String	Holiday start date
cal_holiday . date_end	String	Holiday end date
cal_create_date	Datetime	Calendar creation date
cal_update_date	Datetime	Calendar update date
cal_total_users	Integer	Total number of users registered according to the calendar
cal_total_processes	Integer	Total number of processes according to the calendar
cal_total_tasks	Integer	Total number of tasks according to the calendar

Result:

Type	Description
object	Returns an object with the new calendar data plus the cal_uid attribute

Example:
Request

Response

Update Calendar: PUT /calendar/{cal_uid}

Update an existing calendar.

PUT /api/1.0/{workspace}/calendar/{cal_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
cal_uid	String	Calendar UID

Optional Fields:

Name	Type	Description
cal_name	String	Calendar name
cal_work_days	Array	Work days
cal_description	Description	String
cal_status	String	Calendar status
cal_work_hour	Object	Work hours
cal_work_hour . day	Integer	Calendar days
cal_work_hour . hour_start	String	Start hour
cal_work_hour . hour_end	String	End hour
cal_holiday	Object	Holidays
cal_holiday . name	String	Holiday name
cal_holiday . date_start	String	Holiday start date
cal_holiday . date_end	String	Holiday end date
cal_create_date	Datetime	Calendar creation date
cal_update_date	Datetime	Calendar update date
cal_total_users	Integer	Total number of users registered according to the calendar
cal_total_processes	Integer	Total number of processes according to the calendar
cal_total_tasks	Integer	Total number of tasks according to the calendar

Result:

Type	Description
empty	No result

Example:
Request

Response

Delete Calendar: DELETE /calendar/{cal_uid}

Delete a calendar.

DELETE /api/1.0/{workspace}/calendar/{cal_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
cal_uid	String	Calendar UID

Result:

Type	Description
empty	No return

Example:
Response: