swagger: '2.0'
info:
title: PlanRadar's API Documentation Approval Requests V2 Forms API
version: '2.0'
description: "Welcome to PlanRadar's API documentation, here you can find all the details about our APIs as well as test them online.<br />\n <h5>Rate Limits</h5>30 requests per minute per account, aggregated across all tokens.<br />\n If the threshold is exceeded, a 5-minute cooldown is applied to the account, aggregated across all tokens.<br />\n During the cooldown period, further requests may be rejected until the cooldown ends.<br />\n In rare cases, an endpoint may have a different rate limit than the default. When that happens, the differing limit will be explicitly stated in the API documentation for that endpoint.<br />\n <h5>Access Key</h5>In order to be able to access any API you have to create an access token.Therefore you have to follow these steps:-\n <ul>\n <li>Go to your profile page and click on Personal Access Tokens on the left side bar</li><li>Click on the 'Create Access Token' top right button in order to create a new access token.</li><li>Copy the created token and paste it into the field that pops up when you click on the 'Authorize' button </li><li>Note: you can copy the token only once.</li><li>Now you can easily access any API</li>\n </ul>\n <h5>V2 APIs</h5>We are currently working on upgrading all our APIs to v2, and we recommend that you use v2 APIs if it is available.\n <p>V2 APIs are faster, robust and more flexible than v1 APIs</p>"
basePath: /
schemes:
- https
- http
consumes:
- application/json
produces:
- application/json
tags:
- name: Forms
description: Get your PlanRadar forms
paths:
/api/v1/{customer_id}/ticket_types/{ticket_type_id}:
get:
summary: Returns specific ticket type
tags:
- Forms
description: This API returns a specific ticket type based on its id.
produces:
- application/json
parameters:
- name: customer_id
in: path
type: string
required: true
- name: ticket_type_id
in: path
type: string
required: true
responses:
'404':
description: Ticket Type Not found
put:
summary: Updates specific ticket type
tags:
- Forms
description: This API is used for updating a specific ticket type based on its id.
produces:
- application/json
security:
- apiKey: []
parameters:
- name: customer_id
in: path
type: string
required: true
- name: ticket_type_id
in: path
type: string
required: true
- name: ticket
in: body
schema:
type: object
properties:
data:
type: object
properties:
attributes:
$ref: '#/definitions/TicketType'
required:
- title
- content
responses:
'404':
description: Ticket Type Not Found
delete:
summary: Deletes specific ticket type
tags:
- Forms
description: This API is used for deleting a specific ticket type based on its id.
produces:
- application/json
security:
- apiKey: []
parameters:
- name: customer_id
in: path
type: string
required: true
- name: ticket_type_id
in: path
type: string
required: true
responses:
'404':
description: Ticket Type Not Found
/api/v1/{customer_id}/ticket_types:
post:
summary: Creates ticket type
tags:
- Forms
description: "This API is used for creating a ticket type.\n <br />\n <b>Example:</b>\n <br />\n\n {\n \"data\": {\n \"attributes\": {\n \"name\": \"tickettypeone\",\n \"capabilities\": {\n \"has-media\": true,\n \"has-plan-position\": true,\n \"store-geolocation-data\": false,\n \"has-comments\": false,\n \"has-due-date-extension\": true,\n \"has-recurring-reminders\": false,\n \"has-signature\": true,\n \"has-locking\": true,\n \"has_sign_as_someone_else\": true\n },\n \"typed-fields\": {\n \"bda0b598-ddbf-48c8-8da5-60d2c5983e89\": {\n \"name\": \"fieldname\",\n \"type\": \"CustomFields::IntegerType\",\n \"order\": 1,\n \"visible-to\": [\"xmy\",\"yen\",\"lwm\",\"lm\",\"yn\"],\n \"editable-by\": [\"xmy\",\"yen\",\"lwm\",\"lm\"]\n }\n },\n \"static-fields\": {\n \"progress\": {\n \"order\": 1,\n \"visible-to\": [\"xmy\",\"yen\",\"lwm\",\"lm\",\"yn\"],\n \"editable-by\": [\"xmy\",\"yen\",\"lwm\",\"lm\",\"yn\"]\n }\n },\n \"form-decorators\":{\n \"b6cd699b-668f-4360-b6ac-5de4404a094b\":{\n \"name\":\"seperator\",\n \"visible-to\":[\n 762, \"lm\"\n ],\n \"order\":2,\n \"type\":\"FormDecorators::Separator\",\n \"description\": \"\",\n \"check-all-roles\": false,\n \"default_value\": \"\",\n \"required\": false\n },\"b6cd699b-668f-4360-b6ac-5de4404a095b\":{\n \"name\":\"group\",\n \"order\":3,\n \"type\":\"FormDecorators::Group\",\n \"description\": \"\",\n \"visible_to\": [],\n \"check_all_roles\": true,\n \"fields\":[\n \"cc376c7d-054a-4901-98bb-4069d4e4aa74\",\n \"cc376c0d-054a-4901-98bb-4069d4e4aa74\",\n \"parent-id\"\n ]\n }\n }\n }\n }\n }\n\n <br /><br />\n <b>CheckListType Field Example:</b>\n <br />\n The CheckListType field provides a checklist with configurable response options, attachments, and notes.\n <br /><br />\n <b>Configuration Options:</b>\n <ul>\n <li><b>response-label</b>: Display labels for responses. Valid values: 1 (Yes/No/N/A), 2 (True/False/N/A), 3 (Pass/Fail/N/A). Default: 1</li>\n <li><b>response-color</b>: Color scheme for responses. Valid values: 1 (Green/Red/Blue), 2 (Red/Green/Blue), 3 (Blue for all). Default: 1</li>\n <li><b>enable-attachments</b>: Enable attachment support. Default: true</li>\n <li><b>max-attachments</b>: Maximum attachments per item (requires enable-attachments: true). Default: 1</li>\n <li><b>required-attachments-for</b>: Require attachments for specific answers (requires enable-attachments: true AND max-attachments set). Valid values: [1, 2, 3]</li>\n <li><b>enable-notes</b>: Enable notes for checklist items. Default: true</li>\n <li><b>required-notes-for</b>: Require notes for specific answers (requires enable-notes: true). Valid values: [1, 2, 3]</li>\n </ul>\n <br />\n <b>Answer Values:</b>\n <ul>\n <li><b>1</b>: First response option (Yes/True/Pass depending on response-label)</li>\n <li><b>2</b>: Second response option (No/False/Fail depending on response-label)</li>\n <li><b>3</b>: Third response option (N/A for all response-labels)</li>\n </ul>\n <br />\n <b>conditional-config for CheckListType:</b>\n <ul>\n <li><b>answered</b>: Field has any response (no values required)</li>\n <li><b>not_answered</b>: Field has no response (no values required)</li>\n <li><b>includes_any</b>: Response matches any of the specified values (values required: [1, 2, 3])</li>\n <li><b>includes_all</b>: Response matches all specified values (values required: [1, 2, 3])</li>\n </ul>\n <br />\n <b>Full CheckListType Example:</b>\n <br />\n\n {\n \"data\": {\n \"attributes\": {\n \"name\": \"Safety Inspection Form\",\n \"capabilities\": {\n \"has-media\": true,\n \"has-plan-position\": true\n },\n \"typed-fields\": {\n \"checklist-field-uuid\": {\n \"name\": \"Safety Checklist\",\n \"type\": \"CustomFields::CheckListType\",\n \"order\": 1,\n \"visible-to\": [\"lm\", \"yn\"],\n \"editable-by\": [\"lm\"],\n \"response-label\": 1,\n \"response-color\": 1,\n \"enable-attachments\": true,\n \"max-attachments\": 3,\n \"required-attachments-for\": [1, 2],\n \"enable-notes\": true,\n \"required-notes-for\": [2, 3]\n },\n \"conditional-text-field-uuid\": {\n \"name\": \"Additional Notes\",\n \"type\": \"CustomFields::ShortTextType\",\n \"order\": 2,\n \"visible-to\": [\"lm\"],\n \"editable-by\": [\"lm\"],\n \"conditional-config\": {\n \"condition-type\": \"any\",\n \"conditions\": {\n \"checklist-field-uuid\": {\n \"predicate\": \"includes_any\",\n \"values\": [1, 2]\n }\n }\n }\n }\n }\n }\n }\n }\n\n <br /><br />\n <b>Minimal CheckListType (uses defaults):</b>\n <br />\n\n {\n \"typed-fields\": {\n \"checklist-field-uuid\": {\n \"name\": \"Quick Checklist\",\n \"type\": \"CustomFields::CheckListType\",\n \"order\": 1,\n \"visible-to\": [\"lm\"],\n \"editable-by\": [\"lm\"]\n }\n }\n }"
produces:
- application/json
security:
- apiKey: []
parameters:
- name: customer_id
in: path
type: string
required: true
- name: ticket_type
in: body
schema:
type: object
properties:
data:
type: object
properties:
attributes:
$ref: '#/definitions/TicketType'
responses:
'404':
description: Ticket Type Not Created
get:
summary: Returns all ticket types
tags:
- Forms
description: This API returns all ticket types of the logged in customer.
produces:
- application/json
parameters:
- name: customer_id
in: path
type: string
required: true
- name: last_sync_date
in: query
type: string
description: is a Unix Timestamp. If it is set, only ticket types that were created after that timestamp will be returned
- name: page
in: query
type: integer
description: sets the number of pages for the returned ticket types
- name: pagesize
in: query
type: integer
description: sets the number of ticket types that should be returned per page <br/>Maximum is 500, default is 100
- name: apply_form_display_permission
in: query
type: boolean
required: false
description: (KFT-338) when <code>true</code>, filters to forms the caller's role(s) can see via <code>capabilities.visible_to</code>. Watchers bypass. Default <code>false</code>.
- name: apply_form_edit_permission
in: query
type: boolean
required: false
description: (KFT-338) when <code>true</code>, filters to forms the caller's role(s) can edit via <code>capabilities.editable_by</code>. Watchers bypass. Default <code>false</code>.
responses:
'406':
description: Unsupported Accept Header
definitions:
TicketType:
type: object
properties:
name:
type: string
example: tickettypeone
description: sets the name of the ticket type
capabilities:
type: object
properties:
has-media:
type: boolean
example: true
has-plan-position:
type: boolean
example: true
store-geolocation-data:
type: boolean
example: false
has-comments:
type: boolean
example: false
has-due-date-extension:
type: boolean
example: true
has-recurring-reminders:
type: boolean
example: false
has-signature:
type: boolean
example: false
has-locking:
type: boolean
example: false
has-sign-as-someone-else:
type: boolean
example: false
has-form-sequence:
type: boolean
example: false
has-form-sequence-prefix:
type: string
example: RFI
description: sets the prefix of the form sequence - is optional if has-form-sequence is set to true
has-form-sequence-number:
type: number
example: 1
description: sets the number of the form sequence - is required if has-form-sequence is set to true and it must be greater than 1
description: 'sets whether or not media, plan position, comments, due date extensions, reminder repetitions and store geolocations are displayed in the ticket '
typed-fields:
type: object
properties:
field_key:
type: object
properties:
name:
type: string
example: fieldname
description: name of the ticket type
type:
type: string
example: CustomFields::IntegerType
description: 'sets the type of the field - allowed values: CustomFields::FloatType, CustomFields::DateType, CustomFields::IntegerType, CustomFields::LongTextType, CustomFields::ShortTextType, CustomFields::ListType, CustomFields::SubscriptionType, CustomFields::CheckListType'
order:
type: integer
description: sets the order of the field e.g 1 = first typed field
visible-to:
type: array
items:
type: string
description: sets to which roles this field is visible - array that takes the ids of the roles
editable-by:
type: array
items:
type: string
description: sets who has the permission to edit this field - array that takes the ids of the roles
multiple:
type: boolean
example: true
description: sets whether user field can have multiple assignments
response-label:
type: integer
example: 1
description: 'Display labels for responses. Valid values: 1 (Yes/No/N/A), 2 (True/False/N/A), 3 (Pass/Fail/N/A). Only for CheckListType.'
response-color:
type: integer
example: 1
description: 'Color scheme for responses. Valid values: 1 (Green/Red/Blue), 2 (Red/Green/Blue), 3 (Blue for all). Only for CheckListType.'
enable-attachments:
type: boolean
example: true
description: Enable attachment support for checklist items. Only for CheckListType.
enable-notes:
type: boolean
example: true
description: Enable notes for checklist items. Only for CheckListType.
max-attachments:
type: integer
example: 3
description: 'Maximum attachments per checklist item (requires enable-attachments: true). Only for CheckListType.'
required-attachments-for:
type: array
items:
type: integer
description: Require attachments for specific answers (e.g. [1, 2]). Only for CheckListType.
required-notes-for:
type: array
items:
type: integer
description: Require notes for specific answers (e.g. [1, 2]). Only for CheckListType.
description: typed-fields are the customer's custom created fields
static-fields:
type: object
properties:
field_key:
type: object
properties:
order:
type: integer
description: sets the order of the field e.g 1 = first static field
visible-to:
type: array
items:
type: string
description: sets to which roles this field is visible - array that takes the ids of the roles
editable-by:
type: array
items:
type: string
description: sets who has the permission to edit this field - array that takes the ids of the roles
securityDefinitions:
apiKey:
type: apiKey
name: X-PlanRadar-API-Key
in: header
externalDocs:
description: Find out more about our development portal
url: https://www.planradar.com/knowledge-base-overview/