API Tutorials for User Endpoints – PlanRadar HelpCenter

Overview

In this article, you’ll find tutorials on managing users in PlanRadar via API, including creating users, assigning roles and permissions, adding them to projects or groups, and changing user types.

Find other tutorials in Open API Overview > API Tutorials.

Creating Users

When creating a new user using API, make sure to include all the data related to the new user user. This includes mentioning user’s basic data as well as their role in the company and the project/s they are a part of.

Creating a new user

You can create users using the API:

POST /api/v1/{customer_id}/users

The request body of adding a new user is divided into five parts. These are:

User type

There are three user types; subcontractor, watcher, and in-house. Mark the attribute that mentions the user's type as true. If the user is an in-house user, mark both attributes, subcontractor and watcher, as false.

Check Permissions for more information about PlanRadar’s user types and roles.

User data

In the request body, include the basic data of the new user; such as, name, company name, phone number, etc. The body also contains the typed values of the users custom fields which are already defined before.

User permissions

This part of the request body defines the pages to which the user has access. However, the permission “defects” must be true.

Adding user to a project

In the request body, the user is added to the project that is sent in attribute project_ids and the role_ids. The role_ids determines the role of the user in the projects. To get a list of all roles created in the account, use the API: GET /api/v1/{customer_id}/roles. And for the project ID, use the the API: GET /api/v1/{customer_id}/projects.

Adding user to a group

If you'd like to add a user to one of the pre-created groups in the account, include the group_ids in the request body. To get the IDs of the groups in your account, use the API: GET /api/v1/{customer_id}/projects/{project_id}/project_groups.

A sample request body:

{
	"attributes": {
		"active": true,
		"company": "Planradar",
		"firstname": "new",
		"group_ids": [
			"lm"
		],
		"is_mobile_syncs": [
			true
		],
		"lastname": "user",
		"tel": "64996197",
		"position": "Dev",
		"street": "street",
		"zipcode": "1486",
		"city": "adwawf",
		"mail": "new@user.com",
		"password": "test123",
		"permissions": {
			"defects": true,
			"projects": true,
			"groups": true,
			"statistics": true,
			"users": false,
			"roles": false,
			"limited_projects": false,
			"api_documentation_access": false
		},
		"project_ids": [
			"mdaown"
		],
		"retype_password": "test123",
		"role_ids": [
			"lwm"
		],
		"subcontractor": false,
		"watcher": false,
		"typed-values": {
			"fe4f11eefc404d2d9f06efe58e0b8e90": "wauhfiojhoi",
			"0d3e3e57da6748fd88705fa6c08713c5": "04:00",
			"3eaec354543742b2ba7fdccb2a280627": true,
			"a1e373428d2a49a58ef2ad8ae7b40083": {
				"label": "Category #10",
				"value": "zgdq"
			}
		}
	}
}

After creating the user, an email will be sent to the user notifying them of the new account as well as the project/s they’ve been added to.

Deleting a user from a project

To remove a member from a project, use the API:

DELETE /api/{customer_id}/projects/{id}/remove_member_from_project

Change User Type

In your PlanRadar account, the users are categorized into three types; In-House user, Subcontractor, and Watcher. Each user type has their own permissions.

User type gets assigned when the user is added to the account. However, the user can be upgraded/downgraded afterwards.

You can change the user type from your PlanRadar account or by using APIs. To change the user type via API, follow the upcoming steps:

Change the user type to “Subcontractor”

To change the user type to “Subcontractor“, use the API:

PUT /api/v1/{customer_id}/users/downgrade_user_to_subcontractor

In the request body, include the user ID and mark the parameter “watcher“ as false.

To get your user ID, use the API GET /api/v1/{customer_id}/users

A sample request for changing the user type to “Subcontractor“ is as follows:

{ "data": { "attributes": { "user_id": "string", "watcher": false } } }

Change the user type to “Watcher”

To change the user type to “Watcher“, use the API:

PUT /api/v1/{customer_id}/users/downgrade_user_to_subcontractor

In the request body, include the user ID and mark the parameter “watcher“ as true.

To get your user ID, use the API GET /api/v1/{customer_id}/users

A sample request for downgrading the user type to “Watcher“ is as follows:

{ "data": { "attributes": { "user_id": "string", "watcher": true } } }

Upgrade the user type to “In-House user”

To upgrade a user type from “watcher”/”subcontractor” to an “In-House” user, call this API:

PUT /api/v1/{customer_id}/users/{user_id}

In the request body, include the user ID and mark the parameters “watcher“ and “Subcontractor“ as false. Meanwhile, mark the parameter “Upgrade“ as true.

A sample request for upgrading the user type to “In-House“ is as follows:

{ "data": { "attributes": { "active": true, "city": "", "company": "PlanRadar", "firstname": "", "group_ids": ["null"], "is_mobile_syncs": [ true ], "lastname": "smith", "mail": "string", "password": "string", "permissions": {}, "position": "intern", "project_ids": ["", ""], "retype_password": "string", "role_ids": [""], "street": "", "tel": "", "typed-values": {}, "subcontractor": false, "watcher": false, "upgrade": true } } }