Skip to main content
Show all results

API Tutorials for Project Endpoints

Tobias Patek
  • Updated

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. You can also include 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 their 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: specify the page number 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

Once you've created a project and set up its plan, you can add the ticket forms your project will use.

Add forms to your project

Use the following endpoint to add ticket forms to a project:

POST /api/v1/{customer_id}/projects/{project_id}/ticket_types_project

Include the following in the request body:

  • ticket-type-id - identifies the ticket form to add
  • field IDs of required fields - specifies which ticket fields must be filled in
  • list IDs - specifies which lists to include in the form, along with their respective items

Look up IDs

To find the ticket-type ID, field IDs, list IDs, and list item IDs for a specific project, call:

GET /api/v1/{customer_id}/ticket_types

This returns all ticket forms for the account. Locate the correct form by name, then copy the relevant IDs for your request.

Sample request body

{
  "data": {
    "attributes": {
      "ticket-type-id": "ngyyqkp",
      "required-fields": ["tf9fc8c95e6d17b817", "subject"],
      "approval-workflows-ids": []
    }
  },
  "included": [
    {
      "type": "lists-ticket-types",
      "attributes": {
        "field-name": "tf9fc8c95e6d17b817",
        "list-id": "bjjkqdq",
        "allow-extra-options": false,
        "select-all": true,
        "list-items": [
          "ymdeejkb",
          "lmqwwzee",
          "ogqllxpy"
        ],
        "allow-multiple-selection": false
      }
    },
    {
      "type": "lists-ticket-types",
      "attributes": {
        "field-name": "tfb7066658145d049b",
        "list-id": "dxxyodm",
        "allow-extra-options": false,
        "select-all": true,
        "list-items": [
          "ogqllxyy",
          "mdqeeaxb"
        ],
        "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, specify the role ID to assign to the added users. 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

Selecting which users to add

There are two ways to specify which users to add:

  • white_list - Pass a list of specific user IDs to add only those users.
  • all: true - Add all users in the account who aren't already members of the project. User IDs included in black_list will be skipped for this call.  This is useful with all: true when you want to add everyone except a few specific users - rather than building a large list client-side, you can simply exclude the ones you don't want.

Note that black_list only affects this request. To remove a user who is already a member of a project, use the remove member API instead (see below).

Also specify whether you'd like your users to be able to use the mobile app to download the project data or not, using the is_mobile_sync attribute.

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. Use the following endpoint to retrieve project details:

  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:

  1. Default Fields (e.g., Name, Description, etc.) → These fields are always present in the response body, regardless of whether they have an assigned value.
  2. 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".

Related articles

Comments

0 comments

Please sign in to leave a comment.