Service Desk Developer Manual

Manages the Breaking News.

GET

/breakingnews

Returns the requested Breaking News.

Parameters

Name	Description	Type
date_format	Indicate the date format. The available formats are 'epoch' or 'iso8601'. If null, epoch format is returned.	`STRING`
id required	Breaking News ID.	`INTEGER`

Response

Name	Description	Type
affected_group_ids	Array with IDs of affected groups.	`ARRAY`
body	Breaking News body.	`TEXT`
affected_helpdesk_ids	Array with IDs of affected help desks.	`ARRAY`
created_by_id	Breaking News creator ID.	`INTEGER`
resolution_time	Resolution time in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
title	Breaking News title.	`STRING`
type_id	Breaking News type ID.	`INTEGER`
status_id	Breaking News status ID.	`INTEGER`
id	Breaking News ID.	`INTEGER`
created_at	Creation date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`

PUT

/breakingnews

Modifies a set of Breaking News.

Parameters

Name	Description	Type
affected_group_ids	Groups that are affected. It is required unless there is at least one help desk affected.	`ARRAY`
body	Breaking News body.	`TEXT`
affected_helpdesk_ids	Help desks that are affected. It is required unless there is at least one group affected.	`ARRAY`
status_id	Breaking News status ID.	`INTEGER`
title	Breaking News title.	`STRING`
type_id	Type ID of the breaking news based on importance. 1: High, 2: Medium, 3: Low.	`INTEGER`
creator_id	ID of the Breaking News' creator. If none is provided then it will be the system.	`INTEGER`
id required	Breaking News ID.	`INTEGER`
resolution_time	Estimated resolution time. Must be a timestamp (epoch format).	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the Breaking News was correctly modified; or 'ERROR' if something went wrong.	`STRING`
info	Description of the result.	`STRING`

POST

/breakingnews

Creates Breaking News.

Parameters

Name	Description	Type
affected_group_ids	Groups that are affected. It is required unless there is at least one help desk affected.	`ARRAY`
body required	Breaking News body.	`TEXT`
affected_helpdesk_ids	Help desks that are affected. It is required unless there is at least one group affected.	`ARRAY`
resolution_time	Estimated resolution time. Must be a timestamp (epoch format).	`INTEGER`
title required	Breaking News title.	`STRING`
type_id required	Type ID of the breaking news based on importance. 1: High, 2: Medium, 3: Low.	`INTEGER`
creator_id	ID of the Breaking News' creator. If none is provided then it will be the system.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the Breaking News was correctly created; or 'ERROR' if something went wrong.	`STRING`
id	ID of the Breaking News created.	`INTEGER`
info	Description of the result.	`STRING`

Lists the Breaking News.

GET

/breakingnews.all

Lists all the Breaking News.

Parameters

Name	Description	Type
date_format	Indicate the date format. The available formats are 'epoch' or 'iso8601'. If null, epoch format is returned.	`STRING`

Response

Returns an array of objects with the following structure:

Name	Description	Type
affected_group_ids	Array with IDs of affected groups.	`ARRAY`
body	Breaking News body.	`TEXT`
affected_helpdesk_ids	Array with IDs of affected help desks.	`ARRAY`
created_by_id	Breaking News creator ID.	`INTEGER`
resolution_time	Resolution time in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
title	Breaking News title.	`STRING`
type_id	Breaking News type ID.	`INTEGER`
status_id	Breaking News status ID.	`INTEGER`
id	Breaking News ID.	`INTEGER`
created_at	Creation date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`

Lists the status of the Breaking News.

GET

/breakingnews.attributes.status

Lists all the possible status for the Breaking News' and their descriptions. If an ID is provided, only one will be listed.

Parameters

Name	Description	Type
id	Status ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
name	Status name.	`STRING`
id	Status ID.	`INTEGER`

Lists all the Breaking News importance types.

GET

/breakingnews.attributes.type

Lists all the importance types of the Breaking News. If an ID its provided, only one will be listed.

Parameters

Name	Description	Type
id	Importance type ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
name	Importance type name.	`STRING`
id	Importance type ID.	`INTEGER`

Manages the updates of the Breaking News.

GET

/breakingnews.status

Returns the updates of the requested Breaking News.

Parameters

Name	Description	Type
date_format	Indicate the date format. The available formats are 'epoch' or 'iso8601'. If null, epoch format is returned.	`STRING`
id required	Breaking News ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
body	Body of the update.	`TEXT`
created_at	Creation date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
creator_id	Breaking News creator ID.	`INTEGER`

POST

/breakingnews.status

Creates a new update to the given Breaking News.

Parameters

Name	Description	Type
body required	Breaking News body.	`TEXT`
creator_id	ID of the Breaking News' creator. If none is provided then it will be the system.	`INTEGER`
id required	Breaking News ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the Breaking News update was correctly created; or 'ERROR' if something went wrong.	`STRING`
info	Description of the result.	`STRING`

Lists all the categories.

GET

/categories

Lists all the categories, or the required one if an ID is provided.

Parameters

Name	Description	Type
id	Category ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
name	Category name.	`STRING`
id	Category ID.	`INTEGER`
parent_category_id	Category parent ID.	`INTEGER`

Manages the settings of the list type custom fields.

GET

/cf.field.options.list

Lists the configuration of custom fields that are a list type.

Parameters

Name	Description	Type
uid required	Custom field ID.	`INTEGER`

Response

Name	Description	Type
key-value	Returns an array with the key-values dictionary of the custom field.	`ARRAY`

DELETE

/cf.field.options.list

Erases keys from the list type custom fields configuration.

Parameters

Name	Description	Type
uid required	Custom field ID.	`INTEGER`
keys required	Array [key1,key2] of keys to be erased.	`ARRAY`
type required	Type of configuration to change. Types: key-value.	`STRING`

Response

Name	Description	Type
status	Returns 'OK' if the custom field option was correctly deleted; or 'ERROR' if something went wrong.	`STRING`
total	Number of deleted values.	`INTEGER`
info	Description of the result.	`STRING`

POST

/cf.field.options.list

Configures list type custom fields. If the key already exists, the previous value will be overwritten.

Parameters

Name	Description	Type
uid required	Custom field ID.	`INTEGER`
key_values required	Dictionary {key1: value1, key2: value2, ...} with key-values pairs to be added to the CF list.	`ARRAY`
type required	Type of configuration to change. Types: key-value.	`STRING`

Response

Name	Description	Type
status	Returns 'OK' if the custom field option was correctly added or modified; or 'ERROR' if something went wrong.	`STRING`
total	Number of modified/added values.	`INTEGER`
info	Description of the result.	`STRING`

Manages the settings of the tree type custom fields.

GET

/cf.field.options.tree

Returns the structure of the tree type custom fields options. The hash is system internal, but it is used to make modifications.

Parameters

Name	Description	Type
uid required	Custom field ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
key	Key defined by the user for the option.	`STRING`
name	Option name.	`STRING`
hash	The unique internal identifier of the option.	`STRING`
children	Array of the option's children.	`ARRAY`

PUT

/cf.field.options.tree

Modifies the configuration of the tree type custom fields. If there is no such key, it will be added.

Parameters

Name	Description	Type
uid required	Custom field ID.	`INTEGER`
key	Key defined by the user; if no value is set the previous value will be used.	`STRING`
name	Name of the option, value that the user sees when selecting.	`STRING`
hash required	Hash value of the item to modify.	`STRING`

