API Introduction
OneDesk provides Representational State Transfer (REST) web service. To use a REST API, your can make an HTTP request and parse the response. The request and response support JSON.
URI Structures
The URIs in OneDesk have the following structures: https://onedesk.com/rest/api-version/api-name/resource-name api-version: The current api-version is 2.0
Login API
Login
POST https://app.onedesk.com/rest/2.0/login/loginUser
You should either send the email and the password OR the cookie |
Request fields
Path | Type | Description |
---|---|---|
|
|
Email of the user |
|
|
password of the user |
|
|
Login cookie |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
user name |
|
|
Authentication token |
|
|
Cookie to be used next time the user want to login |
|
|
User ID |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/login/loginUser' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"cookie" : "",
"email" : "john.smith@acme.com",
"password" : "XXXXXXXXXX"
}'
Example request
POST /rest/2.0/login/loginUser HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 83
{
"cookie" : "",
"email" : "john.smith@acme.com",
"password" : "XXXXXXXXXX"
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 184
{
"code" : "SUCCESS",
"data" : {
"name" : "John Smith",
"authenticationToken" : "00000000000",
"cookie" : "4b034b7a-9c3d-4a67-b2d9-a0c4dd2a134a",
"userId" : 1
}
}
Logout
GET https://app.onedesk.com/rest/2.0/login/logoutUser
Request parameters
Parameter | Description |
---|---|
|
authentication token |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/login/logoutUser?token=00000000000' -i -H 'Accept: application/json'
Example request
GET /rest/2.0/login/logoutUser?token=00000000000 HTTP/1.1
Accept: application/json
Host: app.onedesk.com
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 41
{
"code" : "SUCCESS",
"data" : null
}
Organization API
Get organization basic information
GET https://app.onedesk.com/rest/2.0/organization/getOrgInfo
Request parameters
Parameter | Description |
---|---|
|
authentication token |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
Id of the lifecycleStatus |
|
|
Name of the lifecycleStatus |
|
|
icon style of the lifecycleStatus |
|
|
Icon color of the lifecycleStatus |
|
|
Applied property of the lifecycleStatus |
|
|
Name of the item type |
|
|
icon style of the item type |
|
|
Icon color of the item type |
|
|
visibility of the item type |
|
|
item type |
|
|
Name of the user type |
|
|
icon style of the user type |
|
|
Icon color of the user type |
|
|
user type |
|
|
view project management |
|
|
view product management |
|
|
view feedback management |
|
|
view work |
|
|
view dashboard |
|
|
view all items |
|
|
default thread visibility type |
|
|
organization Uri |
|
|
organization dateFormat |
|
|
organization name |
|
|
view users |
|
|
view customers |
|
|
view containers |
|
|
view activities & Discussions |
|
|
view communication |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/organization/getOrgInfo?token=00000000000' -i -H 'Accept: application/json'
Example request
GET /rest/2.0/organization/getOrgInfo?token=00000000000 HTTP/1.1
Accept: application/json
Host: app.onedesk.com
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1687
{
"code" : "SUCCESS",
"data" : {
"statuses" : [ {
"id" : 6544131,
"name" : "In Progress",
"iconStyleName" : "in_progress_icon_style",
"iconColor" : 25651,
"appliedProperty" : "TASK_TYPE_1_LCS"
}, {
"id" : 6544132,
"name" : "Finished",
"iconStyleName" : "finished_icon_style",
"iconColor" : 21526,
"appliedProperty" : "TASK_TYPE_1_LCS"
} ],
"itemTypes" : [ {
"itemType" : "TASK_TYPE_1",
"name" : "Task",
"iconStyleName" : "task_icon_style",
"iconColor" : 21526,
"visible" : true
}, {
"itemType" : "TASK_TYPE_2",
"name" : "Issue",
"iconStyleName" : "issue_icon_style",
"iconColor" : 987426,
"visible" : true
} ],
"userTypes" : [ {
"userType" : "USER_TYPE_1",
"name" : "User",
"iconStyleName" : "user_icon_style",
"iconColor" : 845152
}, {
"userType" : "USER_TYPE_2",
"name" : "VIP user",
"iconStyleName" : "vip_user_icon_style",
"iconColor" : 21654
} ],
"applicationVisibility" : {
"viewAllItems" : true,
"viewProjectManagement" : true,
"viewProductManagement" : true,
"viewFeedbackManagement" : true,
"viewWork" : false,
"viewDashboard" : false,
"viewUsers" : true,
"viewCustomers" : true,
"viewContainers" : true,
"viewActivities" : true,
"viewCommunication" : true
},
"policy" : {
"defaultThreadVisibilityType" : "PUBLIC_DISCUSSION_POST"
},
"organizationProfile" : {
"dateFormat" : "Date",
"organizationName" : "onedesk",
"organizationUri" : "onedesk"
}
}
}
Space API
Get space by id
POST https://app.onedesk.com/rest/2.0/space/getItemById
Request fields
Path | Type | Description |
---|---|---|
|
|
authentication token |
|
|
ID of the space |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
space details (see response example for details) |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/space/getItemById' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"authenticationToken" : "00000000000",
"id" : 333
}'
Example request
POST /rest/2.0/space/getItemById HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 57
{
"authenticationToken" : "00000000000",
"id" : 333
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 257
{
"code" : "SUCCESS",
"data" : {
"id" : 333,
"name" : "space 1",
"description" : "...",
"type" : "SPACE_TYPE_0",
"created" : "2019-10-18T11:09:08:548+00:00",
"parentIds" : [ 444, null ],
"customFields" : {
"cf1" : "cf1 value"
}
}
}
Create space
POST https://app.onedesk.com/rest/2.0/space/create
Request fields
Path | Type | Description |
---|---|---|
|
|
authentication token |
|
|
name of the space |
|
|
type of the space (SPACE_TYPE_0 .. SPACE_TYPE_9) |
|
|
description of the space |
|
|
array of parent/portfolio IDs |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
Id of the created space |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/space/create' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"name" : "space 1",
"authenticationToken" : "00000000000",
"containerType" : "SPACE_TYPE_0",
"description" : "description 1",
"parentIds" : [ 345 ]
}'
Example request
POST /rest/2.0/space/create HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 161
{
"name" : "space 1",
"authenticationToken" : "00000000000",
"containerType" : "SPACE_TYPE_0",
"description" : "description 1",
"parentIds" : [ 345 ]
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 56
{
"code" : "SUCCESS",
"data" : {
"id" : 33
}
}
Search spaces
POST https://app.onedesk.com/rest/2.0/space/search
Request fields
Path | Type | Description |
---|---|---|
|
|
authentication token |
|
|
array of space IDs to filter |
|
|
array of filters |
|
|
name of the property to filter ([custom field name], creatorId, name) |
|
|
operation of the filter (EQ, NE, NOT_EMPTY) |
|
|
the value of the property to filter (date value must be a Unix timestamp in MILLISECONDS) |
|
|
set this to true for custom field/property filter |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
total number of IDs |
|
|
array of IDs of the spaces |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/space/search' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"authenticationToken" : "00000000000",
"itemIds" : [ ],
"filters" : [ {
"propertyName" : "name",
"operation" : "EQ",
"value" : "space 1",
"isCustomField" : false
}, {
"propertyName" : "Custom Field 3",
"operation" : "NOT_EMPTY",
"value" : "",
"isCustomField" : true
} ]
}'
Example request
POST /rest/2.0/space/search HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 315
{
"authenticationToken" : "00000000000",
"itemIds" : [ ],
"filters" : [ {
"propertyName" : "name",
"operation" : "EQ",
"value" : "space 1",
"isCustomField" : false
}, {
"propertyName" : "Custom Field 3",
"operation" : "NOT_EMPTY",
"value" : "",
"isCustomField" : true
} ]
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 82
{
"code" : "SUCCESS",
"data" : {
"items" : [ 3, 5 ],
"total" : 2
}
}
Portfolio API
Get portfolio by id
POST https://app.onedesk.com/rest/2.0/portfolio/getItemById
Request fields
Path | Type | Description |
---|---|---|
|
|
authentication token |
|
|
ID of the portfolio |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
portfolio details (see response example for details) |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/portfolio/getItemById' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"authenticationToken" : "00000000000",
"id" : 444
}'
Example request
POST /rest/2.0/portfolio/getItemById HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 57
{
"authenticationToken" : "00000000000",
"id" : 444
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 182
{
"code" : "SUCCESS",
"data" : {
"id" : 444,
"name" : "portfolio 1",
"type" : "PORTFOLIO_TYPE_0",
"created" : "2019-10-18T11:09:08:237+00:00",
"parentIds" : [ 555, null ]
}
}
Search portfolios
POST https://app.onedesk.com/rest/2.0/portfolio/search
Request fields
Path | Type | Description |
---|---|---|
|
|
authentication token |
|
|
array of portfolio IDs to filter |
|
|
array of filters |
|
|
name of the property to filter (name) |
|
|
operation of the filter (EQ, NE) |
|
|
the value of the property to filter (date value must be a Unix timestamp in MILLISECONDS) |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
total number of IDs |
|
|
array of IDs of the portfolios |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/portfolio/search' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"authenticationToken" : "00000000000",
"itemIds" : [ ],
"filters" : [ {
"propertyName" : "name",
"operation" : "EQ",
"value" : "portfolio 1",
"isCustomField" : false
} ]
}'
Example request
POST /rest/2.0/portfolio/search HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 197
{
"authenticationToken" : "00000000000",
"itemIds" : [ ],
"filters" : [ {
"propertyName" : "name",
"operation" : "EQ",
"value" : "portfolio 1",
"isCustomField" : false
} ]
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 80
{
"code" : "SUCCESS",
"data" : {
"items" : [ 50 ],
"total" : 1
}
}
User API
Create user
POST https://app.onedesk.com/rest/2.0/user/create
Request fields
Path | Type | Description |
---|---|---|
|
|
Authentication token |
|
|
The new user email |
|
|
The first name |
|
|
The last name |
|
|
The user type (USER_TYPE_1 .. USER_TYPE_10, CUSTOMER_TYPE_1 .. CUSTOMER_TYPE_10) |
|
|
The ID of the team |
|
|
The registration status (INVITATION_SENT) |
|
|
true if the new user should be an administrator |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
Id of the newly created user |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/user/create' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"authenticationToken" : "00000000000",
"email" : "john.smith@acme.com",
"firstName" : "john",
"lastName" : "smith",
"type" : "USER_TYPE_1",
"teamId" : 1,
"isAdministrator" : false,
"registrationStatus" : "REGISTERED"
}'
Example request
POST /rest/2.0/user/create HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 236
{
"authenticationToken" : "00000000000",
"email" : "john.smith@acme.com",
"firstName" : "john",
"lastName" : "smith",
"type" : "USER_TYPE_1",
"teamId" : 1,
"isAdministrator" : false,
"registrationStatus" : "REGISTERED"
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 60
{
"code" : "SUCCESS",
"data" : {
"id" : 945621
}
}
Get users
POST https://app.onedesk.com/rest/2.0/user/get
Request fields
Path | Type | Description |
---|---|---|
|
|
Authentication token |
|
|
The IDs of users |
|
|
The emails of users (if user IDs are not specified) |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
list of users (see response example for details) |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/user/get' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"authenticationToken" : "00000000000",
"usersIds" : [ 123547, 851651 ],
"usersEmails" : [ ]
}'
Example request
POST /rest/2.0/user/get HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 101
{
"authenticationToken" : "00000000000",
"usersIds" : [ 123547, 851651 ],
"usersEmails" : [ ]
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1837
{
"code" : "SUCCESS",
"data" : [ {
"id" : 851651,
"organizationId" : 1,
"loginName" : null,
"category" : null,
"type" : "USER_TYPE_1",
"activationStatus" : null,
"registrationStatus" : null,
"lastInvitation" : null,
"customFields" : [ ],
"externalId" : null,
"calendarUrl" : null,
"profile" : {
"id" : null,
"email" : null,
"firstName" : "John",
"lastName" : "Smith",
"phoneWork" : null,
"photoUrl" : null,
"title" : null,
"pictureKey" : "k1",
"color" : "#FF0000"
},
"address" : null,
"userCalendarOptions" : null,
"created" : null,
"authorId" : null,
"priority" : null,
"organizationalId" : null,
"userWorkTimer" : null,
"pushNotificationsRegistrationId" : null,
"destructorId" : null,
"deleteDate" : null,
"userConversationsSettings" : null,
"displayName" : "John Smith"
}, {
"id" : 123547,
"organizationId" : 1,
"loginName" : null,
"category" : null,
"type" : "USER_TYPE_2",
"activationStatus" : null,
"registrationStatus" : null,
"lastInvitation" : null,
"customFields" : [ ],
"externalId" : null,
"calendarUrl" : null,
"profile" : {
"id" : null,
"email" : null,
"firstName" : "Derek",
"lastName" : "Gold",
"phoneWork" : null,
"photoUrl" : null,
"title" : null,
"pictureKey" : "k2",
"color" : "#FF0000"
},
"address" : null,
"userCalendarOptions" : null,
"created" : null,
"authorId" : null,
"priority" : null,
"organizationalId" : null,
"userWorkTimer" : null,
"pushNotificationsRegistrationId" : null,
"destructorId" : null,
"deleteDate" : null,
"userConversationsSettings" : null,
"displayName" : "Derek Gold"
} ]
}
Load user work timer
GET https://app.onedesk.com/rest/2.0/user/userWorkTimer
Request parameters
Parameter | Description |
---|---|
|
authentication token |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
the user id |
|
|
the work item id |
|
|
the start date of this work timer |
|
|
The amount of work in hours for this work timer |
|
|
the start date of the current progress of the work timer |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/user/userWorkTimer?token=00000000000' -i -H 'Accept: application/json'
Example request
GET /rest/2.0/user/userWorkTimer?token=00000000000 HTTP/1.1
Accept: application/json
Host: app.onedesk.com
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 183
{
"code" : "SUCCESS",
"data" : {
"id" : 651321,
"itemId" : 213547,
"startDate" : "2019-10-18T11:09:08:687+00:00",
"amountOfWork" : 6.0,
"startCurrentTimer" : "2019-10-18T11:09:08:687+00:00"
}
}
Start work timer
GET https://app.onedesk.com/rest/2.0/user/startWorkTimer
Request parameters
Parameter | Description |
---|---|
|
authentication token |
|
Id of the work item to start the work timer |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
the amount of work already spent on this work timer |
|
|
the result of your activity change (SUCCESS, FAILED,FAILED_ITEM_NOT_FOUND, FAILED_USER_NOT_FOUND, FAILED_VALUE_NOT_FOUND, FAILED_USER_ALREADY_EXIST,FAILED_WRONG_FUNCTION_SEQUENCE, FAILED_BUSY, FAILED_WRONG_INPUT_DATA) |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/user/startWorkTimer?token=00000000000&itemId=9846251' -i -H 'Accept: application/json'
Example request
GET /rest/2.0/user/startWorkTimer?token=00000000000&itemId=9846251 HTTP/1.1
Accept: application/json
Host: app.onedesk.com
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 91
{
"code" : "SUCCESS",
"data" : {
"type" : "SUCCESS",
"amountOfWork" : 6.0
}
}
Pause work timer
GET https://app.onedesk.com/rest/2.0/user/pauseWorkTimer
Request parameters
Parameter | Description |
---|---|
|
authentication token |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
the amount of work already spent on this work timer |
|
|
the result of your activity change (SUCCESS, FAILED,FAILED_ITEM_NOT_FOUND, FAILED_USER_NOT_FOUND, FAILED_VALUE_NOT_FOUND, FAILED_USER_ALREADY_EXIST,FAILED_WRONG_FUNCTION_SEQUENCE, FAILED_BUSY, FAILED_WRONG_INPUT_DATA) |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/user/pauseWorkTimer?token=00000000000' -i -H 'Accept: application/json'
Example request
GET /rest/2.0/user/pauseWorkTimer?token=00000000000 HTTP/1.1
Accept: application/json
Host: app.onedesk.com
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 91
{
"code" : "SUCCESS",
"data" : {
"type" : "SUCCESS",
"amountOfWork" : 6.0
}
}
Resume work timer
GET https://app.onedesk.com/rest/2.0/user/resumeWorkTimer
Request parameters
Parameter | Description |
---|---|
|
authentication token |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
the amount of work already spent on this work timer |
|
|
the result of your activity change (SUCCESS, FAILED,FAILED_ITEM_NOT_FOUND, FAILED_USER_NOT_FOUND, FAILED_VALUE_NOT_FOUND, FAILED_USER_ALREADY_EXIST,FAILED_WRONG_FUNCTION_SEQUENCE, FAILED_BUSY, FAILED_WRONG_INPUT_DATA) |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/user/resumeWorkTimer?token=00000000000' -i -H 'Accept: application/json'
Example request
GET /rest/2.0/user/resumeWorkTimer?token=00000000000 HTTP/1.1
Accept: application/json
Host: app.onedesk.com
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 91
{
"code" : "SUCCESS",
"data" : {
"type" : "SUCCESS",
"amountOfWork" : 6.0
}
}
Reset work timer
GET https://app.onedesk.com/rest/2.0/user/resetWorkTimer
Request parameters
Parameter | Description |
---|---|
|
authentication token |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
the amount of work already spent on this work timer |
|
|
the result of your activity change (SUCCESS, FAILED,FAILED_ITEM_NOT_FOUND, FAILED_USER_NOT_FOUND, FAILED_VALUE_NOT_FOUND, FAILED_USER_ALREADY_EXIST,FAILED_WRONG_FUNCTION_SEQUENCE, FAILED_BUSY, FAILED_WRONG_INPUT_DATA) |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/user/resetWorkTimer?token=00000000000' -i -H 'Accept: application/json'
Example request
GET /rest/2.0/user/resetWorkTimer?token=00000000000 HTTP/1.1
Accept: application/json
Host: app.onedesk.com
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 91
{
"code" : "SUCCESS",
"data" : {
"type" : "SUCCESS",
"amountOfWork" : 6.0
}
}
User/Customer Team API
Get user teams
POST https://app.onedesk.com/rest/2.0/userteam/get
Request fields
Path | Type | Description |
---|---|---|
|
|
Authentication token |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
list of organization user/customer teams (see response example for details) |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/userteam/get' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"authenticationToken" : "00000000000"
}'
Example request
POST /rest/2.0/userteam/get HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 43
{
"authenticationToken" : "00000000000"
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 134
{
"code" : "SUCCESS",
"data" : [ {
"id" : 1,
"name" : "team1",
"category" : "USER",
"userIds" : [ 23, 25 ]
} ]
}
Activity API
Get followed discussions
POST https://app.onedesk.com/rest/2.0/activity/getFollowedDiscussions
Request fields
Path | Type | Description |
---|---|---|
|
|
Authentication token |
|
|
offset of the pagination |
|
|
limit of the pagination |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
Total number of followed activities |
|
|
Id of the followed activity |
|
|
Date and time of the activity |
|
|
Id of the author |
|
|
name of the author |
|
|
profile picture key of the author |
|
|
profile picture color of the author |
|
|
type of the author |
|
|
the author is deleted |
|
|
Id of the item |
|
|
Name of the item |
|
|
new value name |
|
|
new value |
|
|
is this followed activity read? |
|
|
activity details |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/activity/getFollowedDiscussions' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"authenticationToken" : "00000000000",
"offset" : 0,
"limit" : 10
}'
Example request
POST /rest/2.0/activity/getFollowedDiscussions HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 75
{
"authenticationToken" : "00000000000",
"offset" : 0,
"limit" : 10
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1065
{
"code" : "SUCCESS",
"data" : {
"items" : [ {
"followedActivityId" : 65835,
"timestamp" : "2019-10-18T11:09:08:347+00:00",
"author" : {
"id" : 851651,
"name" : "John Smith",
"pictureKey" : "k1",
"type" : "USER_TYPE_1",
"color" : "#FF0000",
"isDeleted" : false
},
"itemId" : 51651,
"itemName" : "Modify all the products",
"newValueName" : "Are you sure?",
"newValue" : "DiscussionPost.985143",
"read" : true,
"activityDetails" : "_author_jabber_id_"
}, {
"followedActivityId" : 8156,
"timestamp" : "2019-10-18T11:09:08:347+00:00",
"author" : {
"id" : 123547,
"name" : "Derek Gold",
"pictureKey" : "k2",
"type" : "USER_TYPE_2",
"color" : "#FF0000",
"isDeleted" : false
},
"itemId" : 858156,
"itemName" : "Delete typos",
"newValueName" : "Done!",
"newValue" : "DiscussionPost.1581526",
"read" : false,
"activityDetails" : "_author_jabber_id_2_"
} ],
"total" : 2
}
}
Mark followed discussion as read
GET https://app.onedesk.com/rest/2.0/activity/markAsRead
Request parameters
Parameter | Description |
---|---|
|
authentication token |
|
Id of the followed item |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/activity/markAsRead?token=00000000000&followedActivityId=6541251' -i -H 'Accept: application/json'
Example request
GET /rest/2.0/activity/markAsRead?token=00000000000&followedActivityId=6541251 HTTP/1.1
Accept: application/json
Host: app.onedesk.com
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 41
{
"code" : "SUCCESS",
"data" : null
}
History API
Get item updates
POST https://app.onedesk.com/rest/2.0/history/getItemUpdates
Request fields
Path | Type | Description |
---|---|---|
|
|
authentication token |
|
|
unique application ID to track updated/changes |
|
|
array of item types to filter |
|
|
array of item IDs to filter |
|
|
array of operations to filter (CREATE, DELETE, PROPERTY_UPDATE, ADD_TO_COLLECTION, REMOVE_FROM_COLLECTION) |
|
|
array of property names to filter |
|
|
array of new values to filter |
|
|
array of old values to filter |
|
|
array of 2nd order filters |
|
|
name of the property of the 2nd order filter ([custom field name], authorId, spaceName) |
|
|
operation of the 2nd order filter (EQ, NE, NOT_EMPTY) |
|
|
the value of the property of 2nd order filter |
|
|
set this to true for custom field/property 2nd order filter |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
array of history items (see example of response) |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/history/getItemUpdates' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"authenticationToken" : "00000000000",
"applicationId" : "app_1",
"itemTypes" : [ ],
"itemIds" : [ ],
"operations" : [ ],
"propertyNames" : [ ],
"newValues" : [ ],
"oldValues" : [ ],
"filters" : [ {
"propertyName" : "Custom Field 1",
"operation" : "NOT_EMPTY",
"value" : "",
"isCustomField" : true
}, {
"propertyName" : "spaceName",
"operation" : "EQ",
"value" : "Space 1",
"isCustomField" : false
} ]
}'
Example request
POST /rest/2.0/history/getItemUpdates HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 459
{
"authenticationToken" : "00000000000",
"applicationId" : "app_1",
"itemTypes" : [ ],
"itemIds" : [ ],
"operations" : [ ],
"propertyNames" : [ ],
"newValues" : [ ],
"oldValues" : [ ],
"filters" : [ {
"propertyName" : "Custom Field 1",
"operation" : "NOT_EMPTY",
"value" : "",
"isCustomField" : true
}, {
"propertyName" : "spaceName",
"operation" : "EQ",
"value" : "Space 1",
"isCustomField" : false
} ]
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 522
{
"code" : "SUCCESS",
"data" : [ {
"collectedTimestamp" : "2019-10-18T11:09:08:433+00:00",
"authorId" : 3,
"itemType" : "ProjectTask",
"itemId" : 1,
"parentItemType" : null,
"parentItemId" : null,
"itemName" : "item1",
"operation" : "PROPERTY_UPDATE",
"propertyName" : "description",
"newValue" : "nv1",
"newValueName" : null,
"oldValue" : "ov1",
"oldValueName" : null,
"organizationId" : 1,
"spaceId" : 4,
"loadedTimestamp" : "2019-10-18T11:09:08:434+00:00",
"blackList" : null
} ]
}
Work items API
Get todo list
POST https://app.onedesk.com/rest/2.0/workitem/getToDoItems
Request fields
Path | Type | Description |
---|---|---|
|
|
Authentication token |
|
|
Offset of the pagination |
|
|
Limit of the pagination |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
total number of items |
|
|
Id of the work item |
|
|
Name of the work item |
|
|
Type of the work item |
|
|
Planned finish of the work item |
|
|
Lifecycle status id of the work item |
|
|
Number of comments in the work item |
|
|
priority of the work item ([0,20,40,60,80,100] correspond to [0,1,2,3,4,5] stars respectively) |
|
|
creation date of the work item |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/workitem/getToDoItems' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"authenticationToken" : "00000000000",
"filterId" : 123,
"limit" : 10,
"offset" : 0
}'
Example request
POST /rest/2.0/workitem/getToDoItems HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 95
{
"authenticationToken" : "00000000000",
"filterId" : 123,
"limit" : 10,
"offset" : 0
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 627
{
"code" : "SUCCESS",
"data" : {
"items" : [ {
"id" : 6948156,
"name" : "Define the planning for next release",
"type" : "TASK_TYPE_1",
"plannedFinish" : "2019-10-18T11:09:09:011+00:00",
"createDate" : "2019-10-18T11:09:09:011+00:00",
"lifecycleStatusId" : 561581,
"priority" : 20,
"numberOfComments" : 2
}, {
"id" : 488456,
"name" : "The blue button doesn't work",
"type" : "TASK_TYPE_2",
"plannedFinish" : "2019-10-18T11:09:09:011+00:00",
"createDate" : "2019-10-18T11:09:09:011+00:00",
"lifecycleStatusId" : 126447,
"priority" : 100,
"numberOfComments" : 18
} ],
"total" : 2
}
}
Search items
POST https://app.onedesk.com/rest/2.0/workitem/searchItems
Request fields
Path | Type | Description |
---|---|---|
|
|
authentication token |
|
|
array of item IDs to filter |
|
|
array of filters |
|
|
name of the property to filter ([custom field name], authorId, spaceName, edited, requesterId) |
|
|
operation of the filter (EQ, NE, NOT_EMPTY, LE, GE) where LE, GE applicable for dates, e.g. "edited" property |
|
|
the value of the property to filter (date value must be a Unix timestamp in MILLISECONDS and all numerical values should be integers (12 not 12.00)) |
|
|
set this to true for custom field filter OR set this to false for other property filter |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
total number of IDs |
|
|
array of IDs of the items |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/workitem/searchItems' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"authenticationToken" : "00000000000",
"itemIds" : [ ],
"filters" : [ {
"propertyName" : "Custom Field 1",
"operation" : "NOT_EMPTY",
"value" : "",
"isCustomField" : true
} ]
}'
Example request
POST /rest/2.0/workitem/searchItems HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 202
{
"authenticationToken" : "00000000000",
"itemIds" : [ ],
"filters" : [ {
"propertyName" : "Custom Field 1",
"operation" : "NOT_EMPTY",
"value" : "",
"isCustomField" : true
} ]
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 82
{
"code" : "SUCCESS",
"data" : {
"items" : [ 1, 2 ],
"total" : 2
}
}
Update work item
POST https://app.onedesk.com/rest/2.0/workitem/updateWorkItem
Request fields
Path | Type | Description |
---|---|---|
|
|
authentication token |
|
|
the id of the item |
|
|
name of the item |
|
|
description of the item |
|
|
priority of the item ([0,20,40,60,80,100] correspond to [0,1,2,3,4,5] stars respectively) |
|
|
progress of the item |
|
|
array of IDs of the linked items |
|
|
object (map) of properties/values of custom fields |
|
|
lifecycle status name of the item |
|
|
lifecycle status name of the item |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
the id of the updated item |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/workitem/updateWorkItem' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"authenticationToken" : "00000000000",
"itemId" : 1,
"name" : "new name",
"description" : "updated description",
"priority" : 40,
"progress" : 90.0,
"relatedItemIds" : [ 2, 3 ],
"customFields" : {
"customField1" : "value1"
},
"lifecycleStatusName" : "In Progress",
"edited" : null
}'
Example request
POST /rest/2.0/workitem/updateWorkItem HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 310
{
"authenticationToken" : "00000000000",
"itemId" : 1,
"name" : "new name",
"description" : "updated description",
"priority" : 40,
"progress" : 90.0,
"relatedItemIds" : [ 2, 3 ],
"customFields" : {
"customField1" : "value1"
},
"lifecycleStatusName" : "In Progress",
"edited" : null
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 59
{
"code" : "SUCCESS",
"data" : {
"id" : 15474
}
}
Create work item
POST https://app.onedesk.com/rest/2.0/workitem/createWorkItem
Request fields
Path | Type | Description |
---|---|---|
|
|
authentication token |
|
|
the type of the item |
|
|
name of the item |
|
|
description of the item |
|
|
attachment ids |
|
|
Id of the container (optional) |
|
|
priority of the work item ([0,20,40,60,80,100] correspond to [0,1,2,3,4,5] stars respectively) |
|
|
IDs of the requesters |
|
|
object (map) of properties/values of custom fields |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
the id of the created item |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/workitem/createWorkItem' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"authenticationToken" : "00000000000",
"name" : "new name",
"description" : "my description",
"attachmentIds" : [ "0d984f0a", "6c5d4a02", "6c5d4a03" ],
"type" : "FEEDBACK_TYPE_1",
"spaceId" : 321,
"priority" : 0,
"requesterIds" : [ 33 ],
"customFields" : null
}'
Example request
POST /rest/2.0/workitem/createWorkItem HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 281
{
"authenticationToken" : "00000000000",
"name" : "new name",
"description" : "my description",
"attachmentIds" : [ "0d984f0a", "6c5d4a02", "6c5d4a03" ],
"type" : "FEEDBACK_TYPE_1",
"spaceId" : 321,
"priority" : 0,
"requesterIds" : [ 33 ],
"customFields" : null
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 57
{
"code" : "SUCCESS",
"data" : {
"id" : 151
}
}
Get work item details
GET https://app.onedesk.com/rest/2.0/workitem/getItemDetails
Request parameters
Parameter | Description |
---|---|
|
authentication token |
|
Id of the work item |
|
OR by organizationalId of the work item |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
work item id |
|
|
work item id in the organization |
|
|
space id |
|
|
name of the work item |
|
|
description of the work item |
|
|
type of the work item |
|
|
planned finish of the work item |
|
|
creation date of the work item |
|
|
company name of the work item |
|
|
team name of the work item |
|
|
project name of the work item |
|
|
organization name of the requester of the work item |
|
|
requester of the work item |
|
|
the type of the requester of the work item |
|
|
work performed of the work item |
|
|
priority of the work item ([0,20,40,60,80,100] correspond to [0,1,2,3,4,5] stars respectively) |
|
|
number of comments in the work item |
|
|
number of attachments in the work item |
|
|
Is the current user assigned to this work item? |
|
|
lifecycle id of the work item |
|
|
Number of agile points of the work item |
|
|
planned duration amount of the work item |
|
|
planned duration unit of the work item (DAYS, HOURS) |
|
|
percent complete of the work item |
|
|
IDs of the requesters |
|
|
object (map) of properties/values of custom fields |
|
|
id of the attachment |
|
|
key of the attachment |
|
|
name of the attachment |
|
|
content type of the attachment |
|
|
Id of the comment |
|
|
title of the comment |
|
|
body of the comment |
|
|
author id of the comment |
|
|
author type of the comment |
|
|
author name of the comment |
|
|
profile picture key of the author of the comment |
|
|
profile picture color of the author of the comment |
|
|
creation date of the comment |
|
|
Id of the item related to this comment |
|
|
Comment type (OLD_REQUESTER_ONLY_POST, PUBLIC_DISCUSSION_POST, PRIVATE_DISCUSSION_POST) |
|
|
Replies of this comment (with the same properties) |
|
|
the attachments of the post |
|
|
true if the author is deleted |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/workitem/getItemDetails?token=00000000000&workItemId=695165&organizationalId=102' -i -H 'Accept: application/json'
Example request
GET /rest/2.0/workitem/getItemDetails?token=00000000000&workItemId=695165&organizationalId=102 HTTP/1.1
Accept: application/json
Host: app.onedesk.com
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2163
{
"code" : "SUCCESS",
"data" : {
"id" : 695165,
"organizationalId" : 102,
"name" : "The blue button doesn't work",
"requester" : "requester",
"requesterType" : "requesterType",
"companyName" : "company name",
"teamName" : "team name",
"organizationName" : "organization name",
"projectName" : "project name",
"description" : "Why is the blue button <strong>not</strong> working. I was working last week !",
"type" : "TASK_TYPE_2",
"plannedFinish" : "2019-10-18T11:09:09:968+00:00",
"createDate" : "2019-10-18T11:09:09:968+00:00",
"workPerformed" : 1,
"priority" : 80,
"numberOfComments" : 2,
"numberOfAttachments" : 1,
"lifecycleStatusId" : 65165,
"agilePoints" : 2,
"scheduledDurationAmount" : 1.0,
"scheduledDurationUnit" : "DAYS",
"percentComplete" : 30.0,
"attachments" : [ {
"fileId" : 514954,
"name" : "Blue bug.jpg",
"identityKey" : "k1",
"contentType" : "image/jpeg"
} ],
"posts" : [ {
"id" : 513258,
"title" : "I don't see this bug",
"content" : "I have tried <strong>everything</strong>, but I cannot reproduce this issue",
"author" : {
"id" : 12354,
"name" : "John Smith",
"pictureKey" : "k1",
"type" : "USER_TYPE_1",
"color" : "#FF0000",
"isDeleted" : false
},
"creationDate" : "2019-10-18T11:09:09:969+00:00",
"relatedItemId" : 695165,
"postType" : "PRIVATE_DISCUSSION_POST",
"replies" : [ {
"id" : 98258,
"title" : "Ho ok now I see it",
"content" : "Ho ok now I see it, <strong>this<strong> actually was easy",
"author" : {
"id" : 12354,
"name" : "John Smith",
"pictureKey" : "k2",
"type" : "USER_TYPE_1",
"color" : "#FF0000",
"isDeleted" : false
},
"creationDate" : "2019-10-18T11:09:09:969+00:00",
"relatedItemId" : 695165,
"postType" : "PRIVATE_DISCUSSION_POST",
"replies" : [ ],
"attachments" : [ ]
} ],
"attachments" : [ ]
} ],
"spaceId" : 1,
"customFields" : null,
"requesterIds" : [ 33 ],
"assigned" : true
}
}
Get work item details 2
GET https://app.onedesk.com/rest/2.0/workitem/getItemDetails2
Request parameters
Parameter | Description |
---|---|
|
authentication token |
|
Id of the work item |
|
OR by organizationalId of the work item |
Reponse fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
work item id |
|
|
work item id in the organization |
|
|
name of the work item |
|
|
description of the work item |
|
|
type of the work item |
|
|
lifecycle status id of the work item |
|
|
lifecycle status name of the work item |
|
|
priority of the work item ([0,20,40,60,80,100] correspond to [0,1,2,3,4,5] stars respectively) |
|
|
creation date of the work item |
|
|
edit date of the work item |
|
|
last time the work item status was changed to 'in progress' |
|
|
last close date of the work item |
|
|
author id |
|
|
author type |
|
|
author display name |
|
|
author email |
|
|
author team name |
|
|
assignee id |
|
|
assignee type |
|
|
assignee display name |
|
|
assignee email |
|
|
assignee team name |
|
|
assigned team id |
|
|
assigned team name |
|
|
IDs of the associated timesheets |
|
|
project id |
|
|
project name |
|
|
agile points of the work item |
|
|
IDs of the linked items |
|
|
true if the item is published |
|
|
actual start date of the work item |
|
|
actaul finish date of the work item |
|
|
actual cost of the work item |
|
|
actual work of the work item |
|
|
work unit (actual) |
|
|
actual completion |
|
|
planned start date of the work item |
|
|
finish date of the work item |
|
|
type of the work item |
|
|
planned work of the work item |
|
|
work unit (planned) |
|
|
planned cost of the work item |
|
|
id of the attachment |
|
|
name of the attachment |
|
|
content type of the attachment |
|
|
custom field name |
|
|
custom field value |
|
|
true if it is the default value |
|
|
follower type |
|
|
true if the follower is a requester |
|
|
follower id |
|
|
follower user type |
|
|
follower display name |
|
|
follower email |
|
|
follower team name |
|
|
following team id |
|
|
following team name |
|
|
sla of the work item |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/workitem/getItemDetails2?token=00000000000&workItemId=695165&organizationalId=102' -i -H 'Accept: application/json'
Example request
GET /rest/2.0/workitem/getItemDetails2?token=00000000000&workItemId=695165&organizationalId=102 HTTP/1.1
Accept: application/json
Host: app.onedesk.com
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2096
{
"code" : "SUCCESS",
"data" : {
"id" : 695165,
"organizationalId" : 102,
"name" : "The blue button doesn't work",
"description" : "Why is the blue button not working. It was working last week!",
"type" : {
"id" : "FEEDBACK_TYPE_1",
"name" : "ticket"
},
"lifecycleStatus" : {
"id" : 65165,
"name" : "open"
},
"priority" : 80,
"created" : "2019-10-18T11:09:09:073+00:00",
"edited" : "2019-10-18T11:09:09:073+00:00",
"latestInProgress" : "2019-10-18T11:09:09:073+00:00",
"latestClose" : "2019-10-18T11:09:09:073+00:00",
"author" : {
"id" : 1,
"type" : "CUSTOMER_TYPE_1",
"displayName" : "Sample User",
"email" : "user@onedesk.com",
"teamName" : "Team"
},
"assignees" : [ {
"id" : 1,
"type" : "CUSTOMER_TYPE_1",
"displayName" : "Sample User",
"email" : "user@onedesk.com",
"teamName" : "Team"
} ],
"assignedTeams" : [ {
"id" : 1,
"name" : "Team"
} ],
"timesheets" : [ 123 ],
"project" : {
"id" : 1,
"name" : "Test Project"
},
"agilePoints" : 2,
"linkedItems" : [ 123 ],
"published" : true,
"actual" : {
"startDate" : "2019-10-18T11:09:09:073+00:00",
"finishDate" : "2019-10-18T11:09:09:073+00:00",
"cost" : 100.0,
"work" : 1.0,
"workunit" : "MAN_DAYS",
"completion" : 1.0
},
"planned" : {
"startDate" : "2019-10-18T11:09:09:073+00:00",
"finishDate" : "2019-10-18T11:09:09:073+00:00",
"type" : "WORK",
"work" : 1.0,
"workunit" : "MAN_DAYS",
"cost" : 100.0
},
"attachments" : [ {
"id" : "k1",
"name" : "Blue bug.jpg",
"contentType" : "image/jpeg"
} ],
"customFields" : [ {
"name" : "points",
"value" : "5",
"isDefault" : true
} ],
"followers" : [ {
"type" : "USER",
"user" : {
"id" : 1,
"type" : "CUSTOMER_TYPE_1",
"displayName" : "Sample User",
"email" : "user@onedesk.com",
"teamName" : "Team"
},
"team" : {
"id" : 1,
"name" : "Team"
},
"requester" : true
} ],
"sla" : "sample SLA"
}
}
Get items by IDs
POST https://app.onedesk.com/rest/2.0/workitem/getItems
Request fields
Path | Type | Description |
---|---|---|
|
|
Authentication token |
|
|
array of work item IDs |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
total number of items |
|
|
work items (see /rest/2.0/workitem/getItemDetails service for details) |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/workitem/getItems' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"authenticationToken" : "00000000000",
"workItemIds" : [ 695165, 695166 ]
}'
Example request
POST /rest/2.0/workitem/getItems HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 81
{
"authenticationToken" : "00000000000",
"workItemIds" : [ 695165, 695166 ]
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2320
{
"code" : "SUCCESS",
"data" : {
"items" : [ {
"id" : 695165,
"organizationalId" : 102,
"name" : "The blue button doesn't work",
"requester" : "requester",
"requesterType" : "requesterType",
"companyName" : "company name",
"teamName" : "team name",
"organizationName" : "organization name",
"projectName" : "project name",
"description" : "Why is the blue button <strong>not</strong> working. I was working last week !",
"type" : "TASK_TYPE_2",
"plannedFinish" : "2019-10-18T11:09:08:994+00:00",
"createDate" : "2019-10-18T11:09:08:994+00:00",
"workPerformed" : 1,
"priority" : 80,
"numberOfComments" : 2,
"numberOfAttachments" : 1,
"lifecycleStatusId" : 65165,
"agilePoints" : 2,
"scheduledDurationAmount" : 1.0,
"scheduledDurationUnit" : "DAYS",
"percentComplete" : 30.0,
"attachments" : [ {
"fileId" : 514954,
"name" : "Blue bug.jpg",
"identityKey" : "k1",
"contentType" : "image/jpeg"
} ],
"posts" : [ ],
"spaceId" : 1,
"customFields" : null,
"requesterIds" : [ 33 ],
"assigned" : true
}, {
"id" : 695166,
"organizationalId" : 102,
"name" : "The blue button doesn't work",
"requester" : "requester",
"requesterType" : "requesterType",
"companyName" : "company name",
"teamName" : "team name",
"organizationName" : "organization name",
"projectName" : "project name",
"description" : "Why is the blue button <strong>not</strong> working. I was working last week !",
"type" : "TASK_TYPE_2",
"plannedFinish" : "2019-10-18T11:09:08:994+00:00",
"createDate" : "2019-10-18T11:09:08:994+00:00",
"workPerformed" : 1,
"priority" : 80,
"numberOfComments" : 2,
"numberOfAttachments" : 1,
"lifecycleStatusId" : 65165,
"agilePoints" : 2,
"scheduledDurationAmount" : 1.0,
"scheduledDurationUnit" : "DAYS",
"percentComplete" : 30.0,
"attachments" : [ {
"fileId" : 514954,
"name" : "Blue bug.jpg",
"identityKey" : "k1",
"contentType" : "image/jpeg"
} ],
"posts" : [ ],
"spaceId" : 1,
"customFields" : null,
"requesterIds" : [ 33 ],
"assigned" : true
} ],
"total" : 2
}
}
Create comment
POST https://app.onedesk.com/rest/2.0/workitem/createComment
Request fields
Path | Type | Description |
---|---|---|
|
|
Authentication token |
|
|
Id of the work item to post a comment on |
|
|
Comment content |
|
|
Comment type (OLD_REQUESTER_ONLY_POST, PUBLIC_DISCUSSION_POST, PRIVATE_DISCUSSION_POST) |
|
|
Id of the parent comment (null if new thread) |
|
|
Attachment ids |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
Id of the newly created comment |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/workitem/createComment' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"parentPostId" : null,
"itemId" : 564654,
"attachmentIds" : [ "uuid1", "uuid2", "uuid3" ],
"token" : "00000000000",
"description" : "This button should not be red, it should be blue",
"postType" : "PRIVATE_DISCUSSION_POST"
}'
Example request
POST /rest/2.0/workitem/createComment HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 238
{
"parentPostId" : null,
"itemId" : 564654,
"attachmentIds" : [ "uuid1", "uuid2", "uuid3" ],
"token" : "00000000000",
"description" : "This button should not be red, it should be blue",
"postType" : "PRIVATE_DISCUSSION_POST"
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 43
{
"code" : "SUCCESS",
"data" : 564362
}
Worklogs API
Create worklog
POST https://app.onedesk.com/rest/2.0/worklog/createWorklog
Request fields
Path | Type | Description |
---|---|---|
|
|
Authentication token |
|
|
Id of the work item to create a worklog on |
|
|
percentage of the work done |
|
|
comment on the worklog |
|
|
start date of the worklog |
|
|
finish date of the worklog |
|
|
number of hours of work performed for this worklog |
|
|
Id of the new lifecycle status for the work item |
|
|
The worklog is billable |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
Id of the newly created worklog |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/worklog/createWorklog' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"authenticationToken" : "00000000000",
"itemId" : 894365,
"dateStart" : "2019-10-18T11:09:08:819+00:00",
"dateFinish" : "2019-10-18T11:09:08:819+00:00",
"works" : 5.0,
"percentage" : 50.4,
"billable" : false,
"comments" : "Fix the button color",
"lifecycleStatusId" : 591954
}'
Example request
POST /rest/2.0/worklog/createWorklog HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 260
{
"authenticationToken" : "00000000000",
"itemId" : 894365,
"dateStart" : "2019-10-18T11:09:08:819+00:00",
"dateFinish" : "2019-10-18T11:09:08:819+00:00",
"works" : 5.0,
"percentage" : 50.4,
"billable" : false,
"comments" : "Fix the button color",
"lifecycleStatusId" : 591954
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 43
{
"code" : "SUCCESS",
"data" : 564362
}
Get worklog
POST https://app.onedesk.com/rest/2.0/worklog/getItem
Request fields
Path | Type | Description |
---|---|---|
|
|
Authentication token |
|
|
id of the worklog to get |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
id of the worklog |
|
|
percentage of the work done |
|
|
start date of the worklog |
|
|
finish date of the worklog |
|
|
number of hours of work performed for this worklog |
|
|
cost of the worklog based on the amount of work performed |
|
|
status of the worklog |
|
|
id of the item of the worklog |
|
|
name of the item of the worklog |
|
|
user id of the worklog resource |
|
|
space id of the worklog |
|
|
worklog is billable |
|
|
worklog comments |
|
|
IDs of the requesters |
|
|
email of the requesters |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/worklog/getItem' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"authenticationToken" : "00000000000",
"id" : 1
}'
Example request
POST /rest/2.0/worklog/getItem HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 55
{
"authenticationToken" : "00000000000",
"id" : 1
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 521
{
"code" : "SUCCESS",
"data" : {
"id" : 1,
"dateStart" : "2019-10-18T11:09:08:819+00:00",
"dateFinish" : "2019-10-18T11:09:08:819+00:00",
"work" : 5.0,
"cost" : 5,
"percentage" : 50.4,
"status" : "NOT_APPROVED_YET",
"workItemId" : 2,
"workItemName" : "task name",
"resourceUserId" : 3,
"spaceId" : 45,
"comments" : "This is a comment.",
"billable" : false,
"requesterIds" : [ 1, 2, 3 ],
"requesterEmails" : [ "requester1@onedesk.com", "requester2@onedesk.com", "requester3@onedesk.com" ]
}
}
Customer portal API
Get Organization Details
GET https://app.onedesk.com/rest/2.0/customerportal/organizationDetails
Request parameters
Parameter | Description |
---|---|
|
URI of the organization |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
Organization id |
|
|
organization URI |
|
|
Organization name |
|
|
Can user submit item anonymously |
|
|
Display only user/customer containers at customer portal |
|
|
Can user view the list of work items |
|
|
Can the user see his work items? |
|
|
Can user view the list of previously submitted work items |
|
|
Can users see lifecycle status |
|
|
Can anybody see lifecycle status |
|
|
choose to show the branding on the creating form |
|
|
choose to show the branding on the customer portal |
|
|
choose to extend customer portal app |
|
|
date format in organization setting |
|
|
organization calendar data |
|
|
currency code in organization setting |
|
|
Container id |
|
|
Container name |
|
|
Container type name |
|
|
Container type label |
|
|
Container type icon style |
|
|
Container type icon color |
|
|
Url to load files |
|
|
generated file css id |
|
|
default language |
|
|
custom language file id |
|
|
logo file id |
|
|
creation forms |
|
|
statuses for creation forms |
|
|
custom field definitions for creation forms |
|
|
customer portals |
|
|
customer portals appearance options |
|
|
messenger |
|
|
web forms |
|
|
customer portals registration policy |
|
|
item type name |
|
|
item type label |
|
|
item type icon style |
|
|
item type icon color |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/customerportal/organizationDetails?uri=acme' -i -H 'Accept: application/json'
Example request
GET /rest/2.0/customerportal/organizationDetails?uri=acme HTTP/1.1
Accept: application/json
Host: app.onedesk.com
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2563
{
"code" : "SUCCESS",
"data" : {
"id" : 6513554,
"uri" : "acme",
"name" : "ACME Organization",
"canSubmitAnonymously" : false,
"viewWorkItemsList" : true,
"viewMyWorkItems" : true,
"lifecycleStatusVisibleForLoggedIn" : true,
"lifecycleStatusVisibleForEveryBody" : false,
"displayUserContainers" : false,
"viewPreviouslySubmittedItems" : false,
"spaces" : [ {
"id" : 56465,
"name" : "My project 1",
"type" : {
"name" : "SPACE_TYPE_0",
"label" : "Project",
"iconClassName" : "project_icon_style",
"iconColor" : 56513
}
}, {
"id" : 2365847,
"name" : "My project 2",
"type" : {
"name" : "SPACE_TYPE_0",
"label" : "Project",
"iconClassName" : "project_icon_style",
"iconColor" : 56513
}
} ],
"itemTypes" : [ {
"name" : "TASK_TYPE_1",
"label" : "Task",
"iconClassName" : "task_icon_style",
"iconColor" : 651365
}, {
"name" : "TASK_TYPE_2",
"label" : "Issue",
"iconClassName" : "issue_icon_style",
"iconColor" : 12354
} ],
"fileUrl" : "https://app.onedesk.com/cware/file/view",
"generatedCss" : "key",
"langKey" : "en",
"customLangFileId" : "key",
"logo" : "key",
"forms" : [ ],
"statuses" : { },
"customFieldDefinitions" : { },
"showPortalBranding" : true,
"showFormBranding" : true,
"showCustomerApp" : true,
"dateFormat" : "yy/dd/MM",
"customerPortals" : {
"0" : {
"id" : null,
"activated" : null,
"name" : null,
"position" : null,
"permissions" : null,
"configurableFormIds" : [ ]
}
},
"appearanceOptions" : {
"id" : null,
"mainColor" : null,
"bodyColor" : null,
"mainBGColor" : null,
"menuBGColor" : null,
"mainTextColor" : null,
"secondaryButtonTextColor" : null,
"secondaryButtonColor" : null,
"langKey" : null,
"customLangFileId" : null,
"showBranding" : null,
"showCustomerApp" : null,
"logoType" : null,
"logoUrl" : null
},
"messenger" : {
"id" : null,
"activated" : null,
"name" : null,
"position" : null
},
"webForms" : {
"id" : null,
"activated" : null,
"name" : null,
"position" : null
},
"calendar" : {
"holidays" : null,
"workingHoursPerDay" : null
},
"currencyCode" : "USD",
"registrationPolicy" : "ALLOW_SELF_REGISTER"
}
}
Get Work items list
GET https://app.onedesk.com/rest/2.0/customerportal/workItems
Request parameters
Parameter | Description |
---|---|
|
URI of the organization |
|
customer portal ID |
|
offset of the pagination |
|
limit of the pagination |
|
sort (TRENDING, RECENT, POPULAR) |
|
filter to get only the user requester work items |
|
filter to get only the user followed work items |
|
filter work items with a text search |
|
filter work items by type |
|
work items by project |
|
Authentication token |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
totla number of result |
|
|
types to filter |
|
|
projects to filter |
|
|
statuses to filter |
|
|
item id |
|
|
work item id in the organization |
|
|
work item name |
|
|
priority of the work item ([0,20,40,60,80,100] correspond to [0,1,2,3,4,5] stars respectively) |
|
|
project id |
|
|
project name |
|
|
description of the work item |
|
|
creation date of the work item |
|
|
number of followers of the work item |
|
|
true if the current user is following this work item |
|
|
true if the current user is following this work item (only with a user tag, not part of a team are all XXXXX) |
|
|
number of discussions in the work item |
|
|
number of attachments in the work item |
|
|
constraint type of the work item |
|
|
constraint date of the work item |
|
|
planned cost of the work item |
|
|
planned work of the work item |
|
|
planned work unit of the work item |
|
|
custom fields of the work item |
|
|
Id of the lifecycle status of the work item |
|
|
label of the lifecycle status of the work item |
|
|
status of the work item is default |
|
|
icon color of the lifecycle status of the work item |
|
|
true if the current user is the requester of the work item |
|
|
percent complete of the work item |
|
|
actual work of the work item |
|
|
actual start date of the work item |
|
|
actual finish date of the work item |
|
|
actual cost amount of the work item |
|
|
edited date of the work item |
|
|
latest close of the work item |
|
|
latest in progress of the work item |
|
|
author of the work item |
|
|
assignments names of the work item |
|
|
requesters names of the work item |
|
|
name of sla applied to the work item |
|
|
next sla breach of the work item |
|
|
item type name |
|
|
item type label |
|
|
item type icon style |
|
|
item type icon color |
|
|
id of the attachment |
|
|
key of the attachment |
|
|
name of the attachment |
|
|
content type of the attachment |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/customerportal/workItems?uri=acme&cpId=1&offset=0&limit=10&sort=TRENDING&myWorkItems=false&followedItems=false&search=bug&type=TASK_TYPE_1&project=958416&token=00000000000' -i -H 'Accept: application/json'
Example request
GET /rest/2.0/customerportal/workItems?uri=acme&cpId=1&offset=0&limit=10&sort=TRENDING&myWorkItems=false&followedItems=false&search=bug&type=TASK_TYPE_1&project=958416&token=00000000000 HTTP/1.1
Accept: application/json
Host: app.onedesk.com
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 3333
{
"code" : "SUCCESS",
"data" : {
"workItems" : [ {
"id" : 56142,
"organizationalId" : 128,
"name" : "Is this the right color for the button?",
"priority" : 60,
"type" : {
"name" : "TASK_TYPE_1",
"label" : "Task",
"iconClassName" : "task_icon_style",
"iconColor" : 15654
},
"description" : "The button on the right is red, shouldn't it be blue?",
"creationDate" : "2019-10-18T11:09:08:461+00:00",
"numberOfDiscussions" : 2,
"numberOfAttachments" : 1,
"status" : {
"id" : 5641,
"label" : "Open",
"iconColor" : 54651,
"default" : false
},
"attachments" : [ {
"fileId" : 514954,
"name" : "Blue bug.jpg",
"identityKey" : "k1",
"contentType" : "image/jpeg"
} ],
"isRequester" : true,
"followersCount" : 1,
"constraintType" : "ASAP",
"constraintDate" : "2019-10-18T11:09:08:462+00:00",
"plannedCost" : 1.0,
"plannedWork" : 2.0,
"plannedWorkUnit" : "MAN_DAYS",
"customFields" : { },
"projectId" : 1,
"projectName" : "Sample Project",
"percentComplete" : 33.0,
"actualWork" : 1.0,
"actualStart" : "2019-10-18T11:09:08:462+00:00",
"actualFinish" : "2019-10-18T11:09:08:462+00:00",
"actualCostAmount" : 0.0,
"edited" : "2019-10-18T11:09:08:462+00:00",
"latestClose" : "2019-10-18T11:09:08:462+00:00",
"latestInProgress" : "2019-10-18T11:09:08:462+00:00",
"author" : "user 1",
"assignmentsName" : [ ],
"requestersName" : [ ],
"sla" : "Test SLA",
"nextSLABreach" : "Closed",
"followed" : true,
"userSpecificFollower" : true
}, {
"id" : 5814926,
"organizationalId" : 128,
"name" : "There is a bug in the menu",
"priority" : 80,
"type" : {
"name" : "TASK_TYPE_1",
"label" : "Task",
"iconClassName" : "task_icon_style",
"iconColor" : 15654
},
"description" : "There is a bug in the menu, when I click on it, it doesn't open",
"creationDate" : "2019-10-18T11:09:08:462+00:00",
"numberOfDiscussions" : 2,
"numberOfAttachments" : 1,
"status" : {
"id" : 5641,
"label" : "Open",
"iconColor" : 54651,
"default" : false
},
"attachments" : [ {
"fileId" : 514954,
"name" : "Blue bug.jpg",
"identityKey" : "k1",
"contentType" : "image/jpeg"
} ],
"isRequester" : false,
"followersCount" : 5,
"constraintType" : "ASAP",
"constraintDate" : "2019-10-18T11:09:08:462+00:00",
"plannedCost" : 1.0,
"plannedWork" : 2.0,
"plannedWorkUnit" : "MAN_DAYS",
"customFields" : { },
"projectId" : 1,
"projectName" : "Sample Project",
"percentComplete" : 50.0,
"actualWork" : 1.0,
"actualStart" : "2019-10-18T11:09:08:462+00:00",
"actualFinish" : "2019-10-18T11:09:08:462+00:00",
"actualCostAmount" : 0.0,
"edited" : "2019-10-18T11:09:08:462+00:00",
"latestClose" : "2019-10-18T11:09:08:462+00:00",
"latestInProgress" : "2019-10-18T11:09:08:462+00:00",
"author" : "user 1",
"assignmentsName" : [ ],
"requestersName" : [ ],
"sla" : "Test SLA 2",
"nextSLABreach" : "1 day 2:30 late",
"followed" : false,
"userSpecificFollower" : false
} ],
"totalResults" : 2,
"typesToFilter" : [ ],
"projectsToFilter" : [ ],
"statusesToFilter" : { }
}
}
Get Work item
GET https://app.onedesk.com/rest/2.0/customerportal/workItems/{workItemId}
Path parameters
Parameter | Description |
---|---|
|
Id of the work item |
Request parameters
Parameter | Description |
---|---|
|
Authentication token |
|
customer portal ID |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
item id |
|
|
work item id in the organization |
|
|
work item name |
|
|
priority of the work item ([0,20,40,60,80,100] correspond to [0,1,2,3,4,5] stars respectively) |
|
|
project id |
|
|
project name |
|
|
description of the work item |
|
|
creation date of the work item |
|
|
number of followers of the work item |
|
|
true if the current user is following this work item |
|
|
true if the current user is following this work item (only with a user tag, not part of a team are all XXXXX) |
|
|
number of discussions in the work item |
|
|
number of attachments in the work item |
|
|
constraint type of the work item |
|
|
constraint date of the work item |
|
|
planned cost of the work item |
|
|
planned work of the work item |
|
|
planned work unit of the work item |
|
|
custom fields of the work item |
|
|
Id of the lifecycle status of the work item |
|
|
label of the lifecycle status of the work item |
|
|
status of the work item is default |
|
|
icon color of the lifecycle status of the work item |
|
|
true if the current user is the requester of the work item |
|
|
percent complete of the work item |
|
|
actual work of the work item |
|
|
actual start date of the work item |
|
|
actual finish date of the work item |
|
|
actual cost amount of the work item |
|
|
edited date of the work item |
|
|
latest close of the work item |
|
|
latest in progress of the work item |
|
|
author of the work item |
|
|
assignments names of the work item |
|
|
requesters names of the work item |
|
|
name of sla applied to the work item |
|
|
next sla breach of the work item |
|
|
item type name |
|
|
item type label |
|
|
item type icon style |
|
|
item type icon color |
|
|
id of the attachment |
|
|
key of the attachment |
|
|
name of the attachment |
|
|
content type of the attachment |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/customerportal/workItems/56142?token=00000000000&cpId=1' -i -H 'Accept: application/json'
Example request
GET /rest/2.0/customerportal/workItems/56142?token=00000000000&cpId=1 HTTP/1.1
Accept: application/json
Host: app.onedesk.com
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1504
{
"code" : "SUCCESS",
"data" : {
"id" : 56142,
"organizationalId" : 128,
"name" : "Is this the right color for the button?",
"priority" : 60,
"type" : {
"name" : "TASK_TYPE_1",
"label" : "Task",
"iconClassName" : "task_icon_style",
"iconColor" : 15654
},
"description" : "The button on the right is red, shouldn't it be blue?",
"creationDate" : "2019-10-18T11:09:08:868+00:00",
"numberOfDiscussions" : 2,
"numberOfAttachments" : 1,
"status" : {
"id" : 5641,
"label" : "Open",
"iconColor" : 54651,
"default" : false
},
"attachments" : [ {
"fileId" : 514954,
"name" : "Blue bug.jpg",
"identityKey" : "k1",
"contentType" : "image/jpeg"
} ],
"isRequester" : true,
"followersCount" : 1,
"constraintType" : "ASAP",
"constraintDate" : "2019-10-18T11:09:08:868+00:00",
"plannedCost" : 1.0,
"plannedWork" : 2.0,
"plannedWorkUnit" : "MAN_DAYS",
"customFields" : { },
"projectId" : 1,
"projectName" : "Sample Project",
"percentComplete" : 33.0,
"actualWork" : 1.0,
"actualStart" : "2019-10-18T11:09:08:868+00:00",
"actualFinish" : "2019-10-18T11:09:08:868+00:00",
"actualCostAmount" : 0.0,
"edited" : "2019-10-18T11:09:08:868+00:00",
"latestClose" : "2019-10-18T11:09:08:868+00:00",
"latestInProgress" : "2019-10-18T11:09:08:868+00:00",
"author" : "user 1",
"assignmentsName" : [ ],
"requestersName" : [ ],
"sla" : "Test SLA",
"nextSLABreach" : "Closed",
"followed" : true,
"userSpecificFollower" : true
}
}
Login
POST https://app.onedesk.com/rest/2.0/customerportal/login
You should either send the email, the password and the uri OR the cookie |
Request fields
Path | Type | Description |
---|---|---|
|
|
Email of the user |
|
|
password of the user |
|
|
Uri of the organization |
|
|
Remember the login by generating a cookie in the response |
|
|
Login cookie |
|
|
login token |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
user name |
|
|
Uri of the organization |
|
|
Authentication token |
|
|
Cookie to be used next time the user want to login |
|
|
User ID |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/customerportal/login' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"uri" : "acme",
"cookie" : "",
"token" : "",
"email" : "john.smith@acme.com",
"password" : "XXXXXXXXX",
"rememberMe" : true
}'
Example request
POST /rest/2.0/customerportal/login HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 139
{
"uri" : "acme",
"cookie" : "",
"token" : "",
"email" : "john.smith@acme.com",
"password" : "XXXXXXXXX",
"rememberMe" : true
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 204
{
"code" : "SUCCESS",
"data" : {
"name" : "John Smith",
"uri" : "acme",
"authenticationToken" : "00000000000",
"cookie" : "4b034b7a-9c3d-4a67-b2d9-a0c4dd2a134a",
"userId" : 1
}
}
Logout
POST https://app.onedesk.com/rest/2.0/customerportal/logout
Request fields
Path | Type | Description |
---|---|---|
|
|
Authentication token |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/customerportal/logout' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"token" : "00000000000"
}'
Example request
POST /rest/2.0/customerportal/logout HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 29
{
"token" : "00000000000"
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 41
{
"code" : "SUCCESS",
"data" : null
}
Registration
POST https://app.onedesk.com/rest/2.0/customerportal/register
Request fields
Path | Type | Description |
---|---|---|
|
|
user email address |
|
|
Organization uri |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
|
|
the url to redirect to in order ton confirm the registration |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/customerportal/register' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"uri" : "acme",
"email" : "john.smith@acme.com"
}'
Example request
POST /rest/2.0/customerportal/register HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 55
{
"uri" : "acme",
"email" : "john.smith@acme.com"
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 182
{
"code" : "SUCCESS",
"data" : {
"redirectionUrl" : "http://onedesk.com/html/confirmation?uuid=4b034b7a-9c3d-4a67-b2d9-a0c4dd2a134a",
"userId" : 1,
"error" : ""
}
}
Reset password
POST https://app.onedesk.com/rest/2.0/customerportal/resetPasswordRequest
Request fields
Path | Type | Description |
---|---|---|
|
|
user email address |
|
|
Organization uri |
Response fields
Path | Type | Description |
---|---|---|
|
|
the result of the API operation |
Example curl request
$ curl 'https://app.onedesk.com/rest/2.0/customerportal/resetPasswordRequest' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
"uri" : "acme",
"email" : "john.smith@acme.com"
}'
Example request
POST /rest/2.0/customerportal/resetPasswordRequest HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: app.onedesk.com
Content-Length: 55
{
"uri" : "acme",
"email" : "john.smith@acme.com"
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 41
{
"code" : "SUCCESS",
"data" : null
}
Error Handling
HTTP response status
Here are the supported HTTP response status
HTTP response status | Description |
---|---|
200 |
Success |
500 |
Internal server error |
401 |
Authentication error |
403 |
Security error |
Response codes
Every request to the API will return a response code. Here is a list of all possible code and their description.
code | Description |
---|---|
SUCCESS |
The request successfully executed |
ERROR_PORTAL_DISABLED |
Customer portal is disabled in the organization, you cannot use the customer portal API |
ERROR_CANNOT_FIND_ITEM |
Cannot find the specified item |
ERROR_CANNOT_FIND_USER |
cannot find the user |
ERROR_CANNOT_FIND_ORGANIZATION |
cannot find the organization |
ERROR_LOGIN_FAILED |
login failed |
ERROR_COOKIE_LOGIN_FAILED |
login with cookie failed |
ERROR_AUTHENTICATION_FROM_TOKEN_FAILED |
authentication with token failed |
ERROR_AUTHENTICATION_REQUIRED |
authentication required to execute the request |
ERROR_SECURITY_ACCESS |
security access error |
ERROR_ITEM_NOT_PUBLISHED |
Item not publish, so request cannot be executed |
ERROR_INVALID_PAGINATION |
invalid pagination |
ERROR_PAGINATION_NOT_SUPPORTED |
pagination not supported |
ERROR_INVALID_EMAIL |
invalid email |
ERROR_INVALID_FILTER |
invalid filter |
ERROR_INVALID_FILTERID |
invalid filter id |
ERROR_REGISTRATION_NOT_ALLOWED |
registration not allowed (contact the administrator of your organization) |
ERROR_REGISTRATION_CUSTOMER_ALREADY_EXIST |
customer with the same email already exist |
ERROR_SUBMIT_NAME_IS_REQUIRED |
name of the work item required |
ERROR_SUBMIT_DESCRIPTION_IS_REQUIRED |
description of the work item required |
ERROR_SUBMIT_TYPE_IS_REQUIRED |
type of the work item required |
ERROR_SUBMIT_TYPE_IS_WRONG |
Wrong type, this type is not allowed on the customer portal |
ERROR_SUBMIT_WRONG_PRIORITY |
wrong priority (must be between 0 and 100) |
ERROR_SUBMIT_PROJECT_NOT_FOUND |
Container not found |
ERROR_SUBMIT_PROJECT_NOT_PUBLISHED |
Container not published on the customer portal |
ERROR_SUBMIT_ANONYMOUS_MUST_PROVIDE_EMAIL |
email is required when submitting an anonymous work item |
ERROR_USER_ALREADY_EXIST |
user email already exist |
ERROR_CANNOT_FIND_PARENT_POST |
cannot find the parent post |
UNKNOWN_ERROR |
unknown error, please contact OneDesk with the details of you request |
INTERNAL_ERROR |
internal error, please contact OneDesk with the details of you request |
ERROR_CANNOT_FIND_CUSTOMER |
cannot find this customer |