Skip to main content
Show all results

API Tutorials for Ticket Endpoints

Tobias Patek
  • Updated

Overview

In this article, you’ll find tutorials on creating and managing tickets via the PlanRadar API, including creating and updating tickets (single and batch updates), setting key ticket fields (status, priority, assignee, due date), and managing ticket attachments (add, update, delete, and retrieve).

Find other tutorials in Open API Overview > API Tutorials.

Creating a ticket

With PlanRadar, you can create a ticket in a project using APIs. You will be able to add tickets to projects, specifying all ticket details.

Here’s a step by step on what each API should include to create a ticket: 

To create a ticket, use the following API:

POST /api/v2/{customer_id}/projects/{project_id}/tickets

Creating a ticket using APIs requires adding the project ID, ticket form and layer:

  • Project ID: Adding the project ID is crucial to creating a ticket using APIs, without it, no ticket can be created. To get all project IDs in your account, use the API: GET /api/v2/{customer_id}/projects/my_projects
  • Ticket form: In your request URL, you need to specify the form of the ticket to be created. To get the ticket forms added to your project, use the API: GET /api/v2/{customer_id}/projects/{project_id}/ticket_types/ticket_type_project
  • Ticket layer: Specify which layer the ticket should be posted on. To get the IDs of all the layers in your project, use the API: GET /api/v2/{customer_id}/projects/{project_id}/components/project_components

Furthermore, any field that is set as mandatory in your form. However, there are other data that can be added, such as:

  • Ticket subject: This simply refers to the ticket title. Add a name that describes the purpose of creating the ticket.
  • Assignee: For your ticket to be created, add an assignee in your request. To call all users in your account, user the API: GET /api/v2/{customer_id}/projects/{project_id}/ticket_types/ticket_type_project
  • Due date: Add the ticket due date to your request URL.
  • Ticket Status: Add your ticket status to your request. Use the following numbers in your request to indicate the ticket status: [1= Open, 2 = In-Progress, 3 = Resolved, 4 = Feedback, 5 = Closed, 6 = Rejected].
  • Ticket Priority: Add your ticket priority to your request. Use the following numbers in your request to indicate priority: [1 = Low, 2 = Normal, 3 = High]

A sample request for creating a ticket:

{ "data": { "attributes": { "subject": "Fire distinguisher to be replaced", "ticket-type-id": "nmwdzz", "parent-id": "null", "status-id": 1, "component-id": "ogzyndp", "priority-id": 2, "assigned-to-id": "zxwymlz", "due-date": "2023-09-10T07:09:46.246Z", "extension-date": "null", "typed-values": { "tf6e915c90543b14f2": null }, "subscribers": [ 0 ], "progress": 1, "plan-x": null, "plan-y": null } } }

In the response, all the data of the newly created ticket will be listed.

A sample response:

{ "data": { "id": "ymndjbal", "type": "tickets", "attributes": { "uuid": "35b03889-e799-4ded-b848-24337eea10d2", "author-id": "jeqxjq", "updated-by-id": null, "component-id": "ogzyndp", "ticket-type-id": "nmwdzz", "customer-id": "jdkkao", "plan-id": null, "plan-z": null, "subject": "Fire distinguisher to be replaced", "status-id": "lm", "priority-id": "ol", "assigned-to-id": "zxwymlz", "project-id": "xbmqea", "due-date": "2023-09-10T07:09:46.246Z", "plan-x": null, "plan-y": null, "lon": null, "typed-values": { "tf6e915c90543b14f2": null } }, "ticket-type": { "data": { "id": "nmwdzz", "type": "ticket-types" } } } }

Updating a Ticket

With PlanRadar, you can update a ticket in a project using APIs. You will be able to edit all ticket details.

Here’s a step by step on what each API should include to update your ticket details:

To update a ticket, use the API:

PUT /api/v2/{customer_id}/projects/{project_id}/tickets/{uuid}

When updating a ticket using APIs, you should include the customer ID, project ID, and the ticket UUID.