Response

Name	Description	Type
status	Returns 'OK' if the custom field option was correctly modified; or 'ERROR' if something went wrong.	`STRING`
info	Description of the result.	`STRING`

DELETE

/cf.field.options.tree

Erases the options from the tree type custom fields and any of its children.

Parameters

Name	Description	Type
uid required	Custom field ID.	`INTEGER`
hash required	Hash value of the item to modify.	`STRING`

Response

Name	Description	Type
status	Returns 'OK' if the custom field option was correctly deleted; or 'ERROR' if something went wrong.	`STRING`
info	Description of the result.	`STRING`

POST

/cf.field.options.tree

Adds configuration to the tree type custom fields. If the key already exists, the previous value will be overwritten.

Parameters

Name	Description	Type
uid required	Custom field ID.	`INTEGER`
key	Key defined by the user; if no value is set, the hash will be used as key.	`STRING`
name required	Name of the option, value that the user sees when selecting.	`STRING`
parent_hash	Hash value of the parent; if not set, it will be added to the root.	`STRING`

Response

Name	Description	Type
status	Returns 'OK' if the custom field option was correctly added; or 'ERROR' if something went wrong.	`STRING`
info	Description of the result.	`STRING`

Lists the active custom fields.

GET

/cf.fields.all

Returns a list of all the active custom fields.

Response

Returns an array of objects with the following structure:

Name	Description	Type
description	Custom field description.	`TEXT`
label	Custom field name.	`STRING`
categories	Categories where custom field applies.	`STRING`
uid	Custom field ID.	`INTEGER`
type	Custom field type ID.	`INTEGER`
is_required	Indicates if the custom field is required. True if it's required and false if it's not.	`BOOLEAN`

Custom fields by category.

GET

/cf.fields.by.category

Returns a list of the custom fields related to a category ID.

Parameters

Name	Description	Type
category_id required	Category ID.	`INTEGER`

Response

Returns an array with the IDs of the custom fields that apply to the category received as a parameter.

Name	Description	Type
uid	Custom field ID.	`INTEGER`

Lists all the supported custom field types.

GET

/cf.fields.types

Returns a list of all the supported custom field types, with a brief description of the data type for each field.

Response

Returns an array with the following structure:

Name	Description	Type
name	Custom field type name.	`STRING`
id	Custom field type ID.	`INTEGER`

Manages configuration items from custom fields and shared custom fields by IDs.

GET

/cis.by.id

Returns an array of CIs, linked through custom fields and shared custom fields, with their IDs and properties.

Parameters

Name	Description	Type
ci_internal_ids required	Configuration items IDs from Service Desk.	`ARRAY`
ci_source_id	ID of the ITAM tool integration in Service Desk.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
ci_name	Configuration item name.	`STRING`
ci_external_id	Configuration item external source ID.	`INTEGER`
ci_internal_id	Configuration item ID from Service Desk.	`INTEGER`

Manages companies.

GET

/companies

Returns all the active companies.

Parameters

Name	Description	Type
name	Company name.	`STRING`
id	Company ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
total	Users total.	`INTEGER`
name	Company name.	`STRING`
id	Company ID.	`INTEGER`

DELETE

/companies

Erases an existing company.

Parameters

Name	Description	Type
id required	Company ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the object was correctly deleted; or 'ERROR' if something went wrong.	`STRING`

POST

/companies

Creates a new company.

Parameters

Name	Description	Type
name required	Company name.	`STRING`

Response

Name	Description	Type
id	ID of the created object.	`INTEGER`

Manages the relationships between users groups and companies.

GET

/companies.groups

Lists all the users groups related to a company.

Parameters

Name	Description	Type
id required	Company ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
total	Users total.	`INTEGER`
name	Name of the related group.	`STRING`
id	ID of the related group.	`INTEGER`

DELETE

/companies.groups

Suppresses the relationship between a users group and a company.

Parameters

Name	Description	Type
groups required	Groups IDs.	`ARRAY`
unlink_users_too	When is set to true, it breaks the relation between the company users and the group.	`BOOLEAN`
id required	Company ID.	`INTEGER`

Response

Returns an array of groups IDs as keys and TRUE as values of the deleted relations.

Name	Description	Type
id	Group ID.	`ARRAY`

POST

/companies.groups

Relates a users group to a company.

Parameters

Name	Description	Type
groups required	Groups IDs.	`ARRAY`
id required	Company ID.	`INTEGER`

Response

Returns an array of groups IDs as keys and TRUE as values of the created relations.

Name	Description	Type
id	Group ID.	`ARRAY`

Manages companies observers.

GET

/companies.observers

Returns all active companies and their observers, or the observers for the specified companies.

Parameters

Name	Description	Type
ids	Company IDs.	`ARRAY`

Response

Returns an array of objects with the following structure:

Name	Description	Type
observer_users	The observers’ users IDs.	`ARRAY`
name	Company name.	`STRING`
id	Company ID.	`INTEGER`
observer_groups	The groups’ IDs that are observers of the entity.	`ARRAY`

DELETE

/companies.observers

Removes observers from a company.

Parameters

Name	Description	Type
observer_users required	Users IDs to be removed as observers.	`ARRAY`
id required	Company ID.	`INTEGER`

Response

Name	Description	Type
value	Returns 'true' if the users were correctly removed as observers from the company. Returns 'false' if, for any reason, they weren't removed from the company, or if the users weren't observers of the company.	`BOOLEAN`
id	User ID.	`INTEGER`

POST

/companies.observers

Add users as observers to a company.

Parameters

Name	Description	Type
observer_users required	Users IDs to be added as observers.	`ARRAY`
id required	Company ID.	`INTEGER`

Response

Name	Description	Type
value	Returns 'true' if the users were correctly added as observers to the company. Returns 'false' if, for any reason, they weren't added to the company, or if the users were already observers of the company.	`BOOLEAN`
id	User ID.	`INTEGER`

Manages the relationships between users and companies.

GET

/companies.users

Lists the members of a company.

Parameters

Name	Description	Type
id required	Company ID.	`INTEGER`
user_id	User ID	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
username	Username.	`STRING`
name	User full name.	`STRING`
id	User ID.	`INTEGER`
email	User email.	`STRING`

DELETE

/companies.users

Removes a user from a company. If the user is within a group that belongs to that company, they will also be removed from that group.

Parameters

Name	Description	Type
users required	Users IDs.	`ARRAY`
id required	Company ID.	`INTEGER`

Response

Returns an array of users IDs as keys and TRUE as values of the deleted relations.

Name	Description	Type
id	User ID.	`ARRAY`

POST

/companies.users

Adds a user to a company. If the company contains groups, the users will also be added to those groups.

Parameters

Name	Description	Type
users required	Users IDs.	`ARRAY`
id required	Company ID.	`INTEGER`

Response

Returns an array of users IDs as keys and TRUE as values of the created relations.

Name	Description	Type
id	User ID.	`ARRAY`

Manages groups.

GET

/groups

Returns all active groups of users, or one in particular if an ID or name is provided.

Parameters

Name	Description	Type
name	Group name.	`STRING`
id	Group ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
total	Users total.	`INTEGER`
name	Group name.	`STRING`
id	Group ID.	`INTEGER`

DELETE

/groups

Erases a group of users.

Parameters

