Service Desk Developer Manual

API Usage

Abstract

An API (Application Programming Interface) is a set of services and procedures that a system, like Service Desk in this case, offers to get information and apply changes from outside the system. For instance: Requests creation, administration of groups, companies, time-tracking, etc. In this manual we present in detail the resources that Service Desk offers and how to use them.

/breakingnews

Manages the Breaking News.
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
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
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

/breakingnews.all

Lists the Breaking News.
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

/breakingnews.attributes.status

Lists the status of the Breaking News.
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

/breakingnews.attributes.type

Lists all the Breaking News importance types.
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

/breakingnews.status

Manages the updates of the Breaking News.
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
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

/categories

Lists all the 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

/cf.field.options.list

Manages the settings of the list type custom fields.
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
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
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

/cf.field.options.tree

Manages the settings of the tree type custom fields.
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
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
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
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

/cf.fields.all

Lists the active custom fields.
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

/cf.fields.by.category

Custom 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

/cf.fields.types

Lists all the supported custom field 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

/cis.by.id

Manages configuration items from custom fields and shared custom fields by IDs.
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

/companies

Manages 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

/companies.groups

Manages the relationships between users groups and companies.
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
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
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

/companies.observers

Manages 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
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
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

/companies.users

Manages the relationships between users and companies.
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
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
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

/groups

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

/groups.observers

Manages 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
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
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

/groups.users

Manages the relationships between users and groups.
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
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

/helpdesks

Manages the help desks.
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

/helpdesks.observers

Manages help desks 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
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
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

/helpdesksandlevels

Manages help desks and levels.
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

/incident

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

/incident.approval

Manages the approvals instances of a request.
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

/incident.approval.accept

Manages the acceptance of an approval.
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

/incident.approval.add_voter

Manages the voters of an approval.
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

/incident.approval.cancel

Manages the cancellation of an approval.
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

/incident.approval.possible_voters

Manages the users that could accept or reject the approval.
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

/incident.approval.reject

Manages the rejection of an approval.
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

/incident.approval.status

Lists the statuses of the approvals.
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

/incident.approval.type

Lists the available approvals types.
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

/incident.approval.vote_status

Lists the status of the approval votes.
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

/incident.attachment

Manages the attachments of the requests.
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

/incident.attributes.priority

Lists all the priorities.
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

/incident.attributes.source

Lists all the requests sources.
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

/incident.attributes.status

Lists all the 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

/incident.attributes.type

Lists all the types.
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

/incident.collaborator

Manages the collaborators of the requests.
Lists the collaborators IDs.

Parameters

Name Description Type
request_id required

Request ID.

INTEGER
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

/incident.comment

Manages the replies from a given request.
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
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

/incident.custom_approval

Manages the custom approvals.
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
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

/incident.custom_field

Manages the custom fields from a request.
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
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.
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

/incident.external_entity

Manages the external entities linked to a request.
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
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

/incident.link

Manages the requests linked to a request.
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
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

/incident.linked_cis.counters.from

Manages the linked assets counters.
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

/incident.observer

Manages the request's observers.
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
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

/incident.reassign

Manages the requests reassignations to a help desk or agent.
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

/incident.reject

Manages the rejection of a request.
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

/incident.relate.ci.by.keyword

Relates a request to every CI that matches a certain 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

/incident.reopen

Manages a request reopening.
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

/incident.solution.accept

Manages the acceptance of a request's solution.
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

/incident.solution.reject

Manages the rejection of a request's solution.
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

/incident.spontaneous_approval

Manages the spontaneous approvals from a request.
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

/incident.waitingfor.agent

Manages the agent waiting status of the requests.
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

/incident.waitingfor.customer

Manages the customer waiting status of the requests.
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

/incident.waitingfor.date

Manages the waiting for date status of the requests.
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

/incident.waitingfor.external_entity

Manages the waiting for external entities status of the requests.
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

/incident.waitingfor.incident

Manages the waiting for another request status.
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

/incidents

Manages the requests.
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

/incidents.by.agent

Open requests 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

/incidents.by.cis

Manages requests linked to 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

/incidents.by.customer

Manages open requests 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

/incidents.by.helpdesk

Manages open requests by help desk.
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

/incidents.by.status

Manages the open requests 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

/incidents.by.view

Manages the requests from a given view ID.
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

/incidents.last.hour

Manages the requests that were created within the 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

/internalnotes

Manages internal notes.
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
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
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
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

/kb.articles

Manages articles from the Knowledge Base.
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
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
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

/kb.articles.attachments

Manages the attachments from a Knowledge Base article.
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
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
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

/kb.articles.by.category

Manages Knowledge Base 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

/kb.articles.by.ids

Manages Knowledge Base articles by ID.
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

/kb.articles.by.keywords

Manages Knowledge Base 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

/kb.categories

Manages Knowledge Base 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.