For the rest of the ticket data, include the new data you want your ticket to include, such as:

  • Ticket subject: Include the new ticket subject if it has changed. If not, include the old one.
  • Ticket form: include the updated form. To get the ticket forms added to your project, use the API: GET /api/v2/{customer_id}/projects/{project_id}/ticket_types/ticket_type_project
  • Assignee: If your assignee has changed, include the new ticker assignee. Otherwise, mention the original assignee. To call all users in your account, user the API: GET /api/v2/{customer_id}/projects/{project_id}/ticket_types/ticket_type_project
  • Due date: Add the ticket due date to your request URL.
  • Ticket Status: Add the updated ticket status to your request. Use the following numbers in your request to indicate the ticket status: [1= Open, 2 = In-Progress, 3 = Resolved, 4 = Feedback, 5 = Closed, 6 = Rejected].
  • Ticket Priority: Add the updated ticket priority to your request. Use the following numbers in your request to indicate priority: [1 = Low, 2 = Normal, 3 = High].

A sample request for updating a ticket:

{ "data": { "attributes": { "subject": "Fire distinguisher to be replaced", "ticket-type-id": "nmwdzz", "parent-id": "null", "status-id": 1, "component-id": "kqxbbkg", "priority-id": 1, "assigned-to-id": "bqbmpob", "due-date": "2023-12-10T07:09:46.246Z", "extension-date": "null", "typed-values": { "tf6e915c90543b14f2": null }, "subscribers": [ 0 ], "progress": 0, "plan-x": null, "plan-y": null, "uuid": "98917be4-3261-4493-9b4d-3726e360c796" } } }

In the response, all the data of the updated ticket will be listed.

A sample response:

{ "data": { "id": "jewbpyo", "type": "tickets", "attributes": { "uuid": "98917be4-3261-4493-9b4d-3726e360c796", "author-id": "jeqxjq", "updated-by-id": "jeqxjq", "component-id": "kqxbbkg", "ticket-type-id": "nmwdzz", "customer-id": "jdkkao", "sequential-id": 17, "ext-uri": null, "plan-id": null, "server-updated-at": "2022-11-02T14:44:56.538Z", "plan-z": null, "ifc-entity-uuid": null, "meta-options": {}, "created-at": "2022-10-04T12:25:30.773Z", "updated-at": "2022-11-02T14:44:56.508Z", "subject": "Fire distinguisher to be replaced", "status-id": "lm", "priority-id": "lm", "assigned-to-id": "bqbmpob", "project-id": "xbmqea", "due-date": "2023-12-10T07:09:46.246Z", "plan-x": null, "plan-y": null, "lat": null, "lon": null, "screenshots-url": { "isometric": null, "top": null }, "current-viewpoint": null, "typed-values": { "tf6e915c90543b14f2": null } } } }

Updating Multiple Tickets

With PlanRadar, you can update multiple tickets in a project using APIs. Here’s a step by step on which API can be used to update your tickets:

  • To update multiple tickets with the same data use the 'batch_update' API:

  PUT /api/v2/{{Customer ID}}/projects/{{Project ID}}/tickets/batch_update

To Update multiple tickets you should include in the request:

– the UUIDs for the tickets required to be updated

– the new data you want your tickets to include

  • Sample request for the bulk update action :

– “uuid” : for adding in the “value” array the UUIDs for the tickets to be updated

– “data” : for updating the fields with the new data

