API Okdesk
This documentation describes the existing methods of Okdesk API.
All queries require api_token parameter (authorization key). The authorization key can be generated in the API section of your Okdesk account settings.
Companies ¶
Company search
GET/api/v1/companies/{?api_token,name,phone,id,search_string}
The search is carried out by the exact match of the name or additional name of the company, phone, internal ID or substring
Restriction of access rights ¶
Search of the company will be completed only if the key-linked agent has access to the list of companies in accordance with the access rights settings. This method is not available for contact-associated keys.
Please note ¶
-
When transferring the search_string parameter, the other parameters are not considered
-
The + sign shall be used in the search box only in encrypted format as %2B. Otherwise, it will be interpreted as a whitespace
URI example
GET https://<account>.okdesk.com/api/v1/companies/?api_token=3e9a214215f493c4&name=Okdesk&phone=+7(499)703-47-20&id=1040&search_string=desk
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- name
string(optional) Example: OkdeskName
- phone
string(optional) Example: +7(499)703-47-20Phone number
- id
integer(optional) Example: 1040Internal Company ID
- search_string
string(optional) Example: deskTarget substring
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1040,
"name": "Okdesk",
"additional_name": "Help Desk system for service companies",
"site": "http://okdesk.com",
"email": "info@okdesk.com",
"phone": "+7(499)703-47-20",
"address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
"coordinates": [
53.2184321,
44.9998082
],
"comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions."
"observers":
[
{
"id": 2,
"name": "Fred Bloggs"
},
{
"id": 1,
"name": "John Smith"
}
],
"contacts": [],
"default_assignee":
{
"id": 1,
"name": "John Smith"
},
"category":
{
"id": 3,
"code": "vipclient",
"name": "VIP-client",
"color": "#5cb85c"
},
"parameters": [
{
"code": "attr1",
"name": "Document No.",
"field_type": "ftstring",
"value": "2368590"
},
{
"code": "attr2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-06"
},
{
"code": "attr3",
"name": "Date of the next call",
"field_type": "ftdatetime",
"value": "2019-02-21T14:00:00.000+03:00"
},
{
"code": "attr4",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
},
{
"code": "attr5",
"name": "Type of activity",
"field_type": "ftselect",
"value": "Software"
},
{
"code": "attr6",
"name": "Types of premises",
"field_type": "ftmultiselect",
"value": [
"Head office",
"Recreation area"
]
}
]
}Creating a company
POST/api/v1/companies/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | required | Name |
| additional_name | string | optional | Additional company name |
| site | string | optional | Company website |
| string | optional | Company contact e-mail address | |
| phone | string | optional | Company contact phone |
| address | string | optional | Company address. Warning! When transmitting the text part of the address, automatic substitution of the address coordinates (geocoding) is not provided. To have the address displayed on the map, you must further specify address coordinates in the coordinates parameter. You can convert the text part of the address into coordinates using geocoding services, for example, the Google Geocoding API, etc. |
| coordinates | array of float | optional | Company coordinates |
| comment | string | optional | Additional company info |
| observer_ids | array of integer | optional | User ID array for company viewers |
| default_assignee_id | integer | optional | ID of the responsible agent assigned for this company by default |
| category_code | string | optional | Client category code |
| crm_1c_id | string | optional | Object ID in 1C, required to integrate with 1C; is not displayed in the web interface |
| custom_parameters | associative array | optional | Company extended attributes |
Restriction of access rights ¶
Creation of a company is available to agents in accordance with the settings of access rights. This method is not available for contact-associated keys.
Please note ¶
The coordinates parameter is an array of two real numbers (-90 to 90 latitude and -180 to 180 longitude).
URI example
POST https://<account>.okdesk.com/api/v1/companies/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"company": {
"name": "Okdesk",
"additional_name": "Help Desk system for service companies",
"site": "http://okdesk.com",
"email": "info@okdesk.com",
"phone": "+7(499)703-47-20",
"address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
"coordinates": [
53.2184321,
44.9998082
],
"comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions.",
"observer_ids": [
1,
2
],
"default_assignee_id": 1,
"category_code": "client",
"crm_1c_id": "67067c3a29a8",
"custom_parameters": {
"code1": "123456789",
"code2": "2019-02-15",
"code3": true
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1040,
"name": "Okdesk",
"additional_name": "Help Desk system for service companies",
"site": "http://okdesk.com",
"email": "info@okdesk.com",
"phone": "+7(499)703-47-20",
"address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
"coordinates": [
53.2184321,
44.9998082
],
"comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions.",
"crm_1c_id": "67067c3a29a8",
"observers": [
{
"id": 2,
"name": "Fred Bloggs"
},
{
"id": 1,
"name": "John Smith"
}
],
"contacts": [],
"default_assignee": {
"id": 1,
"name": "John Smith"
},
"category": {
"id": 2,
"code": "client",
"name": "Client",
"color": "#5cb85c"
},
"parameters": [
{
"code": "code1",
"name": "Document No.",
"field_type": "ftstring",
"value": "123456789"
},
{
"code": "code2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-15"
},
{
"code": "code3",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
}
]
}Editing the company
PATCH/api/v1/companies/{company_id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | optional | Name |
| additional_name | string | optional | Additional company name |
| site | string | optional | Company website |
| string | optional | Company contact e-mail address | |
| phone | string | optional | Company contact phone |
| address | string | optional | Company address. Warning! When transmitting the text part of the address, automatic substitution of the address coordinates (geocoding) is not provided. To have the address displayed on the map, you must further specify address coordinates in the coordinates parameter. You can convert the text part of the address into coordinates using geocoding services, for example, the Google Geocoding API, etc. |
| coordinates | array of float | optional | Company coordinates |
| comment | string | optional | Additional company info |
| observer_ids | array of integer | optional | User ID array for company viewers |
| default_assignee_id | integer | optional | ID of the responsible agent assigned for this company by default |
| category_code | string | optional | Client category code |
| crm_1c_id | string | optional | Object ID in 1C, required to integrate with 1C; is not displayed in the web interface |
| custom_parameters | associative array | optional | Company extended attributes |
Restriction of access rights ¶
Editing of the company will be completed only if the key-linked agent has the rights to view the company and edit the company attributes in accordance with the access rights settings. This method is not available for contact-associated keys.
Please note ¶
The coordinates parameter is an array of two real numbers (-90 to 90 latitude and -180 to 180 longitude).
URI example
PATCH https://<account>.okdesk.com/api/v1/companies/4?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- company_id
integer(required) Example: 4Company ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"company": {
"name": "Okdesk",
"additional_name": "Help Desk system for service companies",
"site": "http://okdesk.com",
"email": "info@okdesk.com",
"phone": "+7(499)703-47-20",
"address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
"coordinates": [
53.2184321,
44.9998082
],
"comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions.",
"observer_ids": [
1,
2
],
"default_assignee_id": 1,
"category_code": "vipclient",
"crm_1c_id": "67067c3a29a8",
"custom_parameters": {
"code2": "2019-02-22"
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1040,
"name": "Okdesk",
"additional_name": "Help Desk system for service companies",
"site": "http://okdesk.com",
"email": "info@okdesk.com",
"phone": "+7(499)703-47-20",
"address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
"coordinates": [
53.2184321,
44.9998082
],
"comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions."
"crm_1c_id": "67067c3a29a8",
"observers":
[
{
"id": 2,
"name": "Fred Bloggs"
},
{
"id": 1,
"name": "John Smith"
}
],
"contacts": [],
"default_assignee":
{
"id": 1,
"name": "John Smith"
},
"category":
{
"id": 2,
"code": "vipclient",
"name": "VIP-client",
"color": "#5cb85c"
},
"parameters": [
{
"code": "code1",
"name": "Document No.",
"field_type": "ftstring",
"value": "123456789"
},
{
"code": "code2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-22"
},
{
"code": "code3",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
}
]
}Obtaining list by parameters
GET/api/v1/companies/list{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| category_ids | array of integer | optional | Array of company category IDs (set the value “0” to the parameter to show companies without category). Example: category_ids[]=1 |
| default_assignee_ids | array of integer | optional | Array of company responsible agent IDs (set the value “0” to the parameter to show companies without a responsible agent). Example: default_assignee_ids[]=1 |
| default_assignee_group_ids | array of integer | optional | Array of company responsible group IDs (set the value “0” to the parameter to show companies without a responsible group). Example: default_assignee_group_ids[]=1 |
| observer_ids | array of integer | optional | Array of company viewer IDs (set the value “0” to the parameter to show companies without viewers). Example: observer_ids[]=1 |
| observer_group_ids | array of integer | optional | Array of company viewer group IDs (set the value “0” to the parameter to show companies without viewer groups). Example: observer_group_ids[]=1 |
| created_since | string | optional | The date the company was created in the account’s time zone (From) Example: created_since=2019-05-25 |
| created_until | string | optional | The date the company was created in the account’s time zone (Until) Example: created_until=2019-05-25 |
| page | associative array | optional | Associative array of parameters for a per-page display of the company list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the company starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the company id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the company’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the company’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
Retrieving of the list of companies will be completed only if the key-linked agent has access to the list of companies in accordance with the access rights settings. This method is not available for contact-associated keys.
Please note ¶
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 companies created will be returned.
An example of a query with the company list per-page display parameters: ¶
https://<account>.okdesk.com/api/v1/companies/list?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverseURI example
GET https://<account>.okdesk.com/api/v1/companies/list?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 22,
"name": "Mom and Pop"
},
{
"id": 12,
"name": "Acme Ltd."
},
{
"id": 10,
"name": "Okdesk"
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"created_until": [
"Invalid date"
],
"observer_ids": {
"1": [
"must be an integer"
]
},
"page": {
"size": [
"must be less than or equal to 100"
],
"direction": [
"must be one of: reverse, forward"
],
"from_id": [
"must be an integer"
]
}
}
}Employees ¶
Creating an agent
POST/api/v1/employees/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| last_name | string | optional | Last name |
| first_name | string | required | First name |
| patronymic | string | optional | Middle name |
| position | string | optional | Title |
| string | required | Agent E-mail | |
| login | string | required | Agent login |
| password | string | required | Password |
| phone | string | optional | Phone number |
| telephony_number | string | optional | Extension number |
| comment | string | optional | Additional information on the agent |
| role_ids | associative array | required | Set of agent role IDs |
Restriction of access rights ¶
The method is only available for keys associated with the user role “Administrator”.
Please note ¶
This method creates an inactive agent.
URI example
POST https://<account>.okdesk.com/api/v1/employees/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"employee": {
"first_name": "Joe",
"last_name": "Meatball",
"patronymic": "Smith",
"position": "Manager",
"email": "employee@okdesk.com",
"login": "joe_manager",
"password": "12345678",
"role_ids": [
1
],
"phone": "+79459999999",
"telephony_number": "0321",
"comment": "Senior Manager is responsible for Strategic Planning"
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": "10",
"last_name": "Meatball",
"first_name": "Joe",
"patronymic": "Smith",
"position": "Manager",
"active": false,
"email": "employee@okdesk.com",
"login": "joe_manager",
"phone": "+79459999999",
"telephony_number": "0321",
"comment": "Senior Manager is responsible for Strategic Planning",
"roles": [
{
"id": 1,
"name": "Admin"
}
]
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"employee": {
"last_name": "Meatball",
"email": "employee",
"login": 123,
"password": "12345678",
"role_ids": [
1
],
"phone": "+79459999999"
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"first_name": [
"is missing"
],
"email": [
"has invalid format"
],
"login": [
"must be a string"
]
}
}Editing an agent
PATCH/api/v1/employees/{employee_id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| last_name | string | optional | Last name |
| first_name | string | optional | First name |
| patronymic | string | optional | Middle name |
| position | string | optional | Title |
| string | optional | Agent E-mail | |
| login | string | optional | Agent login |
| password | string | optional | Password |
| phone | string | optional | Phone number |
| telephony_number | string | optional | Extension number |
| comment | string | optional | Additional information on the agent |
| role_ids | associative array | optional | Set of agent role IDs |
Restriction of access rights ¶
The method is only available for keys associated with the user role “Administrator”.
URI example
PATCH https://<account>.okdesk.com/api/v1/employees/10?api_token=3e9a214215f493c4
URI parameters
HideShow
- employee_id
integer(required) Example: 10Agent ID.
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"employee": {
"first_name": "Joe",
"last_name": "Meatball",
"patronymic": "Smith",
"position": "Manager",
"email": "employee@okdesk.com",
"login": "joe_manager",
"password": "12345678",
"role_ids": [
1,
2
],
"phone": "+79459999999",
"telephony_number": "0321",
"comment": "Senior Manager is responsible for Strategic Planning"
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 10,
"last_name": "Meatball",
"first_name": "Joe",
"patronymic": "Smith",
"position": "Manager",
"active": false,
"email": "employee@okdesk.com",
"login": "joe_manager",
"phone": "+79459999999",
"telephony_number": "0321",
"comment": "Senior Manager is responsible for Strategic Planning",
"roles": [
{
"id": 1,
"name": "Admin"
},
{
"id": 2,
"name": "Manager"
}
]
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"employee": {
"email": "employee",
"login": 123
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"email": [
"has invalid format"
],
"login": [
"must be a string"
]
}
}Agent activation
PATCH/api/v1/employees/{id}/activations{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| active | boolean | required | Agent activation status |
Restriction of access rights ¶
The method is only available for keys associated with the user role “Administrator”.
URI example
PATCH https://<account>.okdesk.com/api/v1/employees/10/activations?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 10agent ID.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"active": true
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 10,
"last_name": "Meatball",
"first_name": "Joe",
"patronymic": "Smith",
"position": "Manager",
"active": false,
"email": "employee@okdesk.com",
"login": "joe_manager",
"phone": "+79459999999",
"telephony_number": "0321",
"comment": "Senior Manager is responsible for Strategic Planning",
"roles": [
{
"id": 1,
"name": "Admin"
},
{
"id": 2,
"name": "Manager"
}
]
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"active": 'wrong'
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"active": [
"must be boolean"
]
}
}Receiving agents roles
GET/api/v1/employees/roles{?api_token}
Restriction of access rights ¶
The method is only available for keys associated with the user roles “Administrator”.
URI example
GET https://<account>.okdesk.com/api/v1/employees/roles?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1,
"name": "Administrator"
},
{
"id": 2,
"name": "Lead expert"
},
{
"id": 3,
"name": "Expert"
}
]Receiving agents groups
GET/api/v1/employees/groups{?api_token}
Restriction of access rights ¶
The method is only available for keys associated with the user roles “Administrator”.
URI example
GET https://<account>.okdesk.com/api/v1/employees/groups?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1,
"name": "Technical support",
"active": true,
"description": "",
"employees": [
{
"id": 3020,
"first_name": "John",
"last_name": "Smith",
"patronymic": "",
"login": "john_smith"
},
{
"id": 3030,
"first_name": "Fred",
"last_name": "Bloggs",
"patronymic": "",
"login": "fred_bloggs"
}
]
},
{
"id": 2,
"name": "Managers",
"active": true,
"description": "",
"employees": [
{
"id": 3030,
"first_name": "Fred",
"last_name": "Bloggs",
"patronymic": "",
"login": "fred_bloggs"
}
]
}
]Receiving agent route
GET/api/v1/employees/routes/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| employee_id | integer | required | ID Employee |
| date_from | string | optional | Date of coordinate receipt in the account time zone (From) Example: date_from=2021-05-25 00:00 |
| date_to | string | optional | Date of coordinate receipt in the account time zone (To) Example: date_to=2021-05-25 00:00 |
| page | associative array | optional | Associative array of parameters for per-page display of agent routes (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | ID coordinates from which the selection of records starts. By default (if the direction parameter is not specified) selectionstarts from the value from_id from new coordinates to the older ones Example: page[from_id]=10 |
| direction | string | optional | Direction of selection. Two values are available: reverse, forward. reverse - the selection is carried out starting from the value from_id, from the new coordinates to the older ones. forward - the selection is performed starting from the value from_id, from the old coordinates to the newer ones. If the from_id parameter is absent, the selection is performed from the new coordinates to the older ones. Example: page[direction]=forward |
Restriction of access rights ¶
The method is only available for keys associated with the user roles “Administrator”.
Please note ¶
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 coordinates received will be returned.
An example of a query with the agent coordinates per-page display parameters: ¶
https://<account>.okdesk.ru/api/v1/employees/routes/?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=5&page[direction]=forward&employee_id=1&date_from=2021-01-23 00:00&date_to=2021-01-30 00:00URI example
GET https://<account>.okdesk.com/api/v1/employees/routes/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 5,
"received_at": "2021-01-29T12:27:41.000+03:00",
"latitude": 53.1689031,
"longtitude": 45.0079597
},
{
"id": 6,
"received_at": "2021-01-29T12:30:36.000+03:00",
"latitude": 53.1689036,
"longtitude": 45.0079447
},
{
"id": 7,
"received_at": "2021-01-29T14:06:26.000+03:00",
"latitude": 53.16882,
"longtitude": 45.0079635
}
]Obtaining list by parameters
GET/api/v1/employees/list/{?api_token}
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| role_ids | array of integer | optional | Array of agent roles IDs. Example: role_ids[]=1 |
| active | string | optional | Activity status. Takes true or false value |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the agent starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the agent id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the agent’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the agent’s lowest id. Example: page[direction]=forward |
Restriction of access rights: ¶
The method is only available for keys associated with the user role “Administrator”.
Please note ¶
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 agents created will be returned.
An example of a query with the agent list per-page display parameters: ¶
https://<account>.okdesk.com/api/v1/employees/list?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverseURI example
GET https://<account>.okdesk.com/api/v1/employees/list/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": "10",
"last_name": "Meatball",
"first_name": "Joe",
"patronymic": "Smith",
"position": "Manager",
"active": false,
"email": "employee@okdesk.com",
"login": "joe_manager",
"phone": "+79459999999",
"telephony_number": "0321",
"comment": "Senior Manager is responsible for Strategic Planning",
"roles": [
{
"id": 1,
"name": "Admin"
}
]
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"active": [
"must be one of: true, false"
],
"role_ids": {
0: [
"must be an integer"
],
}
}
}Contacts ¶
Contact search
GET/api/v1/contacts/{?api_token,id,email,phone,search_string}
The search is carried out by the exact match of the contact’s email or additional email address, phone or mobile phone number or substring
Restriction of access rights ¶
The method is only available for keys associated with the user roles “Administrator” or “Leading Expert”. The authentication_code and last_seen parameters is only available to agents with the “Administrator” role.
Please note ¶
-
When transferring the search_string parameter, the other parameters are not considered
-
The + sign shall be used in the search box only in encrypted format as %2B. Otherwise, it will be interpreted as a whitespace
-
The last_seen parameter has a 5-minute accuracy.
URI example
GET https://<account>.okdesk.com/api/v1/contacts/?api_token=3e9a214215f493c4&id=1024&email=employee@okdesk.com&phone=83214567788&search_string=desk
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(optional) Example: 1024Internal contact ID
string(optional) Example: employee@okdesk.comContact e-mail or additional email address
- phone
string(optional) Example: 83214567788Contact phone or mobile phone
- search_string
string(optional) Example: deskTarget substring
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 3020,
"name": "Sally Housecoat",
"position": "Manager",
"email": "employee@okdesk.com",
"phone": "+79459999999",
"mobile_phone": "+79999999999",
"comment": "Senior Manager is responsible for Strategic Planning",
"cc_email": "employee@okdesk.com",
"login": "egorov3020",
"crm_1c_id": "67067c3349a8",
"updated_at": "2019-09-30T15:12:09.095+03:00",
"company_id": 1,
"additional_emails": "contact@okdesk.ru, contact2@okdesk.ru",
"access_level": [
"company_issues"
],
"maintenance_entity_ids": [
12
],
"authentication_code": "6920-6310-7466-4123",
"observers": [
{
"id": 2,
"name": "Fred Bloggs"
},
{
"id": 1,
"name": "John Smith"
}
],
"default_assignee": {
"id": 1,
"name": "John Smith"
},
"parameters": [
{
"code": "attr1",
"name": "Contact number",
"field_type": "ftstring",
"value": "2368590"
}
],
"observable_companies": [
{
"id": 1040,
"name": "Okdesk"
},
{
"id": 1041,
"name": "Acme Ltd."
}
],
"last_seen": "2019-09-30T15:12:09.095+03:00"
}Creating a contact
POST/api/v1/contacts/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| first_name | string | required | Name |
| last_name | string | required | Last name |
| patronymic | string | optional | Middle name |
| position | string | optional | Title |
| login | string | optional | Contact login |
| string | optional | Contact e-mail address | |
| additional_emails | string | optional | Additional emails |
| phone | string | optional | Phone number |
| mobile_phone | string | optional | Mobile phone number |
| comment | string | optional | Additional information on the contact |
| company_id | string | optional | ID of the company to which the contact is referenced (contact without reference to any company is allowed) |
| observer_ids | array of string | optional | Array of ID of users who are contact’s viewers |
| default_assignee_id | string | optional | The ID of agent assigned responsible for this contact by default |
| access_level | array of string | optional | The level of access to the contact’s profile. May include the following values: company_issues (view company’s tickets), maintenance_entities_issues (show tickets referenced to service aims), observable_companies_issues (show monitored company’s tickets), access_to_reports (access to reports), allow_close_company_issues (allow closing all company tickets), allow_close_observable_companies_issues (allow closing monitored companies tickets), allow_close_maintenance_entity_issues (allow closing tickets related to assigned service aims), allow_viewing_issue_services (allow viewing ticket quantities), allow_editing_issue_services (allow editing ticket quantities), allow_viewing_issue_sidebar_time_entries (Allow viewing the breakdown of the time spent on the ticket) |
| cc_email | string | optional | Email for CC |
| maintenance_entity_ids | array of integer | optional | Array of service aim IDs |
| observable_company_ids | array of integer | optional | Array of viewed company IDs |
| crm_1c_id | string | optional | Object ID in 1C, required to integrate with 1C; is not displayed in the web interface |
| custom_parameters | associative array | optional | Contact extended attributes |
Please note ¶
-
Contact will not be created, if the service aim IDs (maintenance_entity_ids) do not correspond to the company’s ID (company_id).
-
The last_seen parameter has a 5-minute accuracy.
Restriction of access rights ¶
The method is not available for the keys of users with the “Expert” role. It is only possible to specify a link with a company and companies being monitored when creating a contact if the key-linked agent has the right to add contact persons to the company in accordance with the access rights settings. Specifying a link to service aims when creating a contact will be possible only if the key-linked agent has the right to add contact persons to the service aim in accordance with the settings of access rights. Only contacts with the reference to the corresponding company can be created for the keys associated with contacts. Transferred values of “Responsible manager” and “Viewers by default” parameters will be ignored for the keys associated with contacts. The authentication_code and last_seen parameters is only available to agents with the “Administrator” role.
URI example
POST https://<account>.okdesk.com/api/v1/contacts/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"contact": {
"first_name": "Joe",
"last_name": "Meatball",
"patronymic": "Smith",
"position": "Manager",
"login": "employee@okdesk.com",
"email": "employee@okdesk.com",
"additional_emails": "contact@okdesk.ru, contact2@okdesk.ru",
"phone": "+79459999999",
"mobile_phone": "+79999999999",
"comment": "Senior Manager is responsible for Strategic Planning",
"company_id": "1",
"observer_ids": [
"1",
"2"
],
"default_assignee_id": "1",
"cc_email": "egorov@okdesk.com",
"crm_1c_id": "67067c3a29a8",
"access_level": [
"access_to_reports"
],
"maintenance_entity_ids": [
15
],
"observable_company_ids": [
1040,
1041
],
"custom_parameters": {
"code2": "2019-02-15"
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 3020,
"name": "Sally Housecoat",
"position": "Manager",
"email": "employee@okdesk.com",
"phone": "+79459999999",
"mobile_phone": "+79999999999",
"comment": "Senior Manager is responsible for Strategic Planning",
"company_id": 1,
"additional_emails": "contact@okdesk.ru, contact2@okdesk.ru",
"cc_email": "egorov@okdesk.com",
"crm_1c_id": "67067c3a29a8",
"updated_at": "2019-09-30T17:30:08.288+03:00",
"observers": [
{
"id": 2,
"name": "Fred Bloggs"
},
{
"id": 1,
"name": "John Smith"
}
],
"access_level": [
"access_to_reports"
],
"maintenance_entity_ids": [
15
],
"default_assignee": {
"id": 1,
"name": "John Smith"
},
"authentication_code": "6920-6310-7466-4123",
"parameters": [
{
"code": "code2",
"name": "Date",
"field_type": "ftdate",
"value": "2019-02-15"
}
],
"observable_companies": [
{
"id": 1040,
"name": "Okdesk"
},
{
"id": 1041,
"name": "Acme Ltd."
}
],
"last_seen": "2019-09-30T15:12:09.095+03:00"
}Editing a contact
PATCH/api/v1/contacts/{contact_id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| first_name | string | optional | Name |
| last_name | string | optional | Last name |
| patronymic | string | optional | Middle name |
| position | string | optional | Title |
| string | optional | Contact e-mail address | |
| additional_emails | string | optional | Additional emails |
| login | string | optional | Contact login |
| phone | string | optional | Phone number |
| mobile_phone | string | optional | Mobile phone number |
| company_id | string | optional | ID of the company to which the contact is referenced (contact without reference to any company is allowed) |
| access_level | array of string | optional | The level of access to the contact’s profile. May include the following values: company_issues (view company’s tickets), maintenance_entities_issues (show tickets referenced to service aims), observable_companies_issues (show monitored company’s tickets), access_to_reports (access to reports), allow_close_company_issues (allow closing all company tickets), allow_close_observable_companies_issues (allow closing monitored companies tickets), allow_close_maintenance_entity_issues (allow closing tickets related to assigned service aims), allow_viewing_issue_services (allow viewing ticket quantities), allow_editing_issue_services (allow editing ticket quantities), allow_viewing_issue_sidebar_time_entries (Allow viewing the breakdown of the time spent on the ticket) |
| cc_email | string | optional | Email for CC |
| maintenance_entity_ids | array of integer | optional | Array of service aim IDs |
| observable_company_ids | array of integer | optional | Array of viewed company IDs |
| crm_1c_id | string | optional | Object ID in 1C, required to integrate with 1C; is not displayed in the web interface |
| custom_parameters | associative array | optional | Contact extended attributes |
Please note ¶
-
The contact will not be modified, if the service aim IDs (maintenance_entity_ids) do not correspond to the transferred company ID (company_id).
-
If the company’s ID (company_id) has not been transferred in the course of contact editing, then the service aim’s correspondence will be checked for the contact’s current company.
-
The last_seen parameter has a 5-minute accuracy.
Restriction of access rights ¶
The method is only available for keys associated with the user roles “Administrator” or “Leading Expert”. The authentication_code and last_seen parameters is only available to agents with the “Administrator” role. It is only possible to specify a link with a company and companies being monitored if the key-linked agent has the right to add contact persons to the company in accordance with the access rights settings. Specifying a link to service aims will be possible only if the key-linked agent has the right for adding contact persons to the service aim in accordance with the settings of access rights.
URI example
PATCH https://<account>.okdesk.com/api/v1/contacts/10?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- contact_id
integer(required) Example: 10Contact ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"contact": {
"first_name": "John",
"last_name": "Doe",
"patronymic": "Smith",
"position": "Manager",
"login": "ivanov",
"email": "ivanov@okdesk.com",
"additional_emails": "contact@okdesk.ru, contact2@okdesk.ru",
"phone": "+79452222222",
"mobile_phone": "+73333333333",
"company_id": "33",
"cc_email": "ivanov@okdesk.com",
"crm_1c_id": "67067c3a29a8",
"access_level": [
"company_issues"
],
"maintenance_entity_ids": [
12
],
"observable_company_ids": [
1040,
1041
],
"custom_parameters": {
"code2": "2019-02-15"
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"sequential_id": 10,
"first_name": "John",
"last_name": "Doe",
"patronymic": "Smith",
"position": "Manager",
"email": "ivanov@okdesk.com",
"login": "ivanov",
"phone": "+79452222222",
"mobile_phone": "+73333333333",
"company_id": 33,
"additional_emails": "contact@okdesk.ru, contact2@okdesk.ru",
"cc_email": "ivanov@okdesk.com",
"crm_1c_id": "67067c3a29a8",
"updated_at": "2019-09-30T15:12:09.095+03:00",
"access_level": [
"company_issues"
],
"authentication_code": "6920-6310-7466-4123",
"parameters": [
{
"code": "code2",
"name": "Date",
"field_type": "ftdate",
"value": "2019-02-15"
}
],
"observable_companies": [
{
"id": 1040,
"name": "Okdesk"
},
{
"id": 1041,
"name": "Acme Ltd."
}
],
"last_seen": "2019-09-30T15:12:09.095+03:00"
}Archiving contacts
PATCH/api/v1/contacts/{id}/activations{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| active | boolean | required | Contact activation status |
Restriction of access rights ¶
The method is only available for keys associated with the user role “Administrator”.
URI example
PATCH https://<account>.okdesk.com/api/v1/contacts/1/activations?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 1contact ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"active": true
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"sequential_id": 10,
"first_name": "John",
"last_name": "Doe",
"patronymic": "Smith",
"position": "Manager",
"email": "ivanov@okdesk.com",
"login": "ivanov",
"phone": "+79452222222",
"mobile_phone": "+73333333333",
"company_id": 33,
"additional_emails": "contact@okdesk.ru, contact2@okdesk.ru",
"cc_email": "ivanov@okdesk.com",
"crm_1c_id": "67067c3a29a8",
"updated_at": "2019-09-30T15:12:09.095+03:00",
"access_level": [
"company_issues"
],
"authentication_code": "6920-6310-7466-4123",
"parameters": [
{
"code": "code2",
"name": "Date",
"field_type": "ftdate",
"value": "2019-02-15"
}
],
"observable_companies": [
{
"id": 1040,
"name": "Okdesk"
},
{
"id": 1041,
"name": "Acme Ltd."
}
],
"last_seen": "2019-09-30T15:12:09.095+03:00"
}Obtaining list by parameters
GET/api/v1/contacts/list{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| company_ids | array of integer | optional | Array of company IDs (set the value “0” to the parameter to show contacts without a company). Example: company_ids[]=1 |
| default_assignee_ids | array of integer | optional | Array of IDs of agents who are responsible for the contacts (set the value “0” to the parameter to show contacts without a responsible agent). Example: default_assignee_ids[]=1 |
| default_assignee_group_ids | array of integer | optional | Array of contact responsible group IDs (set the value “0” to the parameter to show contacts without a responsible group). Example: default_assignee_group_ids[]=1 |
| observer_ids | array of integer | optional | Array of IDs of agents who are viewers for the contacts (set the value “0” to the parameter to show contacts without a viewer). Example: observer_ids[]=1 |
| observer_group_ids | array of integer | optional | Array of contact viewer group IDs (set the value “0” to the parameter to show contacts without viewer groups). Example: observer_group_ids[]=1 |
| active | string | optional | Activity status. Takes true or false value |
| created_since | string | optional | The date the contact was created in the account’s time zone (From) Example: created_since=2019-05-25 |
| created_until | string | optional | The date the contact was created in the account’s time zone (Until) Example: created_until=2019-05-25 |
| updated_since | string | optional | The date the contact was modified in the account’s time zone (From) Example: updated_since=2019-05-25 |
| updated_until | string | optional | The date the contact was modified in the account’s time zone (Until) Example: updated_until=2019-05-25 |
| page | associative array | optional | Associative array of parameters for a per-page display of the contact list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the contact starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the contact id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the contact’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the contact’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
The method is only available for keys associated with the user roles “Administrator” or “Leading Expert”. The authentication_code and last_seen parameters is only available to agents with the “Administrator” role.
Please note ¶
-
This method returns no more than 100 entries.
-
If the parameters of per-page display are not transferred, the list of the last 100 contacts created will be returned.
-
The last_seen parameter has a 5-minute accuracy.
An example of a query with the contact list per-page display parameters: ¶
https://<account>.okdesk.com/api/v1/contacts/list?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverseURI example
GET https://<account>.okdesk.com/api/v1/contacts/list?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 9,
"first_name": "John",
"last_name": "Doe",
"patronymic": "Smith",
"active": true,
"email": "mail@johndoe.com",
"phone": "+79876543210",
"mobile_phone": "+71234567890",
"updated_at": "2019-09-30T15:12:09.095+03:00",
"company_id": 2,
"additional_emails": "contact@okdesk.ru, contact2@okdesk.ru",
"last_seen": "2019-09-30T15:12:09.095+03:00"
},
{
"id": 8,
"first_name": "Frank",
"last_name": "Castle",
"patronymic": "Rook",
"active": true,
"email": "mail@frankcastle.com",
"phone": "+79876543211",
"mobile_phone": "+71234567899",
"updated_at": "2019-09-30T15:12:09.095+03:00",
"company_id": 2,
"additional_emails": "contact@okdesk.ru, contact2@okdesk.ru",
"last_seen": "2019-09-30T15:12:09.095+03:00"
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"created_until": [
"Invalid date"
],
"observer_ids": {
"1": [
"must be an integer"
]
},
"page": {
"size": [
"must be less than or equal to 100"
],
"direction": [
"must be one of: reverse, forward"
],
"from_id": [
"must be an integer"
]
}
}
}Contracts ¶
Contract search
GET/api/v1/agreements/{?api_token,search_string}
The search is carried out by entering the substring that is a part of the contract name, value of crm_1c_id parameter, or a String-type extended attribute of the contract.
Restriction of access rights ¶
The method is only available for keys associated with the user roles “Administrator” or “Leading Expert”.
URI example
GET https://<account>.okdesk.com/api/v1/agreements/?api_token=3e9a214215f493c4&search_string=desk
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- search_string
string(required) Example: deskTarget substring
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1,
"title": "Service contract No.2016-03/1",
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"crm_1c_id": "desktop_1",
"active": false,
"company_ids": [
1
],
"service_periods": [
{
"id": 1,
"agreement_id": 1,
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"comment": "Comment",
"reminder_date": "24-04-2018",
"postpay": false,
"paid": true
}
],
"parameters": [
{
"code": "attr1",
"name": "Document No.",
"field_type": "ftstring",
"value": "2368590"
}
]
}
]Contract info
GET/api/v1/agreements/{id}{?api_token}
Restriction of access rights ¶
The method is only available for keys associated with the user roles “Administrator” or “Leading Expert”.
URI example
GET https://<account>.okdesk.com/api/v1/agreements/1?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 1Contract ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"title": "Service contract No.2016-03/1",
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"crm_1c_id": "67067c3a29a8",
"active": true,
"company_ids": [
1
],
"service_periods": [
{
"id": 1,
"agreement_id": 1,
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"comment": "Comment",
"reminder_date": "24-04-2018",
"postpay": false,
"paid": true
}
],
"parameters": [
{
"code": "attr1",
"name": "Document No.",
"field_type": "ftstring",
"value": "2368590"
}
]
}Editing the contract
PATCH/api/v1/agreements/{id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| title | string | optional | Contract name |
| crm_1c_id | string | optional | Object ID in 1C, required to integrate with 1C; is not displayed in the web interface |
| active | boolean | optional | Contract activation status |
| company_ids | array | optional | Array of company IDs. To remove companies from the contract, you need to transfer the value [] |
| custom_parameters | associative array | optional | Contract extended attributes |
Restriction of access rights ¶
The method is only available for keys associated with the user roles “Administrator” or “Leading Expert”. It is only possible to specify a link with a company if the key-linked agent has the right to add a contract to the company in accordance with the access rights settings.
URI example
PATCH https://<account>.okdesk.com/api/v1/agreements/1?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 1Contract ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"agreement": {
"title": "Service contract No.2016-03/1",
"crm_1c_id": "67067c3a29a8",
"active": false,
"company_ids": [
1,
2
],
"custom_parameters": {
"code2": "2019-02-15"
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"title": "Service contract No.2016-03/1",
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"crm_1c_id": "67067c3a29a8",
"active": false,
"company_ids": [
1,
2
],
"service_periods": [
{
"id": 1,
"agreement_id": 1,
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"comment": "Comment",
"reminder_date": "24-04-2018",
"postpay": false,
"paid": true
}
],
"parameters": [
{
"code": "code2",
"name": "Contract date",
"field_type": "ftdate",
"value": "2019-02-15"
}
]
}Creating a contract
POST/api/v1/companies/{company_id}/agreements{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| title | string | required | Contract name |
| crm_1c_id | string | optional | Object ID in 1C, required to integrate with 1C; is not displayed in the web interface |
| custom_parameters | associative array | optional | Contract extended attributes |
Restriction of access rights ¶
The method is only available for keys associated with the user roles “Administrator” or “Leading Expert” that have no restrictions on adding a contract to the company in accordance with the access rights settings.
URI example
POST https://<account>.okdesk.com/api/v1/companies/1/agreements?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- company_id
integer(required) Example: 1Company ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"agreement": {
"title": "Service contract No.2016-03/1",
"crm_1c_id": "67067c3a29a8",
"custom_parameters": {
"code2": "2019-02-12"
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"title": "Service contract No.2016-03/1",
"start_date": null,
"end_date": null,
"cost": 0,
"crm_1c_id": "67067c3a29a8",
"active": true,
"company_ids": [
1
],
"service_periods": [],
"parameters": [
{
"code": "code2",
"name": "Contract date",
"field_type": "ftdate",
"value": "2019-02-12"
}
]
}Obtaining a list of company contracts
GET/api/v1/companies/{company_id}/agreements{?api_token}
Please note ¶
This method returns list of contracts IDs associated with the assigned company.
Restriction of access rights ¶
The method is only available for keys associated with the user roles “Administrator” or “Leading Expert”.
URI example
GET https://<account>.okdesk.com/api/v1/companies/1/agreements?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- company_id
integer(required) Example: 1Company ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
1,
4,
5,
7
]Adding service term
POST/api/v1/agreements/{agreement_id}/service_periods{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| start_date | string | required | Start date Example: start_date=23-04-2018 |
| end_date | string | required | End date Example: end_date=24-04-2018 |
| cost | float | optional | Cost |
| comment | string | optional | Comment |
| reminder_date | string | optional | End date reminder Example: reminder_date=24-04-2018 |
| postpay | boolean | optional | Postpaid service indicator |
| paid | boolean | optional | Payment indicator |
Restriction of access rights ¶
The method is only available for keys associated with the user roles “Administrator” or “Leading Expert”.
URI example
POST https://<account>.okdesk.com/api/v1/agreements/1/service_periods?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- agreement_id
integer(required) Example: 1Contract ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"service_period": {
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"comment": "Comment",
"reminder_date": "24-04-2018",
"postpay": false,
"paid": true
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"agreement_id": 1,
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"comment": "Comment",
"reminder_date": "24-04-2018",
"postpay": false,
"paid": true
}Changing the service term
PATCH/api/v1/agreements/{agreement_id}/service_periods/{id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| start_date | string | optional | Start date Example: start_date=23-04-2018 |
| end_date | string | optional | End date Example: end_date=24-04-2018 |
| cost | float | optional | Cost |
| comment | string | optional | Comment |
| reminder_date | string | optional | End date reminder Example: reminder_date=24-04-2018 |
| postpay | boolean | optional | Postpaid service indicator |
| paid | boolean | optional | Payment indicator |
Restriction of access rights ¶
The method is only available for keys associated with the user roles “Administrator” or “Leading Expert”.
URI example
PATCH https://<account>.okdesk.com/api/v1/agreements/1/service_periods/1?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- agreement_id
integer(required) Example: 1Contract ID.
- id
integer(required) Example: 1Service term ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"service_period": {
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"comment": "Comment",
"reminder_date": "24-04-2018",
"postpay": false,
"paid": true
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"agreement_id": 1,
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"comment": "Comment",
"reminder_date": "24-04-2018",
"postpay": false,
"paid": true
}Tickets ¶
Ticket creation
POST/api/v1/issues/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| title | string | required | Subject |
| description | string | optional | Description |
| company_id | string | optional | The ID of the company linked to the ticket |
| contact_id | string | optional | The ID of the contact linked to the ticket |
| agreement_id | string | optional | The ID of the contract linked to the ticket |
| assignee_id | string | optional | Responsible agent ID |
| group_id | string | optional | Agent’s responsible group ID |
| observer_ids | array of integer | optional | Array of IDs of agents viewing the ticket |
| observer_group_ids | array of integer | optional | Array of IDs of agent groups viewing the ticket |
| contact_observer_ids | array of integer | optional | Array of IDs of contacts viewing the ticket |
| maintenance_entity_id | string | optional | The ID of the service aim linked to the ticket |
| equipment_ids | array | optional | Array of IDs of equipment linked to the ticket |
| type | string | optional | Ticket type code |
| priority | string | optional | Ticket priority code |
| deadline_at | string | optional | Planned resolution date |
| start_execution_until | string | optional | Scheduled for (date/time) |
| planned_execution_in_minutes | number | optional | Planned execution (in minutes) |
| custom_parameters | associative array | optional | Ticket extended attributes |
| parent_id | string | optional | Parent ticket ID |
| author | associative array | optional | Ticket’s author. To specify the author, you need to pass 2 parameters: id (author’s ID, string, required) and type (author’s type, string, required, valid values: employee and contact). The method is only available for keys associated with the user roles “Administrator”. |
Please note ¶
If type or priority parameters are empty, the ticket will be created with priority and type set “by default” in account settings.
Restriction of access rights ¶
start_execution_until and start_execution_until parameters are available for the keys associated with agents.
For the keys associated with agents, creating a ticket and adding a “Planned resolution date” field are available in accordance with access rights settings. It is only possible to specify a company when creating a ticket if the key-linked agent has the right to create a ticket by company in accordance with the access rights settings. It is allowed to specify equipment while creating a ticket only if a key-related agent is entitled to create tickets on equipment in accordance with the settings of access rights. Specifying a service aim will be possible only if the key-related agent has the right for creation of a ticket for the service aim in accordance with the settings of access rights.
For the keys associated with contacts, the “Responsible agent” (will be determined automatically by the rules in the account), “Viewers“ (will be determined automatically according to the rules set in the account) and “Company” (the company associated with the company will be automatically set up with the contact person) parameters will be ignored when creating a ticket. “Contact”, “Contract”, “Related equipment”, and “Service aim” parameters will be checked for the matching of the transferred values with the company’s contact.
Acceptable parameters of attachable files: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| attachment | string | required | Attachable file |
| is_public | string | optional | File availability |
| description | string | optional | File description |
Please note ¶
The content of the query with attached files shall be multipart/form-data and contain the corresponding title.
URI example
POST https://<account>.okdesk.com/api/v1/issues/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"issue": {
"title": "The laptop doesn't work",
"description": "Laptop failed to boot; please check it out",
"company_id": "33",
"contact_id": "4",
"agreement_id": "12",
"type": "service",
"priority": "high",
"maintenance_entity_id": "15",
"equipment_ids": [
"6",
"8"
],
"deadline_at": "2018-05-09 09:15",
"custom_parameters": {
"address": "42 Prestwick Road",
"checked": true
},
"parent_id": "102",
"author": {
"id": "1",
"type": "contact"
},
"observer_ids": [
2,
5,
7
],
"observer_group_ids": [
4,
10
],
"contact_observer_ids": [
56,
86
]
}
}Request
with attached filesHideShow
Headers
Content-Type: multipart/form-dataBody
curl -H "Content-Type: multipart/form-data" -F "issue[title]=The laptop doesn't work" -F "issue[priority]=high"
-F "issue[observer_ids][]=2" -F "issue[observer_ids][]=5" -F "issue[observer_group_ids][]=1"
-F "issue[attachments][0][attachment]=@/path/to/file.txt" -F "issue[attachments][0][is_public]=true"
-F "issue[attachments][0][description]=Warranty terms"
-F "issue[attachments][1][attachment]=@/path/to/file.docx" -F "issue[attachments][1][is_public]=false"
https://<account>.okdesk.com/api/v1/issues/{?api_token}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 237
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"issue": {
"title": "Broken socket",
"company_id": "-5",
"type": "unknown",
"priority": 'high',
"custom_parameters": {
"total": "4"
},
"parent_id": "102"
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"company_id": "Entry -5 does not exist",
"type": "Entry unknown does not exist",
"custom_parameters_total": "the extended parameter total does not exist"
}
}Change of responsible agent
PATCH/api/v1/issues/{issue_id}/assignees{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| assignee_id | string | optional | Responsible agent ID |
| group_id | string | optional | Responsible group ID |
Please note ¶
One of the parameters (assignee_id, group_id) must be set
Restriction of access rights ¶
The change of responsibility for the ticket will be performed only if the user associated with the key has the right to view the ticket and to change the responsible agent in accordance with the access rights settings. This method is not available for keys associated with contacts.
URI example
PATCH https://<account>.okdesk.com/api/v1/issues/763/assignees?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"assignee_id": "1",
"group_id": "4"
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "Web form ticket",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": "2016-03-16T15:00:55.000+03:00",
"start_execution_until": "2016-03-16T08:05:17.568+03:00",
"planned_execution_in_hours": 11,
"delayed_to": null,
"company_id": 40,
"group_id": 3,
"status": {
"code": "completed",
"name": "Completed"
},
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"priority": {
"code": "low",
"name": "Low"
},
"type": {
"code": "service",
"name": "Service"
},
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
}
}Changing the planned date of ticket resolution
PATCH/api/v1/issues/{issue_id}/deadlines{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| deadline_at | string | required | Planned resolution date |
Restriction of access rights ¶
The planned date of ticket resolution will be changed only if the user associated with the key has the right to view the ticket and to change the planned resolution date for this ticket. This method is not available for keys associated with contacts.
URI example
PATCH https://<account>.okdesk.com/api/v1/issues/763/deadlines?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"deadline_at": "2019-09-24 14:35"
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "Web form ticket",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": "2019-09-24T14:35:00.000+03:00",
"start_execution_until": "2016-03-16T09:05:17.568+03:00",
"planned_execution_in_hours": 12,
"delayed_to": null,
"company_id": 40,
"group_id": 3,
"status": {
"code": "completed",
"name": "Completed"
},
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"priority": {
"code": "low",
"name": "Low"
},
"type": {
"code": "service",
"name": "Service"
},
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
}
}Request
with incorrect dateHideShow
Headers
Content-Type: application/jsonBody
{
"deadline_at": "2019/09/24T14:35"
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"deadline_at": [
"Invalid date"
]
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"deadline_at": [
"Date should be later than today"
]
}
}Editing extended ticket attributes
POST/api/v1/issues/{issue_id}/parameters{?api_token}
Parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| custom_parameters | associative array | required | Ticket extended attributes |
Restriction of access rights ¶
Editing of extended attributes will be available if the user with the key assigned is eligible to view the ticket and to edit the particular attribute and extended attributes in general.
Please note ¶
The value of Image-type extended attribute shall be passed as a string in base64 format considering the following limitations:
-
String size (of an image coded in base64) shall not exceed 1MB
-
Image format: PNG
-
Aspect ratio: 1.86:1
-
String shall start with URL structure
data:image/png;base64,
Example:
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAjAAAAEsCAYAA...jLNtZ4AAAAASUVORK5CYII=
URI example
POST https://<account>.okdesk.com/api/v1/issues/763/parameters?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"custom_parameters": {
"address": "Moscow st 2",
"checked": true,
"datetime": "2018-05-09 09:15",
"multiselect": [
"five"
],
"select": "one",
"date": "2018-05-09"
}
}Response
200Request
with incorrect dateHideShow
Headers
Content-Type: application/jsonBody
{
"custom_parameters": {
"datetime": "Second Tuesday"
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"base": [
[
{
"datetime": "Invalid date/time format"
}
]
]
}
}Request
when attribute is requiredHideShow
Body
{
"custom_parameters": {
"total_sum": ""
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"base": [
"Total sum cannot be blank"
]
}
}Ticket status change
POST/api/v1/issues/{issue_id}/statuses{?api_token}
Please note ¶
-
open, delayed, completed, and closed system statuses are defined for tickets by default.
-
You can expand the set of statuses and possible transitions between them in the Settings/Tickets/Ticket statuses section of your Okdesk account.
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| code | string | required | Status code |
| delay_to | string | optional | The time to which the application is postponed. The field is mandatory for delayed status only. For other statuses, this parameter will be ignored. |
| comment | string | optional | Comment to the status. For example, the reason for transition to a new status. You can set the bindingness of this parameter in the “Settings/Tickets/Ticket Status” section. |
| comment_public | boolean | optional | Comment availability flag. Takes true or false value |
| custom_parameters | associative array | optional | Ticket extended attributes that are available to the user to enter when switching to a new status or leaving the current status. |
| time_entry | array | optional | Array of time spents on the ticket that will be added upon changing the status. |
Please note ¶
-
The delay_to parameter is mandatory to switch to delayed status
-
The comment parameter is mandatory for delayed status by default
-
To change your ticket status in your account settings, the transition from the current status of the ticket to the status transferred in a query must be permitted
-
Parameter formatted_spent_time shall be transmitted in the HhMm format without spaces where H is hours spent; M is minutes spent. Example: 1h2m means 1 hour and 2 minutes.
Restriction of access rights ¶
For agents, the ticket status will be changed only if the agent associated with the key has the right to view the ticket and to change the ticket status from the current to the target in accordance with the settings of access rights. For contact-associated keys, not all transitions between statuses are available. A contact can switch ticket only from “Resolved” status for the status specified in “Ticket renewal status” parameter or for “Closed” status, if the corresponding setting is made in the “Settings/Client Portal” section of your account.
URI example
POST https://<account>.okdesk.com/api/v1/issues/763/statuses?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
with status completedHideShow
Headers
Content-Type: application/jsonBody
{
"code": "completed",
"comment": "Ticket-related works are fully complete",
"comment_public": true,
"custom_parameters": {
"code1": "123456789",
"code2": "2019-02-15",
"code3": true
},
"time_entry": [
{
"formatted_spent_time": "12h45m",
"comment": "Adding time spent when the status is changed",
"custom_parameters": {
"code1": "123456789",
"code2": "2019-02-15",
"code3": true
}
},
{
"formatted_spent_time": "1h45m",
"comment": "Adding time spent when the status is changed",
"custom_parameters": {
"code1": "123456789",
"code2": "2019-02-15",
"code3": true
}
}
]
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "Web form ticket",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": "2016-03-16T15:00:55.000+03:00",
"start_execution_until": "2016-03-16T12:05:17.568+03:00",
"planned_execution_in_hours": 11.5,
"delayed_to": null,
"company_id": 40,
"group_id": 3,
"status": {
"code": "completed",
"name": "Completed"
},
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"priority": {
"code": "low",
"name": "Low"
},
"type": {
"code": "service",
"name": "Service"
},
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"parameters": [
{
"code": "code1",
"name": "First",
"field_type": "ftstring",
"value": "123456789"
},
{
"code": "code2",
"name": "Second",
"field_type": "ftdate",
"value": "2019-02-15"
},
{
"code": "code3",
"name": "Third",
"field_type": "ftcheckbox",
"value": true
},
],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
}
}Request
with status delayedHideShow
Headers
Content-Type: application/jsonBody
{
"code": "delayed",
"delay_to": "2016-05-25 22:15",
"comment": "We have run out of consumables, we are waiting for the replenishment.",
"comment_public": true,
"custom_parameters": {
"code1": "123456789",
"code2": "2019-02-15",
"code3": true
},
"time_entry": [
{
"formatted_spent_time": "12h45m",
"comment": "Adding time spent when the status is changed",
"custom_parameters": {
"code1": "123456789",
"code2": "2019-02-15",
"code3": true
}
}
]
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "Web form ticket",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": null,
"start_execution_until": "2016-03-16T15:05:17.568+03:00",
"planned_execution_in_hours": 12,
"delayed_to": "2016-05-25T22:15:00.000+03:00",
"company_id": 40,
"group_id": 3,
"status": {
"code": "delayed",
"name": "Delayed"
},
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"priority": {
"code": "low",
"name": "Low"
},
"type": {
"code": "service",
"name": "Service"
},
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"parameters": [
{
"code": "code1",
"name": "First",
"field_type": "ftstring",
"value": "123456789"
},
{
"code": "code2",
"name": "Second",
"field_type": "ftdate",
"value": "2019-02-15"
},
{
"code": "code3",
"name": "Third",
"field_type": "ftcheckbox",
"value": true
},
],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
}
}Obtaining a list of comments
GET/api/v1/issues/{issue_id}/comments{?api_token}
Restriction of access rights ¶
-
The list of comments to the ticket will be provided only if the user associated with the key has rights to view the ticket.
-
For keys associated with contacts, a list containing public comments only will be returned.
URI example
GET https://<account>.okdesk.com/api/v1/issues/254/comments?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 254ticket ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1,
"content": "Very soon an engineer will come to you to solve the problem.",
"public": false,
"published_at": "2018-12-24T14:38:43.442+03:00",
"author": {
"id": 15,
"name": "David Sarif",
"type": "employee"
}
},
{
"id": 2,
"content": "Thank you, look forward to it.",
"public": true,
"published_at": "2018-12-24T15:57:43.374+03:00",
"author": {
"id": 12,
"name": "James Jim Miller",
"type": "contact"
}
}
]Obtaining list by parameters
GET/api/v1/issues/count{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| assignee_ids | array of integer | optional | Array of ticket responsible agent IDs (set the value “0” to the parameter to show tickets without a responsible agent). Example: assignee_ids[]=1&assignee_ids[]=2 |
| company_ids | array of integer | optional | Array of ticket-related company IDs (set the value “0” to the parameter to show tickets without a company). Example: company_ids[]=1&company_ids[]=2 |
| contact_ids | array of integer | optional | Array of ticket-related contact IDs (set the value “0” to the parameter to show tickets without a contact). Example: contact_ids[]=1&contact_ids[]=2 |
| author_employee_ids | array of integer | optional | Array of ticket initiator IDs (set the value “0” to the parameter to show tickets without an initiator). Example: author_employee_ids[]=1 Combined with author_contact_ids parameter using OR rule |
| author_contact_ids | array of integer | optional | Array of ticket initiating contact IDs (set the value “0” to the parameter to show tickets without an initiator). Example: author_contact_ids[]=57 Combined with author_employee_ids parameter using OR rule |
| maintenance_entity_ids | array of integer | optional | Array of IDs of service aims that are associated with tickets. Example: maintenance_entity_ids[]=1 |
| equipment_ids | array of integer | optional | An array of equipment ID associated with tickets (to display tickets that have no equipment attached, you must pass the value “0” to the parameter). Example: equipment_ids[]=4 |
| status | array of string | optional | Array of Ticket status codes Example: status[]=opened&status[]=completed |
| status_not | array of string | optional | Array of Codes of ticket statuses that are forbidden for the ticket Example: status_not[]=opened&status_not[]=completed |
| priority | array of string | optional | Array of Ticket priority codes Example: priority[]=high&priority[]=low |
| type | array of string | optional | Array of Ticket type codes Example: type[]=incident |
| created_since | string | optional | Date of ticket creation (From) Example: created_since=22-03-2016 |
| created_until | string | optional | Date of ticket creation (Until) Example: created_until=22-06-2016 |
| overdue | integer | optional | Flag “Tickets with deadline expired”. If the value in the field is 1, then only tikets with the deadline expired will be selected. If the value in the field is 0, then all tickets will be selected. Example: overdue=0 |
| overdue_reaction | integer | optional | Flag “Tickets with response time exceeded”. If the value in the field is 1, then only tikets with the response time exceeded will be selected. If the value in the field is 0, then all tickets will be selected. Example: overdue_reaction=0 |
| completed_since | string | optional | Date of ticket resolution (From) Example: completed_since=22-03-2018 |
| completed_until | string | optional | Date of ticket resolution (Until) Example: completed_until=22-06-2018 |
| updated_since | string | optional | Date of the last ticket update (From) Example: updated_since=03-12-2018 |
| updated_until | string | optional | Date of the last ticket update (Until) Example: updated_until=03-12-2018 |
| reacted_since | string | optional | Actual response time (From) Example: reacted_since=03-12-2018 15:30 |
| reacted_until | string | optional | Actual response time (Until) Example: reacted_until=06-12-2018 18:00 |
| deadline_since | string | optional | Planned resolution date (From) Example: deadline_since=03-12-2018 15:30 |
| deadline_until | string | optional | Planned resolution date (Until) Example: deadline_until=06-12-2018 18:00 |
| start_execution_since | string | optional | Scheduled for (From) Example: start_execution_since=05-07-2021 11:30 |
| start_execution_until | string | optional | Scheduled for (Until) Example: start_execution_until=06-07-2021 00:00 |
| planned_reaction_since | string | optional | Planned reaction time (From) Example: planned_reaction_since=05-07-2021 11:30 |
| planned_reaction_until | string | optional | Planned reaction time (Until) Example: planned_reaction_until=06-07-2021 00:00 |
| custom_parameters | associative array | optional | Associative array of Extended attribute code pairs: Value or set of values |
Please note ¶
- You can find codes of ticket status, priority, and type in the corresponding “Settings” menu section of your account.
Restriction of access rights ¶
This method is available for keys associated with agents in accordance with access rights settings. For keys associated with contacts, only tickets related to the contact’s company (if a contact has “View company’s tickets” access level) and service aims (if a contact person has “Show tickets referenced to service aims” access level) and tickets related directly to the contact will be returned.
Valid values of extended attributes: ¶
| Parameter type | Type | Description |
|---|---|---|
| Date | string | There are two value types available: The code of extended attribute_since sets the left boundary (From); and the code of extended attribute_until sets the right boundary of the range (Until). You can transfer one of these parameters or both of them. Example: custom_parameters[date_code_since]=2018-01-01 custom_parameters[date_code_until]=2018-12-12 |
| Date/time | string | There are two value types available: The code of extended attribute_since sets the left boundary (From); and the code of extended attribute_until sets the right boundary of the range (Until). You can transfer one of these parameters or both of them. Example: custom_parameters[datetime_code_since]=2018-01-01 01:01 custom_parameters[datetime_code_until]=2018-12-12 12:12 |
| Checkbox | string | Two values – true and false – are available. Example: custom_parameters[checkbox_code]=true |
| List item | array of string | An array of list values. Example: custom_parameters[list_code][]=list_value |
| List item set | array of string | An array of list values. Example: custom_parameters[list_code][]=list_value |
URI example
GET https://<account>.okdesk.com/api/v1/issues/count?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
45,
67,
89,
55,
37,
54
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": [
{
"message": 'Incorrect assignee_ids data',
"invalid_data": [
-333,
111
]
},
{
"message": 'Incorrect status_codes data',
"invalid_data": [
"done"
]
},
{
"message": 'Incorrect created_since data',
"invalid_data": "33-29-2016"
}
]
}Ticket info
GET/api/v1/issues/{issue_id}{?api_token}
Restriction of access rights ¶
Ticket info will be provided if only the user associated with the key is entitled to view the ticket. Only limited information will be returned for contact-associated keys:
-
Subject;
-
Description;
-
Type;
-
Priority;
-
Registration date;
-
Resolution date;
-
Planned resolution date;
-
Date of the last update;
-
Delayed until;
-
Status;
-
Previous status (if the application is in the completed code status);
-
Rating;
-
Extended attributes, for which the display settings are set up in the client portal;
-
Responsible agent (if the corresponding value of the attribute “Show the responsible for the ticket in the Client portal” is set in the settings of the Client portal);
-
Group viewers and agent viewers (if the corresponding value of the attribute “Show ticket viewers in the Client portal” is set in the settings of the Client portal);
-
Company;
-
Contact;
-
List of public files of the ticket (without private/public tag);
-
The number of public comments and the date the last public comment was added;
-
Registration method.
Please note ¶
File size (attachment_file_size) measured in bytes.
Please note ¶
The value of Image-type extended attribute shall be returned as PNG image coded in base64.
URI example
GET https://<account>.okdesk.com/api/v1/issues/153?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 153ticket ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 153,
"title": "Service man is required",
"created_at": "2016-09-30T09:28:50.499+03:00",
"completed_at": null,
"deadline_at": "2016-09-30T17:28:50.000+03:00",
"updated_at": "2016-09-30T10:34:22.000+03:00",
"delayed_to": null,
"source": "from_email",
"spent_time_total": 6.5,
"start_execution_until": "2019-09-01T00:00:00.000+03:00",
"planned_execution_in_hours": 12.5,
"planned_reaction_at": "2016-10-22T13:00:00.000+03:00",
"reacted_at": "2016-10-15T15:31:14.383+03:00",
"company_id": 86,
"group_id": 3,
"service_object_id": 3,
"equipment_ids": [
2,
6
],
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"parameters": [
{
"code": "address",
"name": "Call address",
"field_type": "ftstring",
"value": "54 Churchill Street"
}
],
"parent_id": 102,
"child_ids": [
93,
94,
91
],
"status_times": {
"opened": {
"total": "0 d., 4 h., 7 m.",
"on_schedule_total": "0 d., 0 h., 35 m."
}
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"assignee": {
"id": 4,
"name": "Max Mustermann"
},
"author": {
"id": 44,
"name": "Jean Dupont"
},
"agreement": {
"id": 34,
"title": "Service contract",
"company_ids": [
1
]
},
"contact": {
"id": 44,
"name": "Jean Dupont"
},
"priority": {
"code": "low",
"name": "Low"
},
"type": {
"code": "service",
"name": "Service"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"comments": {
"count": 4,
"last_at": "2018-07-04T17:30:12.000+03:00"
}
}Ticket rating
POST/api/v1/issues/{issue_id}/rates{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| rate | string | required | Ticket rating Acceptable values: bad, normal, good |
Restriction of access rights ¶
Ticket will be rated if only the user associated with the key has the right to view the ticket and to rate it in accordance with the access rights settings (the contact’s right to rate is determined in the subsection “Tickets \ Ticket rating” in your account’s “Settings” section; the agent’s right to rate is determined in the subsection “Access roles and rights” of the “Settings” section).
URI example
POST https://<account>.okdesk.com/api/v1/issues/254/rates?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 254ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"issue": {
"rate": "bad"
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"rate": "Ticket No. {issue_id} has been rated as Bad"
}Receiving ticket quantities
GET/api/v1/issues/{issue_id}/services{?api_token}
Restriction of access rights ¶
This method is only available to agents according to access rights settings. Herewith, the fields “Cost” (total), “VAT” (total_vat), and “Discount” (discount) will be available only if the user has the right to view the cost in the ticket’s quantities.
URI example
GET https://<account>.okdesk.com/api/v1/issues/153/services?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 153ticket ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1,
"name": "Delivery to the service center",
"quantity": 1,
"discount": 2,
"total": 600,
"comment": "",
"total_vat": 343.83,
"service": {
"type": "service",
"code": "timerateservice",
"unit": "field trip"
},
"price_list": {
"id": 2,
"name": "Field services"
},
"performer": {
"id": 3,
"name": "Max Mustermann"
}
},
{
"id": 2,
"name": "Pay per time services",
"quantity": 3,
"discount": 2,
"total": 10290,
"comment": "Different billed pay per hour services",
"total_vat": 1569.66,
"service": {
"type": "service",
"code": "timerateservice",
"unit": "man-hour"
},
"price_list": {
"id": 3,
"name": "Billed services"
},
"performer": {
"id": 1,
"name": "Jean Dupont"
}
}
]Adding quantities to a ticket
POST/api/v1/issues/{issue_id}/services{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| code | string | required | Code of the quantities line from the price list |
| quantity | number | required | Quantity (non-negative number) |
| performer_id | integer | optional | Responsible agent ID |
| price_list_id | integer | optional | the price list ID |
| comment | string | optional | Comment |
| total | number | optional | Cost (non-negative number) |
| discount | integer | optional | Discount (integer from 0 to 100) |
Please note ¶
-
Transferred responsible agent (performer_id) must be an active employee.
-
If the total and discount parameters are transferred simultaneously, they must correspond to each other based on the cost in the corresponding price list line.
-
The transferred code* of the quantities line (code) must correspond to the active line of the price list.
Restriction of access rights ¶
-
This method is not available for contact-associated keys.
-
This method is only available for keys associated with agents who have access to actions “View the ticket”, “View ticket quantities” and “Editing the ticket quantities”.
-
If the user does not have the right to view the cost in the ticket quantities, the transferred values of the “total” and “discount” parameters will be ignored.
URI example
POST https://<account>.okdesk.com/api/v1/issues/153/services?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 153ticket ID.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"issue_service": {
"code": "service",
"quantity": 1,
"performer_id": 3,
"comment": "Comment",
"discount": 2,
"total": 600,
"price_list_id": 2
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"name": "Delivery to the service center",
"quantity": 1,
"discount": 2,
"total": 600,
"comment": "Comment",
"total_vat": 343.83,
"service": {
"type": "service",
"code": "timerateservice",
"unit": "field trip"
},
"price_list": {
"id": 2,
"name": "Field services"
},
"performer": {
"id": 3,
"name": "Max Mustermann"
}
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"issue_service": {
"code": "wrong_code",
"performer_id": 103,
"comment": "Comment",
"discount": 2.1,
"total": -600,
"price_list_id": 2000
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"code": [
"Price list row does not exist or is not active"
],
"quantity": [
"is missing"
],
"performer_id": [
"The agent does not exist or is not activated"
],
"discount": [
"must be an integer"
],
"total": [
"must be greater than or equal to 0"
],
"price_list": [
"The price list does not exist or is not active"
]
}
}Obtaining time spent on a ticket
GET/api/v1/issues/{issue_id}/time_entries{?api_token}
Restriction of access rights ¶
Information on the time spent on the ticket will be provided only if the user associated with the key has the right to view the ticket and to view the time spent in accordance with the access rights settings. This method is not available for contact-associated keys.
URI example
GET https://<account>.okdesk.com/api/v1/issues/166/time_entries?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 166ticket ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"spent_time_total": 4,
"time_entries": [
{
"id": 1,
"comment": "Packaging",
"spent_time": 1,
"logged_at": "2018-10-16T11:14:00.000+03:00",
"employee": {
"id": 1,
"login": "andrey@okdesk.com",
"name": "Jean Dupont"
},
"parameters": [
{
"code": "address",
"name": "Call address",
"field_type": "ftstring",
"value": "54 Churchill Street"
}
]
},
{
"id": 2,
"comment": "Shipping",
"spent_time": 2,
"logged_at": "2018-10-16T13:10:00.000+03:00",
"employee": {
"id": 2,
"login": "petrov@okdesk.com",
"name": "Max Mustermann"
},
"parameters": [
{
"code": "address",
"name": "Call address",
"field_type": "ftstring",
"value": "54 Churchill Street"
}
]
},
{
"id": 3,
"comment": "Installation",
"spent_time": 1,
"logged_at": "2018-10-16T14:10:00.000+03:00",
"employee": null,
"parameters": [
{
"code": "address",
"name": "Call address",
"field_type": "ftstring",
"value": "54 Churchill Street"
}
]
}
]
}Obtaining a file of a ticket
GET/api/v1/issues/{issue_id}/attachments/{attachment_id}{?api_token}
Restriction of access rights ¶
The file information will be provided only if the user associated with the key has rights to view the ticket. For keys associated with contacts, a list containing public files only will be returned.
Please note ¶
File size (attachment_file_size) measured in bytes. Attachment URL is temporary. It expires after 30 seconds of its creation.
URI example
GET https://<account>.okdesk.com/api/v1/issues/166/attachments/22?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 166ticket ID.
- attachment_id
integer(required) Example: 22File ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 22,
"attachment_file_name": "image.jpg",
"description": "",
"attachment_file_size": 7955,
"is_public": true,
"created_at": "2019-10-29T17:31:30.675+03:00",
"attachment_url": "https://static.okdesk.com/attachments/attachments/000/000/150/original/hqdefault.jpg"
}Obtaining a checklist of ticket
GET/api/v1/issues/{issue_id}/check_lists/items{?api_token}
Restriction of access rights ¶
-
For contact-associated keys, only available for contacts checklist items will be returned.
-
This method is only available for keys associated with agents who have access to actions “View the ticket”, “View the checklist in the ticket”.
URI example
GET https://<account>.okdesk.com/api/v1/issues/166/check_lists/items?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 166ticket ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1001,
"name": "Check equipment",
"required": false,
"visible_for_clients": true,
"checked_at": "2021-01-27T20:45:00.703+03:00",
"parameters": [
{
"param_type": "text",
"required": true,
"value": "No leaks found"
},
{
"param_type": "files",
"required": false,
"value": [
{
"id": 521,
"attachment_file_name": "check_photo.jpeg",
"attachment_file_size": 3243,
"created_at": "2021-04-23T17:20:27.937+03:00"
}
]
}
],
"position": 1,
"checked_by_user_id": 2,
"checked": true
},
{
"id": 1002,
"name": "Sign a contract",
"required": true,
"visible_for_clients": false,
"checked_at": null,
"parameters": [],
"position": 2,
"checked_by_user_id": null,
"checked": false
},
]Applying checklist item
PATCH/api/v1/issues/{issue_id}/check_lists/items/{item_id}/check{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| checked | boolean | required | Applying status of checklist item |
| item_parameters | associative array | optional | Parameters of checklist item |
Restriction of access rights ¶
-
This method is not available for contact-associated keys.
-
This method is only available for keys associated with agents who have access to actions “View the ticket”, “Apply the checklist in the ticket”.
Acceptable parameters of attachable files: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| attachment | string | required | Attachable file |
Please note ¶
-
The content of the query with attached files shall be multipart/form-data and contain the corresponding title.
-
If there are already attached files in the changed checklist item, then when new files are attached, the old ones will be overwritten.
URI example
PATCH https://<account>.okdesk.com/api/v1/issues/166/check_lists/items/1002/check?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 166ticket ID.
- item_id
integer(required) Example: 1002checklist item ID.
Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"check_list_item": {
"checked": true,
"item_parameters": {
"text": "No leaks found"
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1001,
"name": "Check equipment",
"required": false,
"visible_for_clients": true,
"checked_at": "2021-01-27T20:45:00.703+03:00",
"parameters": [
{
"param_type": "text",
"required": true,
"value": "No leaks found"
}
],
"position": 1,
"checked_by_user_id": 2,
"checked": true
},
{
"id": 1002,
"name": "Sign a contract",
"required": true,
"visible_for_clients": false,
"checked_at": null,
"parameters": [],
"position": 2,
"checked_by_user_id": null,
"checked": false
},
]Request
with attached filesHideShow
Headers
Content-Type: multipart/form-dataBody
curl -X PUT -H "Content-Type: multipart/form-data" -F "check_list_item[checked]=true"
-F "check_list_item[item_parameters][text]=No leaks found"
-F "check_list_item[item_parameters][files][0][attachment]=@/path/to/check_photo.jpg"
https://<account>.okdesk.ru/api/v1/issues/12/check_lists/items/1001/check{?api_token}Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1001,
"name": "Check equipment",
"required": false,
"visible_for_clients": true,
"checked_at": "2021-01-27T20:45:00.703+03:00",
"parameters": [
{
"param_type": "text",
"required": true,
"value": "No leaks found"
},
{
"param_type": "files",
"required": false,
"value": [
{
"id": 521,
"attachment_file_name": "check_photo.jpeg",
"attachment_file_size": 3243,
"created_at": "2021-04-23T17:20:27.937+03:00"
}
]
}
],
"position": 1,
"checked_by_user_id": 2,
"checked": true
},
{
"id": 1002,
"name": "Sign a contract",
"required": true,
"visible_for_clients": false,
"checked_at": null,
"parameters": [],
"position": 2,
"checked_by_user_id": null,
"checked": false
},
]Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"check_list_item": {
"checked": 1234
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"checked": [
"must be boolean"
]
}
}Equipment ¶
Equipment search
GET/api/v1/equipments/{?api_token,serial_number,inventory_number,search_string}
The search is carried out by the exact match of the serial number or inventory number or by substring
Restriction of access rights ¶
Equipment search will be performed only if a key-related agent has access to the list of equipment in accordance with the settings of access rights. This method is not available for contact-associated keys.
Please note ¶
When transferring the search_string parameter, the other parameters are not considered
URI example
GET https://<account>.okdesk.com/api/v1/equipments/?api_token=3e9a214215f493c4&serial_number=51BKB835225&inventory_number=1101040003532&search_string=desk
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- inventory_number
string(optional) Example: 1101040003532Equipment inventory number
- serial_number
string(optional) Example: 51BKB835225Equipment serial number
- search_string
string(optional) Example: deskTarget substring
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 3,
"serial_number": "1101040003532",
"inventory_number": "51BKB835225",
"maintenance_entity_id": 15,
"equipment_kind": {
"id": 24,
"code": "laptop",
"name": "Laptop",
"description": ""
},
"equipment_manufacturer": null,
"equipment_model": null,
"company": {
"id": 45,
"name": "Newco"
"additional_name": null,
"site": "intellectplus.com",
"email": "intel+@okdesk.com",
"phone": "+8412 381312",
"address": "60 Wall Street, New York City",
"comment": ""
},
"parameters": [
{
"code": "end_of_service_period",
"name": "Service term completion date",
"field_type": "ftdate",
"value": "2018-03-16"
},
{
"code": "color",
"name": "Color",
"field_type": "ftstring",
"value": "black"
}
]
}Creation of equipment
POST/api/v1/equipments/{?api_token,serial_number,inventory_number,search_string}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| equipment_type_code | string | required | Equipment type code |
| equipment_manufacturer_code | string | optional | Equipment manufacturer code |
| equipment_model_code | string | optional | Equipment model code |
| serial_number | string | optional | Serial number |
| inventory_number | string | optional | Inventory number |
| comment | string | optional | Comment |
| company_id | string | optional | The ID of the company linked to the equipment |
| maintenance_entity_id | string | optional | The ID of the service aim, to which the equipment is linked |
| custom_parameters | associative array | optional | Equipment extended attributes |
Please note ¶
-
If the equipment_type_code or equipment_manufacturer_code does not correspond to the type and manufacturer codes of the equipment model (equipment_model_code), the equipment will not be created.
-
If the service aim ID (maintenance_entity_id) does not correspond to the company’s ID (company_id), the equipment will not be created.
Restriction of access rights ¶
Creation of equipment is available to agents in accordance with the settings of access rights. It is only possible to specify a link with a company if the key-linked agent has the right to add equipment to the company in accordance with the access rights settings. Specifying a service aim will be possible only if the key-linked agent has the right to add equipment to the service aim in accordance with the settings of access rights. This method is not available for contact-associated keys.
URI example
POST https://<account>.okdesk.com/api/v1/equipments/?api_token=3e9a214215f493c4&serial_number=51BKB835225&inventory_number=1101040003532&search_string=desk
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- inventory_number
string(optional) Example: 1101040003532Equipment inventory number
- serial_number
string(optional) Example: 51BKB835225Equipment serial number
- search_string
string(optional) Example: deskTarget substring
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"equipment": {
"equipment_type_code": "laptop",
"equipment_manufacturer_code": "Asus",
"equipment_model_code": "K53sm",
"serial_number": "51BKB835225",
"inventory_number": "11010400003532",
"comment": "The K53SM laptop uses NVIDIA® GeForce® 630M discrete graphics engine with 2 gigabyte video RAM. This will be enough for modern computer games and multimedia applications.",
"company_id": "4",
"maintenance_entity_id": "15",
"custom_parameters": {
"end_of_service_period": "16/03/2018",
"color": "black"
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 3,
"serial_number": "1101040003532",
"inventory_number": "51BKB835225",
"equipment_kind": {
"id": 24,
"code": "laptop",
"name": "Laptop",
"description": null
},
"equipment_manufacturer": {
"id": 1,
"code": "asus",
"name": "Asus",
"description": null
},
"equipment_model": {
"id": 1,
"code": "k53sm",
"name": "K53sm",
"description": null
}
"company": {
"id": 4,
"name": "Newco"
"additional_name": null,
"site": "intellectplus.com",
"email": "intel+@okdesk.com",
"phone": "+8412 381312",
"address": "60 Wall Street, New York City",
"comment": ""
},
"comment": "The K53SM laptop uses NVIDIA® GeForce® 630M discrete graphics engine with 2 gigabyte video RAM. This will be enough for modern computer games and multimedia applications.",
"maintenance_entity_id": 15,
"parameters": [
{
"code": "end_of_service_period",
"name": "Service term completion date",
"field_type": "ftdate",
"value": "2018-03-16"
},
{
"code": "color",
"name": "Color",
"field_type": "ftstring",
"value": "black"
}
]
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"equipment": {
"equipment_type_code": "laptop",
"equipment_manufacturer_code": "Siemens",
"equipment_model_code": "x989",
"serial_number": "51BKB835225",
"inventory_number": "11010400003532",
"company_id": "456",
"maintenance_entity_id": "77"
"custom_parameters":{
"package": "premium"
}
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"equipment_manufacturer": [
"Entry Siemens does not exist"
],
"company": [
"Entry 456 does not exist"
],
"equipment_model_rule": [
"Equipment type code or equipment manufacturer code do not match the equipment model"
],
"maintenance_entity_exists_in_company_scope": [
"Service aim %{maintenance_entity_id} for the assigned company does not exist 22"
],
"custom_parameters": [
{
"package": "values missing from the values list: premium"
}
]
}
}Editing of equipment
PATCH/api/v1/equipments/{id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| equipment_type_code | string | optional | Equipment type code |
| equipment_manufacturer_code | string | optional | Equipment manufacturer code |
| equipment_model_code | string | optional | Equipment model code |
| serial_number | string | optional | Serial number |
| inventory_number | string | optional | Inventory number |
| comment | string | optional | Comment |
| company_id | string | optional | The ID of the company linked to the equipment |
| maintenance_entity_id | string | optional | The ID of the service aim, to which the equipment is linked |
| custom_parameters | associative array | optional | Equipment extended attributes |
Please note ¶
-
If the equipment_type_code or equipment_manufacturer_code does not correspond to the type and manufacturer codes of the equipment model (equipment_model_code), the equipment will not be created.
-
If the service aim ID (maintenance_entity_id) does not correspond to the company’s ID (company_id), the equipment will not be created.
Restriction of access rights ¶
Editing of equipment will be performed only if a key-related agent has rights to review the equipment and edit equipment attributes in accordance with the settings of access rights. It is only possible to specify a link with a company if the key-linked agent has the right to add equipment to the company in accordance with the access rights settings. Specifying a service aim will be possible only if the key-linked agent has the right to add equipment to the service aim in accordance with the settings of access rights. This method is not available for contact-associated keys.
URI example
PATCH https://<account>.okdesk.com/api/v1/equipments/13?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 13Equipment ID.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"equipment": {
"equipment_model_code": "x50sm",
"company_id": "4",
"maintenance_entity_id": "15",
"custom_parameters": {
"end_of_service_period": "16/03/2019"
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 3,
"serial_number": "1101040003532",
"inventory_number": "51BKB835225",
"equipment_kind": {
"id": 24,
"code": "laptop",
"name": "Laptop",
"description": null
},
"equipment_manufacturer": {
"id": 1,
"code": "asus",
"name": "Asus",
"description": null
},
"equipment_model": {
"id": 4,
"code": "x50sm",
"name": "x50sm",
"description": null
}
"company": {
"id": 4,
"name": "Newco"
"additional_name": null,
"site": "intellectplus.com",
"email": "intel+@okdesk.com",
"phone": "+8412 381312",
"address": "60 Wall Street, New York City",
"comment": ""
},
"comment": "The K53SM laptop uses NVIDIA® GeForce® 630M discrete graphics engine with 2 gigabyte video RAM. This will be enough for modern computer games and multimedia applications.",
"maintenance_entity_id": 15,
"parameters": [
{
"code": "end_of_service_period",
"name": "Service term completion date",
"field_type": "ftdate",
"value": "2018-03-16"
},
{
"code": "color",
"name": "Color",
"field_type": "ftstring",
"value": "black"
}
]
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"equipment": {
"equipment_model_code": "x989",
"serial_number": "51BKB835225",
"inventory_number": "11010400003532",
"company_id": "456",
"maintenance_entity_id": "77",
"custom_parameters": {
"package": "premium"
}
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"company": [
"Entry 456 does not exist"
],
"equipment_model_rule": [
"Equipment type code or equipment manufacturer code do not match the equipment model"
],
"maintenance_entity_exists_in_company_scope": [
"Service aim %{maintenance_entity_id} for the assigned company does not exist 22"
],
"custom_parameters": [
{
"package": "values missing from the values list: premium"
}
]
}
}Equipment info
GET/api/v1/equipments/{id}{?api_token}
Restriction of access rights ¶
Information on equipment will be provided only if a key-related agent has rights to review the equipment in accordance with the settings of access rights. This method is not available for contact-associated keys.
URI example
GET https://<account>.okdesk.com/api/v1/equipments/13?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 13Equipment ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 7,
"serial_number": "51BKB835225",
"inventory_number": "909786543",
"comment": "Laptop Asus K53sm",
"company": "Newco",
"maintenance_entity_id": 15,
"parameters": [
{
"code": "attr1",
"name": "Extended warranty",
"field_type": "ftstring",
"value": "36 months"
},
{
"code": "attr2",
"name": "Sale date",
"field_type": "ftdate",
"value": "2018-07-06"
},
{
"code": "attr3",
"name": "Accepted for repairs",
"field_type": "ftdatetime",
"value": "2018-09-21T14:11:00.000+03:00"
},
{
"code": "attr4",
"name": "Warranty claim",
"field_type": "ftcheckbox",
"value": true
},
{
"code": "attr5",
"name": "Operating system",
"field_type": "ftselect",
"value": "Windows 10"
},
{
"code": "attr6",
"name": "Diagnostics",
"field_type": "ftmultiselect",
"value": [
"Disk",
"Motherboard"
]
}
],
"equipment_kind": {
"id": 24,
"code": "laptop",
"name": "Laptop",
"description": ""
},
"equipment_manufacturer": {
"id": 1,
"code": "asus",
"name": "Asus",
"description": ""
},
"equipment_model": {
"id": 4,
"code": "x50sm",
"name": "x50sm",
"description": ""
}
}Obtaining list by parameters
GET/api/v1/equipments/list/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| company_ids | array of integer | optional | Array of company IDs (set the value “0” to the parameter to show equipment without a company). Example: company_ids[]=1 |
| maintenance_entity_ids | array of integer | optional | Array of maintenance entity IDs (set the value “0” to the parameter to show equipment without a maintenance entity). Example: maintenance_entity_ids[]=1 |
| created_since | string | optional | The date equipment was created in the account’s time zone (From) Example: created_since=2019-05-25 |
| created_until | string | optional | The date equipment was created in the account’s time zone (Until) Example: created_until=2019-05-25 |
| equipment_kind_codes | array of string | optional | Array of equipment kind codes. Example: equipment_kind_codes[]=EG |
| equipment_manufacterer_codes | array of string | optional | Array of equipment manufacterer codes. Example: equipment_manufacturer_codes[]=EG |
| equipment_model_codes | array of string | optional | Array of equipment model codes. Example: equipment_model_codes[]=EG |
| custom_parameters | associative array | optional | Associative array of Extended attribute code pairs: Value or set of values |
| page | associative array | optional | Associative array of parameters for a per-page display of the equipment list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the equipment starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the equipment id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
-
This method is not available for contact-associated keys.
-
This method is only available for keys associated with agents who have access to actions “Add to equipment list”, “View enlisted equipment”
Please note ¶
-
This method returns no more than 100 entries.
-
If the parameters of per-page display are not transferred, the list of the last 100 equipment created will be returned.
Valid values of extended attributes: ¶
| Parameter type | Type | Description |
|---|---|---|
| Date | string | There are two value types available: The code of extended attribute_since sets the left boundary (From); and the code of extended attribute_until sets the right boundary of the range (Until). You can transfer one of these parameters or both of them. Example: custom_parameters[date_code_since]=2018-01-01 custom_parameters[date_code_until]=2018-12-12 |
| Date/time | string | There are two value types available: The code of extended attribute_since sets the left boundary (From); and the code of extended attribute_until sets the right boundary of the range (Until). You can transfer one of these parameters or both of them. Example: custom_parameters[datetime_code_since]=2018-01-01 01:01 custom_parameters[datetime_code_until]=2018-12-12 12:12 |
| Checkbox | string | Two values – true and false – are available. Example: custom_parameters[checkbox_code]=true |
| List ite | array of string | An array of list values. Example: custom_parameters[list_code][]=list_value |
| List item set | array of string | An array of list values. Example: custom_parameters[list_code][]=list_value |
An example of a query with the equipment list per-page display parameters ¶
https://<account>.okdesk.com/api/v1/equipments/list?api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=forward
URI example
GET https://<account>.okdesk.com/api/v1/equipments/list/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 32,
"serial_number": "123",
"inventory_number": "321",
"parameters": [
{
"code": "checkbox_sample",
"name": "checkbox_sample",
"field_type": "ftcheckbox",
"value": true
}
],
"company": {
"id": 113,
"name": "SomeCompany"
},
"maintenance_entity": null,
"equipment_kind": {
"id": 5,
"code": "some_lind",
"name": "some_kind",
"description": ""
},
"equipment_manufacturer": null,
"equipment_model": null
}
]Service aims ¶
Service aim search
GET/api/v1/maintenance_entities/{?api_token,name,search_string}
The search is carried out by the exact match of the service aim name or by substring
Please note ¶
If the names of multiple service aims match, all values fit the search criteria will be returned When transferring the search_string parameter, the other parameters are not considered
Restriction of access rights ¶
The service aim search will be performed only if the key-linked agent has access to a service aim list in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
URI example
GET https://<account>.okdesk.com/api/v1/maintenance_entities/?api_token=3e9a214215f493c4&name=Sales outlet No.13&search_string=desk
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- name
string(required) Example: Sales outlet No.13Name
- search_string
string(required) Example: deskTarget substring
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1,
"name": "Sales outlet No.13",
"address": null,
"comment": null,
"default_assignee_id": 12,
"default_assignee_group_id": 1,
"company_id": 1040,
"timezone": {
"code": "Moscow",
"name": "Moscow",
"gmt": "+03:00"
},
"contacts_ids": [
23,
24,
63,
64,
65
],
"equipments_ids": [
8,
9
],
"coordinates": [
53.2184321,
44.9998082
],
"parameters": [
{
"code": "attr1",
"name": "Document No.",
"field_type": "ftstring",
"value": "2368590"
},
{
"code": "attr2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-06"
},
{
"code": "attr3",
"name": "Date of the next call",
"field_type": "ftdatetime",
"value": "2019-02-21T14:00:00.000+03:00"
},
{
"code": "attr4",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
},
{
"code": "attr5",
"name": "Type of activity",
"field_type": "ftselect",
"value": "Software"
},
{
"code": "attr6",
"name": "Types of premises",
"field_type": "ftmultiselect",
"value": [
"Head office",
"Recreation area"
]
}
],
"schedule": {
"id": 1,
"name": "On weekdays, 9 a.m. to 6 p.m."
},
"observers": [
{
"id": 5,
"name": "Andrei Russo"
},
{
"id": 12,
"name": "Alix Mckay"
}
],
"observer_groups": [
{
"id": 23,
"name": "Mechanics"
},
{
"id": 3,
"name": "Drivers"
}
],
"attachments": [
{
"attachment_file_name": "file.jpg",
"description": "Description",
"is_public": true,
"id": 575
}
],
"agreements": [
{
"id": 2,
"title": "Important Contract"
}
]
}
]Creating a service aim
POST/api/v1/maintenance_entities/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | required | Name |
| company_id | integer | required | Company ID |
| agreement_ids | array of int | optional | Contracts IDs |
| address | string | optional | Address. Warning! When transmitting the text part of the address, automatic substitution of the address coordinates (geocoding) is not provided. To have the address displayed on the map, you must further specify address coordinates in the coordinates parameter. You can convert the text part of the address into coordinates using geocoding services, for example, the Google Geocoding API, etc. |
| coordinates | array of float | optional | Service aim coordinates |
| timezone | string | optional | Service aim time zone |
| comment | string | optional | Service aim additional info |
| default_assignee_id | integer | optional | ID of responsible agent by default |
| default_assignee_group_id | integer | optional | ID of responsible group by default |
| schedule_id | integer | optional | Service aim schedule ID |
| observer_ids | array of int | optional | Array of IDs of users viewing the service aim |
| observer_group_ids | array of int | optional | Array of IDs of agent groups viewing the service aim |
| custom_parameters | associative array | optional | Extended attributes of service aim |
Please note ¶
The coordinates parameter is an array of two real numbers (-90 to 90 latitude and -180 to 180 longitude). The agreement_ids parameter must contain IDs of contracts of a company with company_id.
Restriction of access rights ¶
Creating a service aim is available to agents in accordance with the settings of access rights. It is only possible to specify a link with a company if the key-linked agent has the right to add a service aim to the company in accordance with the access rights settings. This method is not available for keys linked to contact persons.
URI example
POST https://<account>.okdesk.com/api/v1/maintenance_entities/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"maintenance_entity": {
"name": "Sales outlet No.13",
"company_id": 1040,
"agreement_ids": [
2
],
"address": "3709 Charter Street, Overland Park, KS 66210",
"comment": "Comment",
"default_assignee_id": 12,
"default_assignee_group_id": 1,
"timezone": "Moscow",
"coordinates": [
53.2184321,
44.9998082
],
"schedule_id": 1,
"observer_ids": [
5,
12
],
"custom_parameters": {
"code1": "123456789",
"code2": "2019-02-15",
"code3": true
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 9,
"name": "Sales outlet No.13",
"address": "3709 Charter Street, Overland Park, KS 66210",
"comment": "Comment",
"default_assignee_id": 12,
"default_assignee_group_id": 1,
"company_id": 1040,
"timezone": {
"code": "Moscow",
"name": "Moscow",
"gmt": "+03:00"
},
"coordinates": [
53.2184321,
44.9998082
],
"parameters": [
{
"code": "code1",
"name": "Document No.",
"field_type": "ftstring",
"value": "123456789"
},
{
"code": "code2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-15"
},
{
"code": "code3",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
}
],
"schedule": {
"id": 1,
"name": "On weekdays, 9 a.m. to 6 p.m."
},
"observers": [
{
"id": 5,
"name": "Robyn Fuller"
},
{
"id": 12,
"name": "Alix Mckay"
}
],
"observer_groups": [],
"attachments": [],
"agreements": [
{
"id": 2,
"title": "Important Contract"
}
]
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"maintenance_entity": {
"name": "Sales outlet No.13",
"company_id": 9999999,
"address": "3709 Charter Street, Overland Park, KS 66210",
"comment": "Comment",
"default_assignee_id": 12,
"default_assignee_group_id": 1
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"company": [
"Entry 9999999 does not exist"
]
}
}Editing a service aim
PATCH/api/v1/maintenance_entities/{id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | optional | Name |
| company_id | integer | optional | Company ID |
| agreement_ids | array of int | optional | Contracts IDs |
| address | string | optional | Address. Warning! When transmitting the text part of the address, automatic substitution of the address coordinates (geocoding) is not provided. To have the address displayed on the map, you must further specify address coordinates in the coordinates parameter. You can convert the text part of the address into coordinates using geocoding services, for example, the Google Geocoding API, etc. |
| coordinates | array of float | optional | Service aim coordinates |
| timezone | string | optional | Service aim time zone |
| comment | string | optional | Service aim additional info |
| default_assignee_id | integer | optional | ID of responsible agent by default |
| default_assignee_group_id | integer | optional | ID of responsible group by default |
| schedule_id | integer | optional | Service aim schedule ID |
| observer_ids | array of int | optional | Array of IDs of users viewing the service aim |
| observer_group_ids | array of int | optional | Array of IDs of agent groups viewing the service aim |
| custom_parameters | associative array | optional | Extended attributes of service aim |
Please note ¶
name parameter can not be transferred with an empty value
The coordinates parameter is an array of two real numbers (-90 to 90 latitude and -180 to 180 longitude). The agreement_ids parameter must contain IDs of contracts of an edited service aim company.
Restriction of access rights ¶
Editing a service aim will be possible only if the key-linked agent has the rights to view the service aim and edit the service aim attributes in accordance with the settings of access rights. It is only possible to specify a link with a company if the key-linked agent has the right to add a service aim to the company in accordance with the access rights settings. This method is not available for keys linked to contact persons.
URI example
PATCH https://<account>.okdesk.com/api/v1/maintenance_entities/4?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 4Service aim ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"maintenance_entity": {
"name": "Shop No. 15",
"agreement_ids": [
3
],
"address": "2537 Goldie Lane, Cincinnati, OH 45203",
"default_assignee_id": 14,
"default_assignee_group_id": 1,
"timezone": "Samara",
"schedule_id": 1,
"observer_group_ids": [
7
],
"coordinates": [
53.2184321,
44.9998082
],
"custom_parameters": {
"code2": "2019-02-15"
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 9,
"name": "Shop No. 15",
"address": "2537 Goldie Lane, Cincinnati, OH 45203",
"comment": "Comment",
"default_assignee_id": 14,
"default_assignee_group_id": 1,
"company_id": 1040,
"timezone": {
"code": "Samara",
"name": "Samara",
"gmt": "+04:00"
},
"coordinates": [
53.2184321,
44.9998082
],
"parameters": [
{
"code": "code1",
"name": "Document No.",
"field_type": "ftstring",
"value": "123456789"
},
{
"code": "code2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-15"
},
{
"code": "code3",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
}
],
"schedule": {
"id": 1,
"name": "On weekdays, 9 a.m. to 6 p.m."
},
"observers": [],
"observer_groups": [
{
"id": 7,
"name": "Electricians"
}
],
"attachments": [
{
"attachment_file_name": "file.jpg",
"description": "Description",
"is_public": true,
"id": 575
}
],
"agreements": [
{
"id": 3,
"title": "Another Important Contract"
}
]
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"maintenance_entity": {
"name": ""
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"name": [
"cannot be blank"
]
}
}Service aim info
GET/api/v1/maintenance_entities/{id}{?api_token}
Restriction of access rights ¶
Service aim info will be provided only if the key-linked agent has the right to view the service aim in accordance with the settings of access rights.
URI example
GET https://<account>.okdesk.com/api/v1/maintenance_entities/153?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 153Service aim ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"name": "Newco Service Center"
"2365 Shobe Lane, Durango, CO 81301"
"comment": "",
"default_assignee_id": 12,
"default_assignee_group_id": 1,
"company_id": 1,
"timezone": {
"code": "Kaliningrad",
"name": "Kaliningrad",
"gmt": "+02:00"
},
"contacts_ids": [
23,
24,
63,
64,
65
],
"equipments_ids": [
8,
9
],
"coordinates": [
53.2605796,
49.9179003
],
"parameters": [
{
"code": "attr1",
"name": "Document No.",
"field_type": "ftstring",
"value": "2368590"
},
{
"code": "attr2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-06"
},
{
"code": "attr3",
"name": "Date of the next call",
"field_type": "ftdatetime",
"value": "2019-02-21T14:00:00.000+03:00"
},
{
"code": "attr4",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
},
{
"code": "attr5",
"name": "Type of activity",
"field_type": "ftselect",
"value": "Software"
},
{
"code": "attr6",
"name": "Types of premises",
"field_type": "ftmultiselect",
"value": [
"Head office",
"Recreation area"
]
}
],
"schedule": {
"id": 1,
"name": "On weekdays, 9 a.m. to 6 p.m."
},
"observers": [
{
"id": 5,
"name": "Jareth Charles"
}
],
"observer_groups": [
{
"id": 7,
"name": "Electricians"
}
],
"attachments": [
{
"attachment_file_name": "file.jpg",
"description": "Description",
"is_public": true,
"id": 575
}
],
"agreements": [
{
"id": 2,
"title": "Important Contract"
}
]
}Obtaining list by parameters
GET/api/v1/maintenance_entities/list{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| company_ids | array of integer | optional | Array of company IDs. Example: company_ids[]=1 |
| default_assignee_ids | array of integer | optional | Array of responsible agent IDs (set the value “0” to the parameter to show service aims without a responsible agent). Example: default_assignee_ids[]=1 |
| default_assignee_group_ids | array of integer | optional | Array of responsible group IDs (set the value “0” to the parameter to show service aims without a responsible group). Example: default_assignee_group_ids[]=1 |
| created_since | string | optional | The date the service aim was created in the account’s time zone (From) Example: created_since=2019-05-25 |
| created_until | string | optional | The date the service aim was created in the account’s time zone (Until) Example: created_until=2019-05-25 |
| updated_since | string | optional | The date the service aim was modified in the account’s time zone (From) Example: updated_since=2019-05-25 |
| updated_until | string | optional | The date the service aim was modified in the account’s time zone (Until) Example: updated_until=2019-05-25 |
| page | associative array | optional | Associative array of parameters for a per-page display of the service aim list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the service aim starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the service aim id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the service aim’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the service aim’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
The list of service aims will be provided only if the key-linked agent has access to a service aim list in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
Please note ¶
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 service aims created will be returned.
An example of a query with the service aim list per-page display parameters ¶
https://<account>.okdesk.com/api/v1/maintenance_entities/list?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=forwardURI example
GET https://<account>.okdesk.com/api/v1/maintenance_entities/list?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 8,
"name": "Aim No.2",
"address": "Anytown",
"coordinates": [
55.755831,
37.617673
],
"company_id": 1
},
{
"id": 5,
"name": "Aim No.1",
"address": "Your Town",
"coordinates": [
59.869778,
30.278344
],
"company_id": 3
}
]Attaching files to a service aim
POST/api/v1/maintenance_entities/{id}/attachments/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| attachments | array | required | List of attached files |
Valid query attached files parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| attachment | string | required | Attachable file |
| description | string | optional | File description |
| is_public | boolean | optional | File availability |
Please note ¶
-
The content of the query with attached files shall be multipart/form-data and contain the corresponding title.
-
If parameter is_public is not sent, availability flag for the attachable files will be equal to the value of settings parameter ‘Files by default’
Restriction of access rights ¶
Adding a file to a service aim is available to agents in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
URI example
POST https://<account>.okdesk.com/api/v1/maintenance_entities/153/attachments/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Ключ авторизации.
- id
integer(required) Example: 153service aim ID.
Request
with attached filesHideShow
Headers
Content-Type: multipart/form-dataBody
curl -H "Content-Type: multipart/form-data"
-F "maintenance_entity[attachments][0][attachment]=@/example/file.jpg"
-F "maintenance_entity[attachments][0][is_public]=true"
-F "maintenance_entity[attachments][0][description]=Description"
https://<account>.okdesk.ru/api/v1/maintenance_entities/{id}/attachments/{?api_token}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"name": "Newco Service Center"
"2365 Shobe Lane, Durango, CO 81301"
"comment": "",
"default_assignee_id": 12,
"default_assignee_group_id": 1,
"company_id": 1,
"timezone": {
"code": "Moscow",
"name": "Moscow",
"gmt": "+03:00"
},
"contacts_ids": [
23,
24,
63,
64,
65
],
"equipments_ids": [
8,
9
],
"coordinates": [
53.2605796,
49.9179003
],
"parameters": [
{
"code": "attr1",
"name": "Document No.",
"field_type": "ftstring",
"value": "2368590"
},
{
"code": "attr2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-06"
},
{
"code": "attr3",
"name": "Date of the next call",
"field_type": "ftdatetime",
"value": "2019-02-21T14:00:00.000+03:00"
},
{
"code": "attr4",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
},
{
"code": "attr5",
"name": "Type of activity",
"field_type": "ftselect",
"value": "Software"
},
{
"code": "attr6",
"name": "Types of premises",
"field_type": "ftmultiselect",
"value": [
"Head office",
"Recreation area"
]
}
],
"schedule": {
"id": 1,
"name": "On weekdays, 9 a.m. to 6 p.m."
},
"observers": [],
"observer_groups": [],
"attachments": [
{
"attachment_file_name": "file.jpg",
"description": "Description",
"is_public": true,
"id": 575
}
],
"agreements": [
{
"id": 2,
"title": "Important Contract"
}
]
}Integration with telephone service ¶
Transfer of information about the incoming call
POST/api/v1/telephony/messages{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| telephony_numbers | array of integer | required | Extensions of employees, to which the call was transferred. |
| search_numbers_count | integer | required | The number of last digits of the caller’s number to find a match. |
| phone | string | required | The caller’s number. |
Restriction of access rights ¶
Data access is available without limitation only for keys associated with admin users (the “Administrator” role).
URI example
POST https://<account>.okdesk.com/api/v1/telephony/messages?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"telephony_numbers": [
123,
456
],
"search_numbers_count": 7,
"phone": "1232123"
}Response
200HideShow
Body
{}Making an entry about the phone call
POST/api/v1/phone_calls{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| call_id | string | required | Call ID in the external system |
| started_at | string | required | Call start date/time |
| finished_at | string | required | Call termination date/time |
| duration | integer | required | Call duration (in seconds) |
| direction | integer | required | Call direction (1 for outgoing and 0 for incoming) |
| receiver_phone | string | required | Receiving number |
| source_phone | string | required | Caller’s number |
| search_numbers_count | integer | required | Number of the last digits of the outside party’s number to find a match in the client database |
| file_url | string | optional | Link to download a file with a recording of a phone call |
Restriction of access rights ¶
The method is only available for key associated with the user role “Administrator”.
URI example
POST https://<account>.okdesk.com/api/v1/phone_calls?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"phone_call": {
"call_id": "test-123",
"started_at": "2019-02-24 09:16",
"finished_at": "2019-02-24 09:17",
"duration": 60,
"direction": 1,
"source_phone": "811111111111",
"receiver_phone": "82222222222",
"search_numbers_count": 10,
"file_url": "https://test.com/file.mp3"
}
}Response
201Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"phone_call": {
"started_at": "2019-02-24 09:17",
"finished_at": "2019-02-24 09:16",
"duration": 60,
"direction": 3,
"source_phone": "811111111111",
"receiver_phone": "82222222222",
"search_numbers_count": -1,
"file_url": "https://test.com/file.mp3"
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"search_numbers_count": [
"must be greater than 0"
],
"call_id": [
"is missing"
],
"direction": [
"must be one of: 0, 1"
],
"compare_dates": [
"End time of phone call must be greater than start time"
],
}
}Price list ¶
Obtaining lists by parameters
GET/api/v1/price_lists{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| page | associative array | optional | Associative array of parameters for a per-page display of the price list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the price list starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the price list id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
The method is only available for key associated with the user role “Administrator”.
Please note ¶
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 price list lines created will be returned.
An example of a query with the price list lines per-page display parameters: ¶
https://<account>.okdesk.com/api/v1/price_lists?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverseURI example
GET https://<account>.okdesk.com/api/v1/price_lists?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 101,
"name": "Price list of maintenance",
"allow_without_category": false,
"allow_without_company": false,
"company_category_codes": [
"partner",
"client",
"vipclient"
],
"company_ids": [
441,
41
]
},
{
"id": 100,
"name": "General services, works and materials price list of the company",
"allow_without_category": false,
"allow_without_company": false,
"company_category_codes": [],
"company_ids": []
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"page": {
"size": [
"must be less than or equal to 100"
],
"direction": [
"must be one of: reverse, forward"
],
"from_id": [
"must be an integer"
]
}
}
}Obtaining list line by parameters
GET/api/v1/price_lists/{price_list_id}/services{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| types | array of string | required | Array of price list sections. Acceptable values: service, work, product. Example: &types[]=work&types[]=service |
| page | associative array | optional | Associative array of parameters for a per-page display of the price list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the price list starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the price list id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
The method is only available for key associated with the user role “Administrator”.
Please note ¶
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 price list lines created will be returned.
An example of a query with the price list lines per-page display parameters: ¶
https://<account>.okdesk.com/api/v1/price_lists/153/services?
api_token=3e9a214215f493c4&types[]=service&page[size]=3&page[from_id]=10&page[direction]=reverseURI example
GET https://<account>.okdesk.com/api/v1/price_lists/154/services?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- price_list_id
integer(required) Example: 154Price list ID.
- types[]
array[string](required) Example: 'work'Array of price list sections.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1,
"code": "timerateservice",
"name": "Pay per time services",
"type": "service",
"unit": "man-hour",
"price": 1000,
"nds": 0,
"visible": true,
"description": "Different billed pay per hour services"
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"types": {
"0": [
"must be one of: service, work, product"
]
},
"page": {
"size": [
"must be less than or equal to 100"
],
"direction": [
"must be one of: reverse, forward"
],
"from_id": [
"must be an integer"
]
}
}
}Price list line adding method
POST/api/v1/price_lists/{price_list_id}/services{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| code | string | required | Directory line code |
| name | string | required | Directory line name |
| type | string | required | Directory line section. Acceptable values: work, product, service |
| unit | string | required | Unit of measure |
| price | number | required | Price |
| nds | integer | required | VAT rate, % |
| visible | boolean | optional | Activity status. Takes true or false value |
| description | string | optional | Description |
Restriction of access rights ¶
The method is only available for key associated with the user role “Administrator”.
URI example
POST https://<account>.okdesk.com/api/v1/price_lists/154/services?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- price_list_id
integer(required) Example: 154Price list ID.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"service": {
"code": "timerateservice",
"name": "Pay per time services",
"type": "service",
"unit": "man-hour",
"price": 1000,
"nds": 0,
"description": "Different billed pay per hour services"
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"code": "timerateservice",
"name": "Pay per time services",
"type": "service",
"unit": "man-hour",
"price": 1000,
"nds": 0,
"visible": true,
"description": "Different billed pay per hour services"
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"service": {
"code": "timerateservice",
"type": "wrong",
"unit": "man-hour",
"price": "wrong",
"nds": 0,
"description": "Different billed pay per hour services"
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"name": [
"is missing"
],
"type": [
"must be one of: service, work, product"
],
"price": [
"must be a float or must be an integer"
]
}
}Price list line editing method
PATCH/api/v1/price_lists/{price_list_id}/services/{code}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | optional | Directory line name |
| type | string | optional | Directory line section. Acceptable values: work, product, service |
| unit | string | optional | Unit of measure |
| price | number | optional | Price |
| nds | integer | optional | VAT rate, % |
| visible | boolean | optional | Activity status. Takes true or false value |
| description | string | optional | Description |
Restriction of access rights ¶
The method is only available for key associated with the user role “Administrator”.
URI example
PATCH https://<account>.okdesk.com/api/v1/price_lists/154/services/timerateservice?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- price_list_id
integer(required) Example: 154Price list ID.
- code
string(required) Example: timerateserviceDirectory line code.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"service": {
"type": "work",
"price": 2000,
"nds": 5
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"code": "timerateservice",
"name": "Pay per time services",
"type": "work",
"unit": "man-hour",
"price": 2000,
"nds": 5,
"visible": true,
"description": "Different billed pay per hour services"
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"service": {
"type": "wrong",
"price": "wrong"
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"type": [
"must be one of: service, work, product"
],
"price": [
"must be a float or must be an integer"
]
}
}Obtaining available price list lines by parameters for ticket and user
GET/api/v1/issues/{issue_id}/available_services{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| search_string | string | optional | Target substring in price list line name |
| page | associative array | optional | Associative array of parameters for a per-page display of the price list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the price list starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the price list id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
- This method is only available for keys associated with agents who have access to actions “View the ticket”, “Editing the ticket quantities”.
Please note ¶
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 equipment types created will be returned.
An example of a query with the price list lines per-page display parameters ¶
https://<account>.okdesk.ru/api/v1/issues/1/available_services?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverse&search_string=firstURI example
GET https://<account>.okdesk.com/api/v1/issues/763/available_services?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763Ticket ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"price_list_id": 3,
"price_list_name": "Price list of maintenance",
"id": 1,
"code": "timerateservice",
"name": "Pay per time services",
"type": "work",
"unit": "man-hour",
"price": 2000,
"nds": 5,
"description": "Different billed pay per hour services"
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"page": {
"size": [
"must be less than or equal to 100"
],
"direction": [
"must be one of: reverse, forward"
],
"from_id": [
"must be an integer"
]
}
}
}Directories ¶
Obtaining a list of ticket types
GET/api/v1/issues/types/{?api_token}
Please note ¶
For contact-associated keys, internal-type tickets are not returned. Only limited information will be available:
-
ID of the ticket type;
-
Name of the ticket type;
-
Ticket type code;
-
Information about the presence of the “Available for selection by client” indicator in the ticket type;
-
Information about the presence of the “by default” indicator in the ticket type.
URI example
GET https://<account>.okdesk.com/api/v1/issues/types/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1,
"code": "incident",
"name": "Incident",
"available_for_client": true,
"default": false,
"inner": false
},
{
"id": 2,
"code": "inner",
"name": "Inner",
"available_for_client": false,
"default": false,
"inner": true
},
{
"id": 3,
"code": "service",
"name": "Service",
"available_for_client": true,
"default": true,
"inner": false
}
]Obtaining a list of ticket priorities
GET/api/v1/issues/priorities/{?api_token}
URI example
GET https://<account>.okdesk.com/api/v1/issues/priorities/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"code": "low",
"name": "Low",
"position": 1,
"default": true,
"color": "#8e9eb3"
},
{
"code": "normal",
"name": "Normal",
"position": 2,
"default": false,
"color": "#5cb85c"
},
{
"code": "high",
"name": "High",
"position": 3,
"default": false,
"color": "#ea2e49"
}
]Obtaining a list of equipment types
GET/api/v1/equipments/kinds/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| search_string | string | optional | Target substring in equipment type name or code |
| page | associative array | optional | Associative array of parameters for a per-page display of the equipment type list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the equipment type starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the equipment type id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment type’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment type’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
The method is only available for key associated with the user role “Administrator”.
Please note ¶
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 equipment types created will be returned.
An example of a query with the equipment type list per-page display parameters ¶
https://<account>.okdesk.com/api/v1/equipments/kinds/?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=forward&search_string=specialURI example
GET https://<account>.okdesk.com/api/v1/equipments/kinds/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 5,
"code": "005",
"name": "somewhatspecialequipment",
"description": "somewhat special equipment",
"visible": true,
"parameters": [
{
"name": "Some_parameter 3",
"field_type": "ftcheckbox"
}
]
},
{
"id": 8,
"code": "008",
"name": "specialequipment",
"description": "special equipment",
"visible": true,
"parameters": [
{
"name": "Some_parameter 2",
"field_type": "ftcheckbox"
}
]
},
{
"id": 10,
"code": "010",
"name": "veryspecialequipment",
"description": "very special equipment",
"visible": true,
"parameters": [
{
"name": "Some_parameter 1",
"field_type": "ftcheckbox"
},
{
"name": "Some_parameter 2",
"field_type": "ftcheckbox"
}
]
}
]Creating equipment type
POST/api/v1/equipments/kinds/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | required | Equipment type name |
| code | string | required | Equipment type code |
| description | string | optional | Equipment type description |
| parameter_codes | array of string | optional | Array of codes of linked extended attributes of equipment |
Restriction of access rights ¶
The method is only available for key associated with the user role “Administrator”.
URI example
POST https://<account>.okdesk.com/api/v1/equipments/kinds/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"equipment_kind": {
"code": "sample_code",
"name": "sample_name",
"description": "sample_text",
"parameter_codes": [
"001",
"002"
]
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 57,
"code": "sample_code",
"name": "sample_name",
"description": "sample_text",
"visible": true,
"parameters": [
{
"name": "Parameter 1",
"field_type": "ftstring"
},
{
"name": "Parameter 2",
"field_type": "ftstring"
}
]
}Editing of equipment type
PATCH/api/v1/equipments/kinds/{kind_id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | optional | Equipment type name |
| description | string | optional | Equipment type description |
| parameter_codes | array of string | optional | Array of codes of linked extended attributes of equipment |
| visible | boolean | optional | Nesting indicator |
Restriction of access rights ¶
The method is only available for key associated with the user role “Administrator”.
URI example
PATCH https://<account>.okdesk.com/api/v1/equipments/kinds/57?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- kind_id
integer(required) Example: 57Edited equipment type ID
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"equipment_kind": {
"name": "changed_name",
"description": "changed_text",
"visible": false,
"parameter_codes": [
"001",
"003"
]
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 57,
"code": "code",
"name": "changed_name",
"description": "changed_text",
"visible": false,
"parameters": [
{
"name": "Parameter 1",
"field_type": "ftstring"
},
{
"name": "Parameter 3",
"field_type": "ftcheckbox"
}
]
}Obtaining equipment manufacturers list
GET/api/v1/equipments/manufacturers/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| search_string | string | optional | Target substring in equipment manufacturer name or code |
| page | associative array | optional | Associative array of parameters for a per-page display of the equipment manufacturer list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the equipment manufacturer starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the equipment manufacturer id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment manufacturer’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment manufacturer’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
The method is only available for key associated with the user role “Administrator”.
Please note ¶
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 equipment manufacturers created will be returned.
An example of a query with the equipment manufacturer list per-page display parameters ¶
https://<account>.okdesk.com/api/v1/equipments/manufacturers/?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=11&page[direction]=forward&search_string=specialURI example
GET https://<account>.okdesk.com/api/v1/equipments/manufacturers/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 5,
"code": "005",
"name": "manufacturer 5",
"description": "somewhat special manufacturer",
"visible": true
},
{
"id": 8,
"code": "008",
"name": "manufacturer 8",
"description": "special manufacturer",
"visible": true
},
{
"id": 10,
"code": "010",
"name": "manufacturer 10",
"description": "very special manufacturer",
"visible": true
}
]Creating equipment manufacturer
POST/api/v1/equipments/manufacturers/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | required | Equipment manufacturer name |
| code | string | required | Equipment manufacturer code |
| description | string | optional | Equipment manufacturer description |
Restriction of access rights ¶
The method is only available for key associated with the user role “Administrator”.
URI example
POST https://<account>.okdesk.com/api/v1/equipments/manufacturers/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"equipment_manufacturer": {
"code": "sample_code",
"name": "sample_name",
"description": "sample_text"
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 57,
"code": "sample_code",
"name": "sample_name",
"description": "sample_text",
"visible": true
}Editing equipment manufacturer
PATCH/api/v1/equipments/manufacturers/{manufacturer_id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | optional | Equipment manufacturer name |
| description | string | optional | Equipment manufacturer description |
| visible | boolean | optional | Nesting indicator |
Restriction of access rights ¶
The method is only available for key associated with the user role “Administrator”.
URI example
PATCH https://<account>.okdesk.com/api/v1/equipments/manufacturers/57?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- manufacturer_id
integer(required) Example: 57ID of editing equipment manufacturer
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"equipment_manufacturer": {
"name": "changed_name",
"description": "changed_text",
"visible": false
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 57,
"code": "code",
"name": "changed_name",
"description": "changed_text",
"visible": false
}Obtaining list of equipment models
GET/api/v1/equipments/models/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| search_string | string | optional | Target substring in equipment model name or code |
| page | associative array | optional | Associative array of parameters for a per-page display of the equipment model list (detailed description is available in the table below)… |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the equipment model starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the equipment model id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment model’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment model’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
The method is only available for key associated with the user role “Administrator”.
Please note ¶
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 equipment models created will be returned.
An example of a query with the equipment models list lines per-page display parameters: ¶
https://<account>.okdesk.com/api/v1/equipments/models/?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=forward&search_string=specialURI example
GET https://<account>.okdesk.com/api/v1/equipments/models/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 5,
"code": "005",
"name": "somewhatspecialequipment",
"description": "somewhat special equipment",
"visible": true,
"equipment_kind": {
"code": "002",
"id": 2,
"name": "sample_kind"
},
"equipment_manufacturer": {
"code": "001",
"id": 1,
"name": "sample_manufacturer"
}
},
{
"id": 8,
"code": "008",
"name": "specialequipment",
"description": "special equipment",
"visible": true,
"equipment_kind": {
"code": "002",
"id": 2,
"name": "sample_kind"
},
"equipment_manufacturer": {
"code": "002",
"id": 2,
"name": "second_sample_manufacturer"
}
},
{
"id": 10,
"code": "010",
"name": "veryspecialequipment",
"description": "very special equipment",
"visible": true,
"equipment_kind": {
"code": "003",
"id": 4,
"name": "another_sample_kind"
},
"equipment_manufacturer": {
"code": "001",
"id": 1,
"name": "sample_manufacturer"
}
}
]Creating equipment models
POST/api/v1/equipments/models/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | required | Equipment model name |
| code | string | required | Equipment model code |
| equipment_kind_id | integer | required | Equipment type ID |
| equipment_manufacturer_id | integer | required | Equipment manufacturer ID |
| description | string | optional | Equipment model description |
Restriction of access rights ¶
The method is only available for key associated with the user role “Administrator”.
URI example
POST https://<account>.okdesk.com/api/v1/equipments/models/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"equipment_model": {
"code": "model_code",
"name": "model_name",
"description": "sample",
"equipment_kind_id": 1,
"equipment_manufacturer_id": 1
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 57,
"code": "model_code",
"name": "model_name",
"description": "sample",
"visible": true,
"equipment_kind": {
"code": "001",
"id": 1,
"name": "sample_kind"
},
"equipment_manufacturer": {
"code": "001",
"id": 1,
"name": "sample_manufacturer"
}
}Editing equipment model
PATCH/api/v1/equipments/models/{model_id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | optional | Equipment model name |
| description | string | optional | Equipment model description |
| visible | boolean | optional | Nesting indicator |
| equipment_kind_id | integer | optional | Equipment type ID |
| equipment_manufacturer_id | integer | optional | Equipment manufacturer ID |
Restriction of access rights ¶
The method is only available for key associated with the user role “Administrator”.
URI example
PATCH https://<account>.okdesk.com/api/v1/equipments/models/57?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- model_id
integer(required) Example: 57ID of editing equipment model
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"equipment_model": {
"name": "changed_name",
"description": "changed_text",
"visible": false,
"equipment_kind_id": 2,
"equipment_manufacturer_id": 3
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 57,
"code": "model code",
"name": "changed_name",
"description": "changed_text",
"visible": false,
"equipment_kind": {
"code": "002",
"id": 2,
"name": "sample_kind"
},
"equipment_manufacturer": {
"code": "003",
"id": 3,
"name": "some_manufacturer"
}
}Obtaining a list of time zones
GET/api/v1/timezones{?api_token}
Restriction of access rights ¶
The method is only available for keys associated with the user role “Administrator”.
URI example
GET https://<account>.okdesk.com/api/v1/timezones?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"code": "Kaliningrad",
"name": "Kaliningrad",
"gmt": "+02:00"
},
{
"code": "Moscow",
"name": "Moscow",
"gmt": "+03:00"
},
{
"code": "Samara",
"name": "Samara",
"gmt": "+04:00"
},
{
"code": "Irkutsk",
"name": "Irkutsk",
"gmt": "+08:00"
}
]Miscellaneous ¶
Creating a link to the login
POST/api/v1/login_link{?api_token}
Generation of a new one-time link to user authentication
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| user_login | string | optional | User login |
| user_type | string | optional | User type. Acceptable types: employee - agent, contact - contact person |
| user_id | integer | optional | User ID |
| expire_after | integer | optional | The link’s life in minutes. It will be set to 30 days, if its value is not defined. |
| one_time | boolean | optional | Link type (one-time / reusable). If the parameter is not passed, a one-time link for the login is created |
Please note ¶
If there is no user_login or one of the parameters user_type, user_id parameters, the link to login will be generated for the user associated with the key.
Restriction of access rights ¶
The generation of links to user authentication is available without limitation only for keys associated with admin users (the “Administrator” role). In other cases, you can generate a link to authorization only for a user associated with the key.
URI example
POST https://<account>.okdesk.com/api/v1/login_link?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"user_login": "employee@okdesk.com",
"expire_after": 60,
"one_time": false
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"login_link": "http://<account>.okdesk.com/login?token=430379fd78be7c71623cad7590b8a23d",
"user_id": 56,
"user_type": "employee",
"roles": [
"Administrator"
],
"user_first_name": "John",
"user_last_name": "Kennedy",
"user_patronymic": "Fitzgerald",
"user_position": "Head of Technology",
"user_email": "example@example.com",
"user_custom_parameters": []
}Creating an API-key for a user
POST/api/v1/api_key{?api_token}
Generating a new API-key for a user
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| user_type | string | mandatory | User type (employee or contact) |
| id | integer | mandatory | User ID |
Restriction of access rights ¶
The method is only available for keys associated with the user role “Administrator”.
URI example
POST https://<account>.okdesk.com/api/v1/api_key?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"user_type": "employee",
"id": 1
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"api_key": "12345ghy8be7c71623cad7590b8a5q3"
}Request
HideShow
Headers
Content-Type: application/jsonBody
{
"user_type": "employee",
"id": 12
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": "The requested user has been disabled"
}Obtaining an API-key of a user
GET/api/v1/api_key{?api_token}&user_type={user_type}&id={id}
Restriction of access rights ¶
The method is only available for keys associated with the user role “Administrator”.
URI example
GET https://<account>.okdesk.com/api/v1/api_key?api_token=3e9a214215f493c4&user_type=employee&id=2
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 2User internal ID
- user_type
string(required) Example: employeeUser type
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"api_key": "430379fd78be7c71623cad7590b8a23d"
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": "The requested user has been disabled"
}Obtaining an API-key of a user by login and password
POST/api/v1/users/sign_in
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| login | string | required | User login (employee or contact) |
| password | string | required | Password |
URI example
POST https://<account>.okdesk.com/api/v1/users/sign_in
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"login": "user",
"password": "Password"
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"api_key": "430379fd78be7c71623cad7590b8a23d"
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"login": "user"
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"password": [
"is missing"
]
}
}
Adding a comment
POST
/api/v1/issues/{issue_id}/comments{?api_token}Valid query parameters: ¶
Acceptable types: employee (default) - agent, contact - contact person
Please note ¶
If the public parameter is not specified, the comment created by default will be private.
Contacts cannot create private comments.
If the author_type parameter is not specified, the agent will be author of the comment by default.
Restriction of access rights ¶
For agents, comment will be added to a ticket if only the agent associated with the key has the right to view the ticket and to add the comment in accordance with access rights settings. For contact-associated keys, it is only possible to add a public comment. For keys of users not associated with the “Administrator” role (including contacts), the value of the author_id parameter will be ignored (comment will be added on behalf of the key owner).
Acceptable parameters of attachable files: ¶
Please note ¶
The content of the query with attached files shall be multipart/form-data and contain the corresponding title.
The availability flag for the attachable files will be set similar to the transferred value for the comment, to which the files are attached
URI example
string(required) Example: 3e9a214215f493c4Authorization key.
integer(required) Example: 254ticket ID.
Headers
Content-Type: application/jsonBody
{ "comment": { "content": "Very soon an engineer will come to you to solve the problem.", "public": true, "author_id": 10, "author_type": "employee" } }200Headers
Content-Type: application/jsonBody
{ "id": 1, "content": "Very soon an engineer will come to you to solve the problem.", "public": true, "author": { "id": 10, "name": "Juan Perez" "type": "employee" } }with attached filesHeaders
Content-Type: multipart/form-dataBody
curl -H "Content-Type: multipart/form-data" -F "comment[content]=Here are the long-awaited report files" -F "comment[public]=true" -F "comment[author_id]=15" -F "comment[author_type]=employee" -F "comment[attachments][0][attachment]=@/path/to/file.txt" -F "comment[attachments][0][description]=report" -F "comment[attachments][1][attachment]=@/path/to/file.docx" https://<account>.okdesk.com/api/v1/issues/{issue_id}/comments/{?api_token}200Headers
Content-Type: application/jsonBody
{ "id": 1, "content": "Here are the long-awaited report files", "public": true, "author": { "id": 15, "name": "David Sarif", "type": "employee" } }with incorrect parametersHeaders
Content-Type: application/jsonBody
{ "comment": { "content": "Very soon an engineer will come to you to solve the problem.", "public": false, "author_id": 22221, "author_type": "contact" } }422Headers
Content-Type: application/jsonBody
{ "errors": { "author_presence": [ "user is not found" ], "contact_comment_cannot_be_private": [ "the contact cannot be an author of a private comment" ] } }