OpenAPI Specification
swagger: '2.0'
info:
title: PlanRadar's API Documentation Approval Requests V2 Users V1 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: Users V1
description: Manage all users in your account
paths:
/api/v1/{customer_id}/users:
get:
summary: Returns all users of a customer
tags:
- Users V1
description: "This API returns all users that were created by a specific customer.\n Without any extra parameters it will return the first 100 users ordered by ascending ID. Extra parameters can be added to filter and sort the results.<br />\n <b>Users Sorting:</b>\n Users can be sorted by their attributes like firstname, company etc. .\n The sort is always ascending unless the field name is prefixed with a minus (U+002D HYPHEN-MINUS, \"-\") i.e. `-id` or `id`.\n <br /><b>Example: </b> `/users?sort=-company`<br />\n "
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 users that were created after that timestamp will be returned'
- name: sort
in: query
type: string
- name: pagesize
in: query
type: string
description: sets the number of users that should be returned per page <br/>Maximum is 500, default is 100
- name: page
in: query
type: string
description: sets the number of pages for the returned users
- name: search
in: query
type: string
description: search keyword based on which users are filtered
responses:
'404':
description: Users Not Found
post:
summary: 'Creates user '
tags:
- Users V1
security:
- apiKey: []
description: 'This API is used for creating users. Note: The ''permissions'' object with ''defects: true'' is required for non-subcontractor and non-watcher users.
**Rate Limit:** 10 requests per minute.'
produces:
- application/json
parameters:
- name: customer_id
in: path
type: string
required: true
- name: user
in: body
schema:
type: object
properties:
data:
type: object
properties:
attributes:
type: object
required:
- firstname
- lastname
- mail
- permissions
properties:
firstname:
type: string
example: Max
description: first name of the user (required)
lastname:
type: string
description: last name of the user (required)
mail:
type: string
example: example@gmail.com
description: email address of the user (required)
active:
type: boolean
example: true
description: sets whether or not user is active
city:
type: string
example: Vienna
description: city of the user
company:
type: string
example: PlanRadar
description: company of the user
password:
type: string
example: Kl8957$kgj32
description: password of the user
retype_password:
type: string
example: Kl8957$kgj32
description: password confirmation - has to be the same as password
position:
type: string
example: intern
description: position of the user
street:
type: string
example: Ring Street 5
description: street of the user
tel:
type: string
example: '+43679455652823'
description: telephone number of the user
zipcode:
type: string
example: '1020'
description: zipcode of the user
subcontractor:
type: boolean
example: false
description: sets whether or not the user is of type subcontractor
watcher:
type: boolean
example: true
description: sets whether or not the user is of type watcher
project_ids:
type: array
description: array of the ids of the projects that the user is part of
items:
type: string
example: mdaown
role_ids:
type: array
description: array of the ids of the user's roles in the projects that he is part of - the roles are set for each project in the same order as the projects are sorted in the project_ids array
items:
type: string
group_ids:
type: array
description: array that takes the ids of the groups that the user is part of
items:
type: string
example: lm
is_mobile_syncs:
type: array
description: sets whether or not the data of the projects that the user is part of are synced on mobile devices - each boolean in this array is set for each project in the same order as the projects are sorted in the project_ids array
items:
type: boolean
permissions:
type: object
description: sets the permissions of the user (required for non-subcontractor and non-watcher users)
properties:
accounts:
type: boolean
example: false
api_documentation_access:
type: boolean
example: false
categories:
type: boolean
example: false
defects:
type: boolean
example: true
description: defects are tickets (required - must be set to true)
groups:
type: boolean
example: false
limited_projects:
type: boolean
example: false
projects:
type: boolean
example: false
report_templates:
type: boolean
example: false
roles:
type: boolean
example: false
statistics:
type: boolean
example: false
sub_users:
type: boolean
example: false
user_metrics:
type: boolean
example: false
users:
type: boolean
example: false
typed-values:
type: object
description: sets the values of the typed-fields
responses:
'404':
description: User Not Created
/api/v1/{customer_id}/users/{user_id}:
get:
summary: Returns a specific user of a customer
tags:
- Users V1
description: This API returns a specific user that was created by the logged in customer.
produces:
- application/json
parameters:
- name: customer_id
in: path
type: string
required: true
- name: user_id
in: path
type: string
required: true
responses:
'404':
description: User Not Found
delete:
summary: 'Deletes a specific user of a customer '
tags:
- Users V1
description: This API is used for deleting a specific user that was created by the logged in customer.
produces:
- application/json
security:
- apiKey: []
parameters:
- name: customer_id
in: path
type: string
required: true
- name: user_id
in: path
type: string
required: true
responses:
'404':
description: User Not Found
put:
summary: Updates a specific user of a customer
tags:
- Users V1
description: This API is used for updating a specific user that was created by the logged in customer.
produces:
- application/json
security:
- apiKey: []
parameters:
- name: customer_id
in: path
type: string
required: true
- name: user_id
in: path
type: integer
required: true
- name: user
in: body
schema:
type: object
properties:
data:
type: object
properties:
attributes:
$ref: '#/definitions/User'
responses:
'404':
description: User Not Found
/api/v1/{customer_id}/users/downgrade_user_to_subcontractor:
put:
summary: Downgrades user to subcontractor
tags:
- Users V1
description: This API is used for downgrading the type of a user to subcontractor.
produces:
- application/json
security:
- apiKey: []
parameters:
- name: customer_id
in: path
type: string
required: true
- name: user_id
in: query
type: string
- name: user_type
in: body
schema:
type: object
properties:
data:
type: object
properties:
attributes:
type: object
properties:
user_id:
type: string
description: id of the user that should be downgraded - is required
watcher:
type: boolean
example: false
description: ' the only allowed value in order to downgrade the user is false'
responses:
'404':
description: User Not Found
/api/v1/{customer_id}/users/activate_user:
post:
summary: Activates deactivated user
tags:
- Users V1
description: This API is used for reactivating a specific deactivated user.
produces:
- application/json
security:
- apiKey: []
parameters:
- name: customer_id
in: path
type: string
required: true
- name: user_id
in: query
type: string
responses:
'404':
description: Could Not Reactivate User
/api/v1/{customer_id}/users/export_users_xls:
get:
summary: Exports users as an Excel file
tags:
- Users V1
description: This API is used for exporting all users of the logged in customer as an Excel file.
produces:
- application/json
security:
- apiKey: []
parameters:
- name: customer_id
in: path
type: string
required: true
responses:
'404':
description: Export Failed
definitions:
User:
type: object
properties:
active:
type: boolean
example: true
description: sets whether or not user is active
city:
type: string
example: Vienna
description: city of the user
company:
type: string
example: PlanRadar
description: company of the user
firstname:
type: string
example: Max
description: first name of the user
group_ids:
type: array
description: array that takes the ids of the groups that the user is part of
items:
type: string
example: lm
is_mobile_syncs:
type: array
description: sets whether or not the data of the projects that the user is part of are synced on mobile devices - each boolean in this array is set for each project in the same order as the projects are sorted in the project_ids array
items:
type: boolean
lastname:
type: string
description: last name of the user
mail:
type: string
example: example@gmail.com
description: email address of the user
password:
type: string
example: Kl8957$kgj32
description: password of the user
permissions:
type: object
description: sets the permissions of the user
properties:
accounts:
type: boolean
example: false
api_documentation_access:
type: boolean
example: false
categories:
type: boolean
example: false
defects:
type: boolean
example: true
description: defects are tickets
groups:
type: boolean
example: false
limited_projects:
type: boolean
example: false
projects:
type: boolean
example: false
report_templates:
type: boolean
example: false
roles:
type: boolean
example: false
statistics:
type: boolean
example: false
sub_users:
type: boolean
example: false
user_metrics:
type: boolean
example: false
users:
type: boolean
example: false
position:
type: string
example: intern
description: position of the user
project_ids:
type: array
description: array of the ids of the projects that the user is part of
items:
type: string
example: mdaown
retype_password:
type: string
example: Kl8957$kgj32
description: ' password confirmation - has to be the same as password'
role_ids:
type: array
description: array of the ids of the user's roles in the projects that he is part of - the roles are set for each project in the same order as the projects are sorted in the project_ids array
items:
example: ''
type: string
street:
type: string
example: Ring Street 5
description: ' street of the user'
tel:
type: string
example: '+43679455652823'
description: ' telephone number of the user'
typed-values:
type: object
description: sets the values of the typed-fields
subcontractor:
type: boolean
example: false
description: sets whether or not the user is of type subcontractor
watcher:
type: boolean
example: true
description: sets whether or not the user is of type watcher
zipcode:
type: string
example: '1020'
description: zipcode of the user
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/