{ "component_id": "wjaqpka", "filter": { "uuid": [ { "predicate": "in", "value": [ "cceaeecc-325a-4f29-b8a6-19fe42363139", "7c06f8cd-a151-4249-ac9a-6ea123990857", "2ef43242-d7d1-47aa-9266-e1e7b3e3685d" ] } ] }, "data": { "attributes": { "due-date": "2025-02-07", "progress": "13", "status-id": "ol" }, "bqbabmz": { "tffa0f15a97215b928": "powkppqm" //for typed values }, "append_receiver": false } }

In the response, for a success case, we receive the following response with the number of updated tickets,

{ "count": 3, "method": "job" }

Ticket Attachments

Tickets in PlanRadar accept 4 different types of attachments. These are: 

  • Images 
  • Audio 
  • Video 
  • Documents 

Adding Ticket Attachments

To add an attachment to a certain ticket, use this API:

POST /api/v2/{customer_id}/projects/{project_id}/tickets/{ticket_uuid}/attachments

A sample request body

{ "data": { "attributes": { "uuid": "eb9965e3-8770-44e8-ae03-c0f8fd198c37", "attachment": "base64 string", "attachment-name": "Negative Pressure Fan.png", "caption": "fan needs replacement" } } }

In the API include the customer ID, project ID, and ticket UUID. To get the ticket UUID, use the API: GET /api/v1/{customer_id}/projects/{project_id}/tickets/load.

For the attachment itself, you can either upload a file or add it as a base64 string. Also, add a caption to mention the reason for uploading the attachment.

A sample response body:

{ "data": { "id": "dozwyxly", "type": "ticket-attachment", "attributes": { "attachable-type": "DefectradarIssueImage" } }, "included": [{ "id": "eglkqkze", "type": "defectradar-issue-images", "attributes": { "id": "eglkqkze", "image-file-name": "eb9965e3-8770-44e8-ae03-c0f8fd198c37.jpeg", "image-content-type": "image/jpeg", "uuid": "eb9965e3-8770-44e8-ae03-c0f8fd198c37", "caption": "fan needs replacement", "image-url": "string", "ticket-id": "wmbgblx" } }] }

The response body notifies you that the attachment was added successfully as well as mentions the attachment ID.

You can also update the attachment by using the API:

PUT /api/v2/{customer_id}/projects/{project_id}/tickets/{ticket_uuid}/attachments/{attachment_id}

You can also delete any of the attachments by using the API:

DELETE /api/v2/{customer_id}/projects/{project_id}/tickets/{ticket_uuid}/attachments/{attachment_id}

Calling Ticket Attachments

In the past, PlanRadar had multiple APIs to call these different types of attachments added to the tickets. Nowadays, however, PlanRadar has one API that allows you to call all the attachments in a certain ticket regardless of their type. To do so, you need to use the following API: 

GET api/v2/{customer_id}/projects/{project_id}/tickets/{ticket_uuid}/attachments

PlanRadar allows you to return all ticket attachments by using the attachments request parameter.  

When loading ticket attachments, you must include the {project_id} as well as the {ticket_uuid}. To get the ticket UUID, use the API: GET /api/v1/{customer_id}/projects/{project_id}/tickets/load. 

The ticket UUID can be easily identified in the response body as being made of a hyphenated string of numbers and letters; e.g. {b18cf3s6-9ba0-56be-9f08-3jh931df4aa9}. 

The response body includes data related to the ticket attachments as well as the user. The attributes returned in the response include: 

  • Attachable type: here the title of the ticket will be mentioned 
  • Server updated at: the time at which the server was last updated 
  • Attachable id: this attribute shows a hashed attachable ID to keep your IDs safe 
  • Customer id: a hashed customer ID is shown here 
  • Included: in this attribute, the type of attachment included in the ticket is mentioned as well as the file type, file size, caption, and more. 
  • Attachment URL: the response includes a URL that’s valid for 120 minutes (2 hours) where you can view the attachment. 

At the end of the response, user information is included as well.

A sample response body

{ "data": [{ "id": "wdpayqpq", "type": "ticket-attachment", "attributes": { "attachable-type": "DefectradarIssueImage", "attachable-id": "ymdkqxlo", "customer-id": "nkjlmk", "project-id": "weozyb", "user-id": "xmqenzn", "ticket-id": "lkdpegm" } }], "included": [{ "id": "ymdkqxlo", "type": "defectradar-issue-images", "attributes": { "id": "ymdkqxlo", "image-content-type": "image/jpeg", "uuid": "c093d491-2608-4ff6-b81c-68b8c2328610", "image-url": "https://prd-planradar.s3-eu-central-1.amazonaws.com/923179/defectradar_issue_images/35041334/original/35041334.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJC7EX2365PC3WEYQ%2F20220705%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20220705T071546Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=a6a998e81d6d87e8090f96228e06c5a6f6711f6d7855e69a81dfd4f14a0d91c9", "ticket-id": "lkdpegm" } }, { "id": "xmqenzn", "type": "users", "attributes": { "id": "xmqenzn", "firstname": "xxx", "lastname": "xxx", "company": "PlanRadar Constructions", "mail": "{email_address}", "customer-id": "nkjlmk" } } ] }

Related articles

Comments

0 comments

Please sign in to leave a comment.