Name	Description	Type
id required	Group ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the object was correctly deleted; or 'ERROR' if something went wrong.	`STRING`

POST

/groups

Creates a group of users.

Parameters

Name	Description	Type
name required	Group name.	`STRING`

Response

Name	Description	Type
id	ID of the created object.	`INTEGER`

Manages groups observers.

GET

/groups.observers

Returns all active groups and their observers, or the observers for the specified groups.

Parameters

Name	Description	Type
ids	Group IDs.	`ARRAY`

Response

Returns an array of objects with the following structure:

Name	Description	Type
observer_users	The observers’ users IDs.	`ARRAY`
name	Group name.	`STRING`
id	Group ID.	`INTEGER`
observer_groups	The groups’ IDs that are observers of the entity.	`ARRAY`

DELETE

/groups.observers

Removes observers from a group.

Parameters

Name	Description	Type
observer_users required	Users IDs to be removed as observers.	`ARRAY`
id required	Group ID.	`INTEGER`

Response

Name	Description	Type
value	Returns 'true' if the users were correctly removed as observers from the group. Returns 'false' if, for any reason, they weren't removed from the group, or if the users weren't observers of the group.	`BOOLEAN`
id	User ID.	`INTEGER`

POST

/groups.observers

Add users as observers to a group.

Parameters

Name	Description	Type
observer_users required	Users IDs to be added as observers.	`ARRAY`
id required	Group ID.	`INTEGER`

Response

Name	Description	Type
value	Returns 'true' if the users were correctly added as observers to the group. Returns 'false' if, for any reason, they weren't added to the group, or if the users were already observers of the group.	`BOOLEAN`
id	User ID.	`INTEGER`

Manages the relationships between users and groups.

GET

/groups.users

Lists the members of a group.

Parameters

Name	Description	Type
id required	Group ID.	`INTEGER`
user_id	User ID	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
username	Username.	`STRING`
name	User full name.	`STRING`
id	User ID.	`INTEGER`
email	User email.	`STRING`

DELETE

/groups.users

Removes a user from a group.

Parameters

Name	Description	Type
users required	Users IDs.	`ARRAY`
id required	Group ID.	`INTEGER`

Response

Returns an array of users IDs as keys and TRUE as values of the deleted relations.

Name	Description	Type
id	User ID.	`ARRAY`

POST

/groups.users

Adds a user to a group.

Parameters

Name	Description	Type
users required	Users IDs.	`ARRAY`
id required	Group ID.	`INTEGER`

Response

Returns an array of users IDs as keys and TRUE as values of the created relations.

Name	Description	Type
id	User ID.	`ARRAY`

Manages the help desks.

GET

/helpdesks

Returns all the active help desks, or one in particular.

Parameters

Name	Description	Type
name	Help desk name.	`STRING`
id	Help desk ID.	`INTEGER`
include_deleted	True if deleted help desks should be included.	`BOOLEAN`

Response

Returns an array of objects with the following structure:

Name	Description	Type
total_members	Total of members.	`INTEGER`
parent_id	Help desk parent ID.	`INTEGER`
name	Help desk name.	`STRING`
status_id	Help desk status ID.	`INTEGER`
engine_id	Help desk engine ID.	`INTEGER`
id	Help desk ID.	`INTEGER`

Manages help desks observers.

GET

/helpdesks.observers

Returns all active help desks and their observers, or the observers for the specified help desks.

Parameters

Name	Description	Type
ids	Help Desk IDs.	`ARRAY`

Response

Returns an array of objects with the following structure:

Name	Description	Type
observer_users	The observers’ users IDs.	`ARRAY`
name	Help Desk name.	`STRING`
id	Help Desk ID.	`INTEGER`
observer_groups	The groups’ IDs that are observers of the entity.	`ARRAY`

DELETE

/helpdesks.observers

Removes observers from a help desk.

Parameters

Name	Description	Type
observer_users required	Users IDs to be removed as observers.	`ARRAY`
id required	Help Desk ID.	`INTEGER`

Response

Name	Description	Type
value	Returns 'true' if the users were correctly removed as observers from the help desk. Returns 'false' if, for any reason, they weren't removed from the help desk, or if the users weren't observers of the help desk.	`BOOLEAN`
id	User ID.	`INTEGER`

POST

/helpdesks.observers

Add users as observers to a help desk.

Parameters

Name	Description	Type
observer_users required	Users IDs to be added as observers.	`ARRAY`
id required	Help Desk ID.	`INTEGER`

Response

Name	Description	Type
value	Returns 'true' if the users were correctly added as observers to the help desk. Returns 'false' if, for any reason, they weren't added to the help desk, or if the users were already observers of the help desk.	`BOOLEAN`
id	User ID.	`INTEGER`

Manages help desks and levels.

GET

/helpdesksandlevels

Returns all the help desks and levels, or one in particular.

Parameters

Name	Description	Type
id	Level ID.	`INTEGER`
include_deleted	True if deleted help desks and levels should be included.	`BOOLEAN`

Response

Returns an array of objects with the following structure:

Name	Description	Type
total_members	Total of members.	`INTEGER`
level_order	If it's a level, indicates the order.	`INTEGER`
parent_id	Parent ID.	`INTEGER`
status_id	Status ID. 1: Enabled, 2: Suspend, 3: Out time work, 4: Disabled.	`INTEGER`
name	If it is a help desk, indicates the name.	`STRING`
members_ids	Members IDs.	`ARRAY`
engine_id	Engine ID. 1: Round robin, 2: By load, 3: Free, 4: Manual.	`INTEGER`
id	Level ID.	`INTEGER`

Manages a request.

GET

/incident

Returns the information of the given request.

Parameters

Name	Description	Type
comments	When set to true, it includes the comments of the request.	`BOOLEAN`
decoded_special_characters	Indicate if the message is returned decoded. If null, coded format is returned.	`BOOLEAN`
date_format	Indicate the date format. The available formats are 'epoch' or 'iso8601'. If null, epoch format is returned.	`STRING`
id required	Request ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
pretty_id	Request pretty ID as configured on the Service Desk instance.	`STRING`
process_id	Process ID of the request if it is a workflow instance.	`INTEGER`
attachments	Array with the IDs of the attachments.	`ARRAY`
assigned_group_id	Help desk ID.	`INTEGER`
category_id	Category ID.	`INTEGER`
rating	Stars given to the solution. If there's no rating, this field won't be shown.	`INTEGER`
date_ocurred	Occurrence date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
solved_at	Solution date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
sla_incident_first_reply	First response SLA of the request.	`STRING`
status_id	Status ID.	`INTEGER`
type_id	Type ID.	`INTEGER`
priority_id	Priority ID.	`INTEGER`
id	Request ID.	`INTEGER`
custom_fields	Array with the custom fields ids as keys and the respective values.	`ARRAY`
assigned_id	Assigned agent ID.	`INTEGER`
created_at	Creation date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
title	Request title.	`STRING`
closed_at	Closing date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
description	Request description.	`STRING`
last_update	Last update in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
comments	Array with comments of the requests with the comment structure.	`ARRAY`
sla_incident_resolution	Resolution SLA of the request.	`STRING`
creator_id	Creator ID.	`INTEGER`
source_id	Source ID.	`INTEGER`
closed_reason	Reason of closing. 1: Solution accepted, 2: Solution expired, 3: Customer timeout, 4: Finalized workflow.	`STRING`
user_id	Customer ID.	`INTEGER`

