Overview
In this article, you’ll find step-by-step tutorials on creating and managing projects via the PlanRadar API, including creating projects, adding plans and layers, assigning forms and users, retrieving project details, and deleting projects.
Find other tutorials in Open API Overview > API Tutorials.
Introduction
Creating a full project using APIs instead of using the app combines various steps. These APIs are responsible for adding forms, layers, and users to the projects. So, they allow you to simply create a full project using only the APIs.
Since you will be adding/creating elements to your project using these APIs, all the APIs used contain the command POST. Other parameters differ depending on the data you want to include in your project.
Here’s a step by step on what each API should include to create a full project:
Creating a project
The first thing you need to do is create a project by using the following API.
POST /api/v1/{customer_id}/projects
Creating a project using APIs requires only adding the customer ID. However, you still can add the main information of the project, such as:
- Project name
- Project address
- Project description
- Project website
A sample request for creating a project:
{
"data": {
"attributes": {
"name": "firstproject",
"projectnumber": 0,
"zipcode": "1010",
"city": "Vienna",
"country": "Austria",
"description": "This is the first project",
"homepage": "https://www.planradar.com",
"budget": 0,
"drend_date": "string",
"drstart_date": "string",
"identifier": "string",
"is_active": true,
"is_public": true,
"fields": [{
"edit": true,
"id": "b5723873-a607-4ea6-956a-6d5663f1953b",
"name": "first-field",
"type": "CustomFields::LongTextType",
"value": "firstvalue"
}]
}
}
}
In the response, all the data of the newly created project will be listed. Make sure to save the project ID as you will need it in the rest of the APIs to create a full project.
A sample response:
{
"data": {
"id": "mgllka",
"type": "projects",
"attributes": {
"id": "mgllka",
"name": "firstproject",
"homepage": "https://www.planradar.com",
"country": "Austria",
"projectnumber": "0",
"typed-fields": [{}],
"description": "This is the first project",
"city": "Vienna",
"zipcode": "1010",
"street": "Some Street",
"status": 0,
"author-id": "xmqenzn",
"typed-values": {}
}
}
}
The user who created the project will be automatically added to it with the administrator role. Thus, an email will be sent to his/her email address notifying them that they've been added to a new project.
Adding project plans
This API allows you to upload plans to existing projects. It accepts both creating a layer without a plan as well as a layer containing a plan.
The API allows uploading a file of the plan or using a URL containing the plan. Adding layers to your project is important as tickets can only be created on a layer.
Adding Layers without Plans
API:
POST /api/v1/{customer_id}/projects/{project_id}/components
You can create a layer without attaching a plan to it. The request body for such a layer can look like:
{
"data": [
{
"attributes": {
"layers": [
{
"name" : "test plan up",
"parent-id": "xqxx"
}
]
}
}
]
}
If you want to place your newly created layer under an existing layer, add the ID of the parent layer in your request body. When a layer ID is set, the new layer will be added as a child of that layer. Otherwise, the layer will be added to the root. To get the IDs of all the project plans, use the API:
GET /api/v1/{customer_id}/projects/{project_id}/components
Adding Layers and Plans
API:
POST /api/v1/{customer_id}/projects/{project_id}/components
Sample request:
{
"data": [
{
"attributes": {
"file-name": "site-report-temp.pdf",
"file-content-type": "application/pdf",
"file-created-at": date,
"file": (binary),
"layers": [
{
"name" : "test plan up",
"page": 1,
"parent-id": "xqxx",
"order": 5
}
]
}
}
]
}
If you are using a pdf file to upload the plan instead of a URL, here’s the data to include in your request:
- *
file-name: include the name of the plan file - *
file-content-type: mention the mime type of the file (pdf, jpeg, etc.) -
file: the plan file, binary data are accepted -
page: write the number of the pages included in the plan file -
name: the name of the plan -
parent-id: type the parent layer ID. -
order: mention the order of the parent layer among other layers.
* file_name, and file_content_type are only needed if the file attribute is in base64 format, otherwise you can skip them
In all cases, after a successful layer/plan creation, the response body includes the plan ID and its parent layer ID. It also includes other information regarding the plan, such as its creation date and time, update time, user ID, etc.
You can also delete any plan by using the API:
DELETE /api/v1/{customer_id}/projects/{project_id}/components/{id}
Adding project forms
After creating the project and adding all of its plan, you can start adding the ticket forms you need to use with the project. To add project forms, use the API:
POST /api/v1/{customer_id}/projects/{project_id}/ticket_types_project
In the body request, include the following:
- Customer id: use either your hashed or un-hashed customer ID
- Project id: add the ID of your newly created project
- List id: add the list id/s you want to include in your new form. Use this API:
GET /api/v1/{customer_id}/projects/{project_id}/ticket_types
This API calls all your ticket forms and find the list ID you want to use. After adding the list ID, you can specify the list items you want to use. If you want to include all items on a list, do not specify any.
Here’s a sample request:
{
"data": {
"attributes": {
"ticket-type-id": "xmwp",
"required-fields": [
"string"
]
}
},
"included": [{
"type": "lists-ticket-types",
"attributes": {
"list-id": "gwgw",
"field-name": "tf29b038634ac7d062",
"list-items": [
"string"
],
"allow-multiple-selection": false
}
}]
}
In case you want to delete a form from a project, use the API:
DELETE /api/v1/{customer_id}/projects/{project_id}/ticket_types_project/{ticket_type_project_id}
This API will delete the link between the form and your project but won’t delete the form from your account.
Adding users to projects
To add users to your project, use this API:
POST /api/v1/{customer_id}/projects/{project_id}/add_member_to_project
Request Body:
{
"data": {
"attributes": {
"all": true,
"is_mobile_sync": true,
"white_list": [
"byk"
],
"black_list": [
"lmw"
],
"roleId": "neypzq"
}
}
}
In your request, mention the customer IDs of the users you want to add as well as the role ID. To get a list of all roles created in the account, use the API:
GET /api/v1/{customer_id}/roles
And to get all users in the account, use the API:
GET /api/v1/{customer_id}/users
Also specify whether you’d like your user to be able to use the mobile app to download the project data or not.
To remove a member from a project, use the API:
DELETE /api/{customer_id}/projects/{id}/remove_member_from_project
So, these are all the APIs you might need to create a full project. One last API you might need is the one to delete the project:
DELETE /api/v1/{customer_id}/projects/{project_id}
GET project details
With PlanRadar, you can get all the details for a specific project using APIs, here is a step-by-step guide to use the APIs,
-
to get the project details call the API:
GET /api/v2/{{Customer ID}}/projects/{{Project ID}} - Sample response::
{
"data": {
"id": "nwmkdb",
"type": "projects",
"attributes": {
"id": "nwmkdb", //project ID
"name": "Project1", //Project Name
"parent-id-hashed": "kkdzpd",
"homepage": "",
"country": null,
"projectnumber": null,
"created-on": "2025-01-17T11:37:47.975Z",
"updated-on": "2025-02-11T07:19:41.349Z",
"drstart-date": "2025-01-17T11:37:47.000Z",
"typed-fields": [ //all of the local custom fields at the project level
{
"id": "86fa7ae9-14ac-418d-9b86-03e866efc009",
"name": "local custom field",
"type": "CustomFields::LongTextType",
"base_field": true,
"edit": false,
"value": ""
}
],
"drend-date": null,
"description": null, //project description
"running-number": 6,
"access-token": null,
"city": null,
"zipcode": null,
"street": null,
"author-id": "lmqjnkn",
"schedule-start-date": null,
"typed-values": { // only the assigned Global custom fields
"53c6f336baf143f4bcbdfd3dbe822fb7": "Global Custom field"
},
"status": 1
},
"relationships": {
"groups": {
"data": []
},
"project-memberships": {
"data": [
{
"id": "lmpjwkl",
"type": "project-memberships"
}
]
},
"author": {
"data": {
"id": "lmqjnkn",
"type": "users"
}
},
"project-working-days": {
"data": {
"id": "wndndg",
"type": "project-working-days"
}
}
}
},
"included": [
{
"id": "wndndg",
"type": "project-working-days",
"attributes": {
"id": "wndndg",
"country": null,
"region": null,
"weekdays": [
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday"
],
"project-id": "nwmkdb",
"customer-id": "kkdzpd",
"public-holiday": null
},
"relationships": {
"projects": {
"data": {
"id": "nwmkdb",
"type": "projects"
}
}
}
}
]
}
N.B.:
In our projects, we have three types of fields:
- Default Fields (e.g., Name, Description, etc.) → These fields are always present in the response body, regardless of whether they have an assigned value.
- Custom Fields:
-
Local Custom Fields → These are customized at the project level and are always included in the response body in the object
"typed-fields", regardless of whether they have an assigned value. -
Global Custom Fields → These are customized at the global level and exist across all projects, but they appear in the response body only if they have an assigned value, and they are returned in the object
"typed-values".
Comments
0 comments
Please sign in to leave a comment.