PUT

/incident

Change attributes of a request.

Parameters

Name	Description	Type
date_format	Indicate the date format. The available formats are 'epoch' or 'iso8601'. If null, epoch format is returned.	`STRING`
title	Request title.	`STRING`
date	Occurred on timestamp.	`STRING`
description	Request description.	`TEXT`
reassignment	Set to true to reassign the request to a help desk according to the new properties.	`BOOLEAN`
category_id	Category ID.	`INTEGER`
customer_id	Client ID.	`INTEGER`
location_id	Location ID.	`INTEGER`
type_id	Type ID.	`INTEGER`
source_id	Source ID.	`INTEGER`
priority_id	Priority ID.	`INTEGER`
id required	Request ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
process_id	Process ID of the request if it is a workflow instance.	`INTEGER`
location_id	Location ID.	`INTEGER`
attachments	Array with the IDs of the attachments.	`ARRAY`
assigned_group_id	Help desk ID.	`INTEGER`
category_id	Category ID.	`INTEGER`
date_ocurred	Occurrence date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
solved_at	Solution date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
status_id	Status ID.	`INTEGER`
type_id	Type ID.	`INTEGER`
priority_id	Priority ID.	`INTEGER`
id	Request ID.	`INTEGER`
custom_fields	Array with the custom fields IDs as keys and the respective values.	`ARRAY`
assigned_id	Assigned agent ID.	`INTEGER`
created_at	Creation date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
title	Request title.	`STRING`
closed_at	Closing date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
description	Request description.	`STRING`
last_update	Last update in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
creator_id	Creator ID.	`INTEGER`
source_id	Source ID.	`INTEGER`
closed_reason	Reason of closing. 1: Solution accepted, 2: Solution expired, 3: Customer timeout, 4: Finalized workflow	`STRING`
user_id	Customer ID.	`INTEGER`

POST

/incident

Creates a request.

Parameters

Name	Description	Type
title required	Request title.	`STRING`
date	Occurred on timestamp in epoch format.	`STRING`
description	Request description. Required for requests and Workflows with descriptions.	`TEXT`
location_id	Location ID.	`INTEGER`
attachments	Array of request's attachments.	`ARRAY`
category_id required	Category ID.	`INTEGER`
related_to	Requests IDs to link.	`ARRAY`
customer_id required	Client ID.	`INTEGER`
creator_id required	Creator ID.	`INTEGER`
type_id required	Type ID.	`INTEGER`
priority_id required	Priority ID.	`INTEGER`
source_id	Source ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the request was correctly created; or 'ERROR' if something went wrong.	`STRING`
request_id	ID of the created request.	`INTEGER`
info	Description of the result.	`STRING`

Manages the approvals instances of a request.

GET

/incident.approval

Lists the approvals instances that the given request has.

Parameters

Name	Description	Type
only_pending	When set to true, it only returns pending approvals.	`BOOLEAN`
date_format	Indicate the date format. The available formats are 'epoch' or 'iso8601'. If null, epoch format is returned.	`STRING`
request_id required	Request ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
status	Status ID of the approval. -2: Cancelled, -1: Waiting, 0: Rejected, 1: Approved.	`INTEGER`
approval_request_description	Description of the approval.	`TEXT`
created_at	Date when the approval was triggered, in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
type	Type ID of the approval. 1: Predefined approval, 2: Spontaneous approval.	`INTEGER`
author_id	Author ID of the approval.	`INTEGER`
approval_request_id	ID of the approval template.	`INTEGER`
id	ID of the approval instance.	`INTEGER`

Manages the acceptance of an approval.

PUT

/incident.approval.accept

Accepts an approval.

Parameters

Name	Description	Type
approval_id required	Approval ID to be accepted.	`INTEGER`
user_id required	ID of the user who will accept the approval.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the approval was correctly accepted.	`STRING`

Manages the voters of an approval.

POST

/incident.approval.add_voter

Adds a voter to an approval.

Parameters

Name	Description	Type
approval_id required	ID of the approval instance.	`INTEGER`
user_id required	Author ID of the approval.	`INTEGER`

Response

Name	Description	Type
approval_id	ID of the approval instance.	`INTEGER`
user_id	Author ID of the approval.	`INTEGER`

Manages the cancellation of an approval.

PUT

/incident.approval.cancel

Cancels an approval.

Parameters

Name	Description	Type
approval_id required	Approval ID to be cancelled.	`INTEGER`
user_id required	ID of the user who will cancel the approval.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the approval was correctly canceled; or 'ERROR' if something went wrong.	`STRING`

Manages the users that could accept or reject the approval.

GET

/incident.approval.possible_voters

Lists users that could accept or reject the approval.

Parameters

Name	Description	Type
only_pending	When set to true, it only returns voters who have not voted.	`BOOLEAN`
approval_id required	Approval ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
status	Approval status ID. -2: Annulled, -1: Waiting, 0: Rejected, 1: Approved, 2:Expired.	`INTEGER`
id	User ID.	`INTEGER`

Manages the rejection of an approval.

PUT

/incident.approval.reject

Rejects an approval.

Parameters

Name	Description	Type
approval_id required	Approval ID to be rejected.	`INTEGER`
user_id required	ID of the user will reject the approval.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the approval was correctly rejected; or 'ERROR' if something went wrong.	`STRING`

Lists the statuses of the approvals.

GET

/incident.approval.status

Lists the statuses of the approvals.

Response

Returns an array with status ID as keys and status description as values.

Name	Description	Type
id	Status ID and description.	`ARRAY`

Lists the available approvals types.

GET

/incident.approval.type

Lists the available approvals types.

Response

Returns an array with type id as keys and type description as values.

Name	Description	Type
id	Type ID and description.	`ARRAY`

Lists the status of the approval votes.

GET

/incident.approval.vote_status

Lists the status of the approval votes.

Response

Returns an array with status id as keys and status description as values.

Name	Description	Type
id	Status ID and description.	`ARRAY`

Manages the attachments of the requests.

GET

/incident.attachment

Returns the requested attachment.

Parameters

Name	Description	Type
id required	Attachment ID.	`INTEGER`

Response

Name	Description	Type
url	URL of the attached file.	`STRING`
extension	Extension of the attached file.	`STRING`
name	Name of the attached file.	`STRING`
id	ID of the attached file.	`INTEGER`
hash	Hash of the attached file.	`STRING`

Lists all the priorities.

GET

/incident.attributes.priority

Lists all the priorities, or only one if an ID its provided.

Parameters

Name	Description	Type
id	Priority ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
name	Priority name.	`STRING`
id	Priority ID.	`INTEGER`

Lists all the requests sources.

GET

/incident.attributes.source

Lists all the sources. If an ID is provided, only the one that matches the specified ID will be listed.

Parameters

Name	Description	Type
id	Source ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
name	Source name.	`STRING`
id	Source ID.	`INTEGER`

Lists all the status.

GET

/incident.attributes.status

Lists all the status. If an ID is provided, only the one that matches the specified ID will be listed.

Parameters

Name	Description	Type
id	Status ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
name	Status name.	`STRING`
id	Status ID.	`INTEGER`

Lists all the types.

GET

/incident.attributes.type

Lists all the types. If an ID is provided, only the one that matches the specified ID will be listed.

Parameters

Name	Description	Type
id	Type ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
name	Type name.	`STRING`
id	Type ID.	`INTEGER`

Manages the collaborators of the requests.

GET

/incident.collaborator

Lists the collaborators IDs.

Parameters

Name	Description	Type
request_id required	Request ID.	`INTEGER`

POST

/incident.collaborator

Requests collaboration from the defined user.

Parameters

Name	Description	Type
author_id required	Author ID. Must be the ID of the user that asks for collaboration.	`INTEGER`
user_id	User ID.	`INTEGER`
users_id	Users IDs.	`ARRAY`
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the collaboration was correctly requested; or 'ERROR' if something went wrong.	`STRING`

Manages the replies from a given request.

GET

/incident.comment

Gets the replies from a given request.

Parameters

Name	Description	Type
decoded_special_characters	Indicate if the message is returned decoded. If null, coded format is returned.	`BOOLEAN`
is_solution	Indicate if the comments returned are the request's solution. 1: Is solution, 0: Is not solution. If this parameter is not provided then all comments will be returned.	`BOOLEAN`
date_format	Indicate the date format. The available formats are 'epoch' or 'iso8601'. If null, epoch format is returned.	`STRING`
request_id required	Request ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
incident_id	Request ID.	`INTEGER`
customer_visible	Indicates if the comment is internal or not. 0: Internal, 1: Public.	`BOOLEAN`
attachments	Attachment IDs.	`ARRAY`
id	Comment ID.	`INTEGER`
is_solution	Indicates if this comment is the solution of the request. 1: if is the solution, 0: if not.	`BOOLEAN`
msg_num	Number of the message in the request.	`INTEGER`
author_id	Author ID.	`INTEGER`
reference	ID of the comment that is replying to.	`INTEGER`
message	Message of the comment.	`STRING`
created_at	Creation time in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`

POST

/incident.comment

Adds a reply to a request.

Parameters

Name	Description	Type
customer_visible	Mark as internal. 0: Internal, 1: Public.	`BOOLEAN`
comment required	Comment to be added.	`TEXT`
is_solution	Mark as solution. 1: Is solution, 0: Is not solution.	`BOOLEAN`
author_id required	Author ID.	`INTEGER`
attachments	Attachments IDs.	`ARRAY`
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the comment was correctly added; or 'ERROR' if something went wrong.	`STRING`

Manages the custom approvals.

GET

/incident.custom_approval

Lists the custom approvals templates that the given request has.

Parameters

Name	Description	Type
date_format	Indicate the date format. The available formats are 'epoch' or 'iso8601'. If null, epoch format is returned.	`STRING`
request_id required	Request ID.	`INTEGER`

Response

Returns an array of the approval templates that a request has, using the approval ID as key and values with the following structure:

Name	Description	Type
description_prompt	Template description.	`STRING`
created_at	Creation time in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
description_required	Indicates if the description is required or not. 0: Required, 1: Not required.	`BOOLEAN`
expired_in	Expiration time in seconds.	`STRING`
status	Approval status ID. 1: Active, -1: Deleted.	`INTEGER`
description	Approval description.	`STRING`
wf_process_id	ID of the associated workflow.	`INTEGER`
expired_approved	Indicates the action when the approval expires. 1: Approve, 2: Reject.	`INTEGER`
pause_sla	Indicates if the approval pauses the SLA. 1: Pause, 0: Do not pause.	`BOOLEAN`
wf_item_id	ID of the phase of the associated workflow.	`INTEGER`
id	Approval template ID.	`INTEGER`
title	Approval title.	`STRING`

POST

/incident.custom_approval

Requests a custom approval in the given request.

Parameters

Name	Description	Type
author_id required	Author ID of the approval request.	`INTEGER`
description	Custom approval description.	`TEXT`
approval_id required	Custom approval ID.	`INTEGER`
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the approval was correctly requested; or 'ERROR' if something went wrong.	`STRING`

Manages the custom fields from a request.

DELETE

/incident.custom_field

Deletes value in the associated custom field.

Parameters

Name	Description	Type
author_id required	Author ID.	`INTEGER`
custom_field_uid required	Custom field UID.	`INTEGER`
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the values were correctly created; or 'ERROR' if something went wrong.	`STRING`
info	Deletes value in the associated custom field.	`STRING`

PATCH

/incident.custom_field

Add values for a multiple custom field from a request. This only works for the custom field with type CI. It can only be sent one CI name at a time in the values variable. It must be the complete name of the CI and all the CIs that have that exact name will be added to the multiple custom field.

POST

/incident.custom_field

Creates values for a custom field from a request. Different types of data can be sent in the values variable. No value (empty string) means erase value. When sending files, the name of the file has to be in the values array (including its extension), and the file(s) itself should be sent in the body of the request.

Parameters

Name	Description	Type
author_id required	Author ID.	`INTEGER`
custom_field_uid required	Custom field UID.	`INTEGER`
values required	Array of values. If only one is required, only the first will be processed. If you are sending files, here you should list the names (with extension) of the files.	`ARRAY`
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the values were correctly created; or 'ERROR' if something went wrong.	`STRING`
info	Description of the result.	`STRING`

Manages the external entities linked to a request.

GET

/incident.external_entity

Lists all the external entities linked to a request.

Parameters

Name	Description	Type
request_id required	Request ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
link_id	Relation ID.	`INTEGER`
ext_ref_id	External entity reference ID.	`INTEGER`
name	External entity name.	`STRING`
type	Entity type. Always 100.	`STRING`
ref_id	External entity ID.	`INTEGER`
status	Entity status. 1: Enabled, 0: Deleted.	`BOOLEAN`

POST

/incident.external_entity

Links a request to an external entity.

Parameters

Name	Description	Type
external_entity_id required	External entity ID.	`INTEGER`
external_entity_ref_id	External entity reference ID.	`STRING`
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the external entity was correctly linked; or 'ERROR' if something went wrong.	`STRING`
link_id	ID of the created relation.	`STRING`
info	Description of the result.	`STRING`

Manages the requests linked to a request.

GET

/incident.link

Lists all the linked requests from a given request.

Parameters

Name	Description	Type
request_id required	Request ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
title	Related request title.	`STRING`
id	Related request ID.	`INTEGER`

POST

/incident.link

Links a request to another request.

Parameters

Name	Description	Type
request_ids required	Request IDs to link.	`ARRAY`
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the request was correctly linked; or 'ERROR' if something went wrong.	`STRING`
info	Description of the result.	`STRING`

Manages the linked assets counters.

GET

/incident.linked_cis.counters.from

Returns counters with the number of incidents of each status.

Parameters

Name	Description	Type
cis_source_id required	ID of the ITAM tool integration in Service Desk.	`INTEGER`
from required	Date timestamp from which the counters are picked.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
ci_id	ID of the CI.	`INTEGER`
requests	An object that contains two arrays: one counting linked CIs by request status and the other counting linked CIs by request type (only for open requests).	`ARRAY`
group	Name of the group for this CI.	`STRING`

Manages the request's observers.

GET

/incident.observer

Lists all the IDs of the request's observers.

Parameters

Name	Description	Type
request_id required	Request ID.	`INTEGER`

Response

Returns an array with the IDs of the observers.

Name	Description	Type
user_id	User ID.	`INTEGER`

POST

/incident.observer

Adds a user as observer.

Parameters

Name	Description	Type
author_id required	Author ID.	`INTEGER`
user_id	User ID.	`INTEGER`
users_id	Users IDs.	`ARRAY`
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the observer was correctly added; or 'ERROR' if something went wrong.	`STRING`

Manages the requests reassignations to a help desk or agent.

POST

/incident.reassign

Reassigns a request to a help desk and/or agent.

Parameters

Name	Description	Type
author_id required	Author ID.	`INTEGER`
agent_id	Agent ID.	`INTEGER`
group_id required	Help desk ID.	`INTEGER`
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the help desk or group was correctly reassigned; or 'ERROR' if something went wrong.	`STRING`

Manages the rejection of a request.

POST

/incident.reject

Rejects a request.

Parameters

Name	Description	Type
author_id required	ID of the user rejecting the request.	`INTEGER`
request_id required	ID of the request to reject.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the request was correctly rejected; or 'ERROR' if something went wrong.	`STRING`

Relates a request to every CI that matches a certain keyword.

POST

/incident.relate.ci.by.keyword

Relates a request to every CI that matches a certain keyword.

Parameters

Name	Description	Type
exact_match	Indicates if the results must be an exact match or not.	`BOOLEAN`
keyword required	Keyword to search CIs.	`STRING`
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the CIs were correctly related; or 'ERROR' if something went wrong.	`STRING`
info	Description of the result.	`STRING`

Manages a request reopening.

PUT

/incident.reopen

Reopens a request.

Parameters

Name	Description	Type
author_id	User ID who reopened the ticket.	`INTEGER`
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the request was correctly reopened; or 'ERROR' if something went wrong.	`STRING`

Manages the acceptance of a request's solution.

PUT

/incident.solution.accept

Accepts the solution of a request.

Parameters

Name	Description	Type
comment	Solution comment. This parameter is required if the rating is less than 4.	`STRING`
id required	Request ID.	`INTEGER`
rating required	Request rating. Rate the solution on a scale of 1-5, 1 being the lowest and 5 being the highest.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the solution was correctly accepted; or 'ERROR' if something went wrong.	`STRING`

Manages the rejection of a request's solution.

PUT

/incident.solution.reject

Rejects the solution of a request.

Parameters

Name	Description	Type
comment required	Rejection reason.	`STRING`
id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the solution was correctly rejected; or 'ERROR' if something went wrong.	`STRING`

Manages the spontaneous approvals from a request.

POST

/incident.spontaneous_approval

Creates a spontaneous approval.

Parameters

Name	Description	Type
author_id required	Author ID.	`INTEGER`
description required	Approval description.	`TEXT`
approval_user_id required	User ID from the approval voter.	`INTEGER`
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the approval was correctly created; or 'ERROR' if something went wrong.	`STRING`

Manages the agent waiting status of the requests.

POST

/incident.waitingfor.agent

Sets the agent waiting status to the request.

Parameters

Name	Description	Type
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the waiting status was correctly set; or 'ERROR' if something went wrong.	`STRING`
info	Description of the result.	`STRING`

Manages the customer waiting status of the requests.

POST

/incident.waitingfor.customer

Sets the waiting for customer status to the request.

Parameters

Name	Description	Type
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the waiting status was correctly set; or 'ERROR' if something went wrong.	`STRING`
info	Description of the result.	`STRING`

Manages the waiting for date status of the requests.

POST

/incident.waitingfor.date

Sets the waiting for date status to the request.

Parameters

Name	Description	Type
timestamp required	Date timestamp to set.	`STRING`
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the waiting status was correctly set; or 'ERROR' if something went wrong.	`STRING`
info	Description of the result.	`STRING`

Manages the waiting for external entities status of the requests.

POST

/incident.waitingfor.external_entity

Sets the request in the waiting for external entity status. The entity should be already linked.

Parameters

Name	Description	Type
entity_link_id required	External entity ID to link to the request status.	`INTEGER`
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the waiting status was correctly set; or 'ERROR' if something went wrong.	`STRING`
info	Description of the result.	`STRING`

Manages the waiting for another request status.

POST

/incident.waitingfor.incident

Sets the request in the waiting for another request status.

Parameters

Name	Description	Type
wait_request_id required	Request ID that will be waiting for.	`INTEGER`
request_id required	Request ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the waiting status was correctly set; or 'ERROR' if something went wrong.	`STRING`
info	Description of the result.	`STRING`

Manages the requests.

GET

/incidents

Lists the requests.

Parameters

Name	Description	Type
ids required	Request IDs.	`ARRAY`
comments	When set to true, it includes the comments of the request.	`BOOLEAN`
date_format	Indicate the date format. The available formats are 'epoch' or 'iso8601'. If null, epoch format is returned.	`STRING`

Response

Returns an array of objects with the following structure:

Name	Description	Type
pretty_id	Request pretty ID as configured on the Service Desk instance.	`STRING`
process_id	Process ID of the request if it is a workflow instance.	`INTEGER`
attachments	Array with the IDs of the attachments.	`ARRAY`
assigned_group_id	Help desk ID.	`INTEGER`
category_id	Category ID.	`INTEGER`
rating	Stars given to the solution. If there's no rating, this field won't be shown.	`INTEGER`
date_ocurred	Occurrence date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
solved_at	Solution date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
sla_incident_first_reply	First response SLA of the request.	`STRING`
status_id	Status ID.	`INTEGER`
type_id	Type ID.	`INTEGER`
priority_id	Priority ID.	`INTEGER`
id	Request ID.	`INTEGER`
custom_fields	Array with the custom fields IDs as keys and the respective values.	`ARRAY`
assigned_id	Assigned agent ID.	`INTEGER`
created_at	Creation date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
title	Request title.	`STRING`
closed_at	Closing date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
description	Request description.	`STRING`
last_update	Last update in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
comments	Array with comments of the requests with the comment structure.	`ARRAY`
sla_incident_resolution	Resolution SLA of the request.	`STRING`
creator_id	Creator ID.	`INTEGER`
source_id	Source ID.	`INTEGER`
closed_reason	Reason of closing. 1: Solution accepted, 2: Solution expired, 3: Customer timeout, 4: Finalized workflow.	`INTEGER`
user_id	Customer ID.	`INTEGER`

Open requests by agent.

GET

/incidents.by.agent

Lists the requests from a given agent.

Parameters

Name	Description	Type
comments	When set to true, it includes the comments of the request.	`BOOLEAN`
username	Agent username.	`STRING`
email	Agent email.	`STRING`
id	Agent ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
pretty_id	Request pretty ID as configured on the Service Desk instance.	`STRING`
process_id	Process ID of the request if it is a workflow instance.	`INTEGER`
attachments	Array with the IDs of the attachments.	`ARRAY`
assigned_group_id	Help desk ID.	`INTEGER`
category_id	Category ID.	`INTEGER`
date_ocurred	Occurrence date in epoch.	`STRING`
solved_at	Solution date in epoch.	`STRING`
sla_incident_first_reply	First response SLA of the request.	`STRING`
status_id	Status ID.	`INTEGER`
type_id	Type ID.	`INTEGER`
priority_id	Priority ID.	`INTEGER`
id	Request ID.	`INTEGER`
custom_fields	Array with the custom fields IDs as keys and the respective values.	`ARRAY`
assigned_id	Assigned agent ID.	`INTEGER`
created_at	Creation date in epoch.	`STRING`
title	Request title.	`STRING`
closed_at	Closing date in epoch.	`STRING`
description	Request description.	`STRING`
last_update	Last update in epoch.	`STRING`
comments	Array with comments of the requests with the comment structure.	`ARRAY`
sla_incident_resolution	Resolution SLA of the request.	`STRING`
creator_id	Creator ID.	`INTEGER`
source_id	Source ID.	`INTEGER`
closed_reason	Reason of closing. 1: Solution accepted, 2: Solution expired, 3: Customer timeout, 4: Finalized workflow.	`INTEGER`
user_id	Customer ID.	`INTEGER`

Manages requests linked to CIs.

GET

/incidents.by.cis

Returns all the requests linked to a CI, considering its IDs, its groups and the ID of the integration it belongs to.

Parameters

Name	Description	Type
ci_ids required	IDs of the CIs.	`ARRAY`
cis_source_id required	ID of the ITAM tool integration in Service Desk.	`INTEGER`
group required	Name of the group the CIs belong to. Possible values are ‘Asset’ or ‘BusinessApplication’.	`STRING`

Response

Returns an array of objects with the following structure:

Name	Description	Type
ci_id	ID of the CI.	`STRING`
requests	An object that contains two arrays, one listing linked CIs by request status and the other counting linked CIs by request type, only for open requests.	`ARRAY`
group	Name of the group for this CI.	`STRING`

Manages open requests by customer.

GET

/incidents.by.customer

Lists the open requests from a customer.

Parameters

Name	Description	Type
comments	When set to true, it includes the comments of the request.	`BOOLEAN`
username	Customer username.	`STRING`
email	Customer email.	`STRING`
id	Customer ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
pretty_id	Request pretty ID as configured on the Service Desk instance.	`STRING`
process_id	Process ID of the request if it is a workflow instance.	`INTEGER`
attachments	Array with the IDs of the attachments.	`ARRAY`
assigned_group_id	Help desk ID.	`INTEGER`
category_id	Category ID.	`INTEGER`
date_ocurred	Occurrence date in epoch.	`STRING`
solved_at	Solution date in epoch.	`STRING`
sla_incident_first_reply	First response SLA of the request.	`STRING`
status_id	Status ID.	`INTEGER`
type_id	Type ID.	`INTEGER`
priority_id	Priority ID.	`INTEGER`
id	Request ID.	`INTEGER`
custom_fields	Array with the custom fields IDs as keys and the respective values.	`ARRAY`
assigned_id	Assigned agent ID.	`INTEGER`
created_at	Creation date in epoch.	`STRING`
title	Request title.	`STRING`
closed_at	Closing date in epoch.	`STRING`
description	Request description.	`STRING`
last_update	Last update in epoch.	`STRING`
comments	Array with comments of the requests with the comment structure.	`ARRAY`
sla_incident_resolution	Resolution SLA of the request.	`STRING`
creator_id	Creator ID.	`INTEGER`
source_id	Source ID.	`INTEGER`
closed_reason	Reason of closing. 1: Solution accepted, 2: Solution expired, 3: Customer timeout, 4: Finalized workflow.	`INTEGER`
user_id	Customer ID.	`INTEGER`

Manages open requests by help desk.

GET

/incidents.by.helpdesk

Lists the open requests from a help desk.

Parameters

Name	Description	Type
helpdesk_id	Help desk ID.	`INTEGER`
helpdesk_ids	Help desks IDs.	`ARRAY`

Response

Name	Description	Type
status	Returns 'OK' if the query was correctly executed; or 'ERROR' if something went wrong.	`STRING`
requestIds	Request IDs.	`ARRAY`
info	Description of the result.	`STRING`

Manages the open requests by status.

GET

/incidents.by.status

Lists all open requests matching the status specified by parameter.

Parameters

Name	Description	Type
offset	Skip this number of items in the response.	`INTEGER`
limit	Number of items per page.	`INTEGER`
status_ids	Status IDs.	`ARRAY`
status_id	Status ID.	`INTEGER`

Response

Name	Description	Type
offset	Items skipped in the response.	`INTEGER`
requestIds	Request IDs.	`ARRAY`
limit	Number of items per page.	`INTEGER`
info	Description of the result.	`STRING`
status	Returns 'OK' if the query was correctly executed; or 'ERROR' if something went wrong.	`STRING`
total	Total items.	`INTEGER`

Manages the requests from a given view ID.

GET

/incidents.by.view

Lists the requests from a view ID.

Parameters

Name	Description	Type
offset	Skip this amount of requests in the response.	`INTEGER`
limit	Number of items per page.	`INTEGER`
view_id required	View ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the query was correctly executed; or 'ERROR' if something went wrong.	`STRING`
requestIds	Request IDs returned by the view.	`ARRAY`
limit	Number of items per page.	`INTEGER`
offset	This amount of request were skipped in the response.	`INTEGER`
info	Description of the result.	`STRING`

Manages the requests that were created within the last hour.

GET

/incidents.last.hour

Lists all the requests that were created within the last hour.

Response

Returns an array of objects with the following structure:

Name	Description	Type
pretty_id	Request pretty ID as configured on the Service Desk instance.	`STRING`
process_id	Process ID of the request if it is a workflow instance.	`INTEGER`
attachments	Array with the IDs of the attachments.	`ARRAY`
assigned_group_id	Help desk ID.	`INTEGER`
category_id	Category ID.	`INTEGER`
rating	Stars given to the solution. If there's no rating, this field won't be shown.	`INTEGER`
date_ocurred	Occurrence date in epoch.	`STRING`
solved_at	Solution date in epoch.	`STRING`
sla_incident_first_reply	First response SLA of the request.	`STRING`
status_id	Status ID.	`INTEGER`
type_id	Type ID.	`INTEGER`
priority_id	Priority ID.	`INTEGER`
id	Request ID.	`INTEGER`
custom_fields	Array with the custom fields IDs as keys and the respective values.	`ARRAY`
assigned_id	Assigned agent ID.	`INTEGER`
created_at	Creation date in epoch.	`STRING`
title	Request title.	`STRING`
closed_at	Closing date in epoch.	`STRING`
description	Request description.	`STRING`
last_update	Last update in epoch.	`STRING`
comments	Array with comments of the requests with the comment structure.	`ARRAY`
sla_incident_resolution	Resolution SLA of the request.	`STRING`
creator_id	Creator ID.	`INTEGER`
source_id	Source ID.	`INTEGER`
closed_reason	Reason of closing. 1: Solution accepted, 2: Solution expired, 3: Customer timeout, 4: Finalized workflow.	`INTEGER`
user_id	Customer ID.	`INTEGER`

Manages internal notes.

GET

/internalnotes

Lists all the internal notes, or one in particular.

Parameters

Name	Description	Type
object_id	Entity ID.	`INTEGER`
date_format	Indicate the date format. The available formats are 'epoch' or 'iso8601'. If null, epoch format is returned.	`STRING`
id required	Note ID.	`INTEGER`
object_type	Entity type ID. 1: User, 2: Helpdesk, 3: Company, 4: Users Group, 5: External Entity.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
object_id	Entity ID.	`INTEGER`
created_at	Creation date of the note in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
title	Note title.	`STRING`
author_id	Author ID.	`INTEGER`
description	Note description.	`STRING`
last_update	Last update of the note in epoch or ISO-8601 format depending on the date_format .	`STRING`
last_author	Last author ID.	`INTEGER`
id	Note ID.	`INTEGER`
object_type	Entity type ID. 1: User, 2: Helpdesk, 3: Company, 4: Users Group, 5: External Entity.	`INTEGER`

PUT

/internalnotes

Updates the info of an internal note.

Parameters

Name	Description	Type
author_id required	Author ID.	`INTEGER`
description	Note description.	`STRING`
title	Note title.	`STRING`
id required	Note ID.	`INTEGER`

Response

Name	Description	Type
Status	Returns 'OK' if the internal note was correctly updated; or 'ERROR' if something went wrong.	`STRING`

DELETE

/internalnotes

Deletes an internal note.

Parameters

Name	Description	Type
author_id required	Author ID.	`INTEGER`
id required	Note ID.	`INTEGER`

Response

Name	Description	Type
Status	Returns 'OK' if the internal note was correctly deleted; or 'ERROR' if something went wrong.	`STRING`

POST

/internalnotes

Creates an internal note.

Parameters

Name	Description	Type
object_id required	Entity ID.	`INTEGER`
author_id required	Author ID.	`INTEGER`
description required	Note description.	`STRING`
title required	Note title.	`STRING`
object_type required	Entity type ID. 1: User, 2: Helpdesk, 3: Company, 4: Users Group, 5: External Entity.	`INTEGER`

Response

Name	Description	Type
Status	Returns 'OK' if the internal note was correctly created; or 'ERROR' if something went wrong.	`STRING`

Manages articles from the Knowledge Base.

GET

/kb.articles

Lists all the articles with their properties.

Parameters

Name	Description	Type
offset	Skip this number of items in the response.	`INTEGER`
limit	Number of items per page.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
category_id	Category ID.	`INTEGER`
creation_date	Creation date in epoch.	`STRING`
attachments	Array with the ID, name and URL of each attachment.	`ARRAY`
content	Content of the article.	`STRING`
title	Article title.	`STRING`
views	Amount of views that the article has.	`INTEGER`
author_id	Author ID.	`INTEGER`
solved_requests	Amount of requests that this article helped to solve.	`INTEGER`
rating	Average scoring of the article.	`FLOAT`
id	Article ID.	`INTEGER`
last_update_date	Last update date in epoch.	`STRING`

PUT

/kb.articles

Modifies an article given a certain ID.

Parameters

Name	Description	Type
category_id	Category ID.	`INTEGER`
content	Article content.	`STRING`
title	Article title.	`STRING`
is_private	True if the article is for internal use only.	`BOOLEAN`
author_id required	Author ID.	`INTEGER`
description	Article description.	`STRING`
id required	Article ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the article was correctly modified; or 'ERROR' if something went wrong.	`STRING`

DELETE

/kb.articles

Deletes an article from a given ID.

Parameters

Name	Description	Type
id required	Article ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the article was correctly deleted; or 'ERROR' if something went wrong.	`STRING`

POST

/kb.articles

Creates an article.

Parameters

Name	Description	Type
content required	Article content.	`STRING`
title required	Article title.	`STRING`
is_private	True if the article is for internal use only.	`BOOLEAN`
author_id required	Author ID.	`INTEGER`
description	Article description.	`STRING`
attachments	Array of attachments.	`ARRAY`
category_id required	Category ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the article was correctly created; or 'ERROR' if something went wrong.	`STRING`
article_id	Article ID.	`INTEGER`

Manages the attachments from a Knowledge Base article.

GET

/kb.articles.attachments

Lists the attachments from an article.

Parameters

Name	Description	Type
article_id required	Article ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
status	Returns 'OK' if the query was correctly executed; or 'ERROR' if something went wrong.	`STRING`
url	Attachment URL.	`STRING`
name	Attachment Filename.	`STRING`
id	Attachment ID.	`INTEGER`

DELETE

/kb.articles.attachments

Deletes an attachment from an article.

Parameters

Name	Description	Type
attachment_id required	Attachment ID.	`INTEGER`
article_id required	Article ID.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the attachment was correctly deleted; or 'ERROR' if something went wrong.	`STRING`

POST

/kb.articles.attachments

Adds attachments to an article.

Parameters

Name	Description	Type
author_id required	ID of the user in whose name the update of the article will be done.	`INTEGER`
article_id required	Article ID.	`INTEGER`
attachments	Array of attachments.	`ARRAY`

Response

Name	Description	Type
status	Returns 'OK' if the attachment was correctly added; or 'ERROR' if something went wrong.	`STRING`

Manages Knowledge Base articles by category.

GET

/kb.articles.by.category

Lists all the articles that belong to a certain category.

Parameters

Name	Description	Type
offset	Skip this number of items in the response.	`INTEGER`
limit	Number of items per page.	`INTEGER`
category_id required	Category ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
category_id	Category ID.	`INTEGER`
creation_date	Creation date in epoch.	`STRING`
attachments	Array with the ID, name and URL of each attachment.	`ARRAY`
content	Content of the article.	`STRING`
title	Article title.	`STRING`
views	Amount of views that the article has.	`INTEGER`
author_id	Author ID.	`INTEGER`
solved_requests	Amount of requests that this article helped to solve.	`INTEGER`
rating	Average scoring of the article.	`FLOAT`
id	Article ID.	`INTEGER`
last_update_date	Last update date in epoch.	`STRING`

Manages Knowledge Base articles by ID.

GET

/kb.articles.by.ids

Lists articles by ID.

Parameters

Name	Description	Type
ids required	Article IDs.	`ARRAY`

Response

Returns an array of objects with the following structure:

Name	Description	Type
category_id	Category ID.	`INTEGER`
creation_date	Creation date in epoch.	`STRING`
attachments	Array with the ID, name and URL of each attachment.	`ARRAY`
content	Content of the article.	`STRING`
title	Article title.	`STRING`
views	Amount of views that the article has.	`INTEGER`
author_id	Author ID.	`INTEGER`
solved_requests	Amount of requests that this article helped to solve.	`INTEGER`
rating	Average scoring of the article.	`FLOAT`
id	Article ID.	`INTEGER`
last_update_date	Last update date in epoch.	`STRING`

Manages Knowledge Base articles by keywords.

GET

/kb.articles.by.keywords

Searches for articles by keywords.

Parameters

Name	Description	Type
limit	Number of results, 25 by default.	`INTEGER`
min_search_scoring	Minimum search scoring from 0 to 1, which measures the accuracy of the search results.	`FLOAT`
keywords required	Keywords to search.	`STRING`

Response

Returns an array of objects with the following structure:

Name	Description	Type
creation_date	Creation date in epoch.	`STRING`
last_update_date	Last update date in epoch.	`STRING`
title	Article title.	`STRING`
views	Amount of views that the article has.	`INTEGER`
attachments	Array with the ID, name and URL of each attachment.	`ARRAY`
category_id	Category ID.	`INTEGER`
rating	Average scoring of the article.	`FLOAT`
search_scoring	Score from 0 to 1 that measures the accuracy of the search result.	`FLOAT`
content	Content of the article.	`STRING`
author_id	Author ID.	`INTEGER`
id	Article ID.	`INTEGER`
solved_requests	Amount of requests that this article helped to solve.	`INTEGER`

Manages Knowledge Base categories.

GET

/kb.categories

Lists all the Knowledge Base categories.

Response

Returns an array of objects with the following structure:

Name	Description	Type
parent_id	Category parent ID.

Service Desk Developer Manual

API Usage

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Response

Parameters

Response

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response