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.
Modifies a set of Breaking News.

Parameters

Name Description Type
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
id required

Breaking News ID.

INTEGER
creator_id

ID of the Breaking News' creator. If none is provided then it will be the system.

INTEGER
affected_group_ids

Groups that are affected. It is required unless there is at least one help desk affected.

ARRAY
title

Breaking News title.

STRING
type_id

Type ID of the breaking news based on importance. 1: High, 2: Medium, 3: Low.

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
body required

Breaking News body.

TEXT
affected_group_ids

Groups that are affected. It is required unless there is at least one help desk affected.

ARRAY
creator_id

ID of the Breaking News' creator. If none is provided then it will be the system.

INTEGER
affected_helpdesk_ids

Help desks that are affected. It is required unless there is at least one group affected.

ARRAY
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
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 created; or 'ERROR' if something went wrong. STRING
info Description of the result. STRING
id ID of the Breaking News created. INTEGER
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
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
affected_helpdesk_ids Array with IDs of affected help desks. ARRAY
body Breaking News body. TEXT
created_at Creation date in epoch or ISO-8601 format depending on the date_format parameter. STRING
id Breaking News ID. INTEGER
status_id Breaking News status ID. INTEGER
affected_group_ids Array with IDs of affected groups. ARRAY
title Breaking News title. STRING
type_id Breaking News type ID. INTEGER

/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
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
affected_helpdesk_ids Array with IDs of affected help desks. ARRAY
type_id Breaking News type ID. INTEGER
status_id Breaking News status ID. INTEGER
id Breaking News ID. INTEGER
affected_group_ids Array with IDs of affected groups. ARRAY
title Breaking News title. STRING
body Breaking News body. TEXT
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.
Creates a new update to the given Breaking News.

Parameters

Name Description Type
creator_id

ID of the Breaking News' creator. If none is provided then it will be the system.

INTEGER
body required

Breaking News body.

TEXT
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
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
creator_id Breaking News creator ID. INTEGER
body Body of the update. TEXT
created_at Creation date in epoch or ISO-8601 format depending on the date_format parameter. 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
parent_category_id Category parent ID. INTEGER
id Category ID. INTEGER

/cf.field.options.list

Manages the settings of the list type custom fields.
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
total Number of modified/added values. INTEGER
status Returns 'OK' if the custom field option was correctly added or modified; or 'ERROR' if something went wrong. STRING
info Description of the result. STRING
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
total Number of deleted values. INTEGER
status Returns 'OK' if the custom field option was correctly deleted; or 'ERROR' if something went wrong. STRING
info Description of the result. STRING

/cf.field.options.tree

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

Name of the option, value that the user sees when selecting.

STRING
key

Key defined by the user; if no value is set the previous value will be used.

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
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
name required

Name of the option, value that the user sees when selecting.

STRING
key

Key defined by the user; if no value is set, the hash will be used as key.

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
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
name Option name. STRING
key Key defined by the user for the option. STRING
hash The unique internal identifier of the option. STRING
children Array of the option's children. ARRAY
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

/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
uid Custom field ID. INTEGER
description Custom field description. TEXT
is_required Indicates if the custom field is required. True if it's required and false if it's not. BOOLEAN
categories Categories where custom field applies. STRING
label Custom field name. STRING
type Custom field type ID. INTEGER

/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_external_id Configuration item external source ID. INTEGER
ci_internal_id Configuration item ID from Service Desk. INTEGER
ci_name Configuration item name. STRING

/companies

Manages companies.
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
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
name Company name. STRING
total Users total. INTEGER
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

/companies.groups

Manages the relationships between users groups and companies.
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
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
name Name of the related group. STRING
total Users total. INTEGER
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

/companies.observers

Manages 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
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
observer_groups The groups’ IDs that are observers of the entity. ARRAY
id Company ID. INTEGER
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

/companies.users

Manages the relationships between users and companies.
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
Lists the members of a company.

Parameters

Name Description Type
user_id

User ID

INTEGER
id required

Company ID.

INTEGER

Response

Returns an array of objects with the following structure:

Name Description Type
name User full name. STRING
email User email. STRING
username Username. STRING
id User ID. INTEGER
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

/groups

Manages groups.
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
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
name Group name. STRING
total Users total. INTEGER
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

/groups.observers

Manages 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
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
observer_groups The groups’ IDs that are observers of the entity. ARRAY
id Group ID. INTEGER
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

/groups.users

Manages the relationships between users and groups.
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
Lists the members of a group.

Parameters

Name Description Type
user_id

User ID

INTEGER
id required

Group ID.

INTEGER

Response

Returns an array of objects with the following structure:

Name Description Type
name User full name. STRING
email User email. STRING
username Username. STRING
id User ID. INTEGER
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

/helpdesks

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

Parameters

Name Description Type
name

Help desk name.

STRING
include_deleted

True if deleted help desks should be included.

BOOLEAN
id

Help desk ID.

INTEGER

Response

Returns an array of objects with the following structure:

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

/helpdesks.observers

Manages help desks 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
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
observer_groups The groups’ IDs that are observers of the entity. ARRAY
id Help Desk ID. INTEGER
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

/helpdesksandlevels

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

Parameters

Name Description Type
include_deleted

True if deleted help desks and levels should be included.

BOOLEAN
id

Level ID.

INTEGER

Response

Returns an array of objects with the following structure:

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

/incident

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

Set to true to reassign the request to a help desk according to the new properties.

BOOLEAN
priority_id

Low = 1, Medium = 2, High = 3, Urgent = 4, Critical = 5

INTEGER
description

Request description.

TEXT
date

Occurred on timestamp.

STRING
type_id

Incident = 1, Service Request = 2, Question = 3, Problem = 4, Change = 5, Major Incident = 6

INTEGER
id required

Request ID.

INTEGER
category_id

Category name can be obtained calling https://releases.invgate.com/service-desk/api/#categories-GET

INTEGER
customer_id

Client ID.

INTEGER
title

Request title.

STRING
source_id

Source ID.

INTEGER
location_id

Location ID.

INTEGER

Response

Returns an array of objects with the following structure:

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

Parameters

Name Description Type
creator_id required

Creator ID.

INTEGER
title required

Request title.

STRING
priority_id required

Low = 1, Medium = 2, High = 3, Urgent = 4, Critical = 5

INTEGER
description

Request description. Required for requests and Workflows with descriptions.

TEXT
date

Occurred on timestamp in epoch format.

STRING
related_to

Requests IDs to link.

ARRAY
location_id

Location ID.

INTEGER
category_id required

Category name can be obtained calling https://releases.invgate.com/service-desk/api/#categories-GET

INTEGER
customer_id required

Client ID.

INTEGER
attachments

Array of request's attachments.

ARRAY
source_id

Source ID.

INTEGER
type_id required

Incident = 1, Service Request = 2, Question = 3, Problem = 4, Change = 5, Major Incident = 6

INTEGER

Response

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

Parameters

Name Description Type
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
comments

When set to true, it includes the comments of the request.

BOOLEAN
id required

Request ID.

INTEGER

Response

Returns an array of objects with the following structure:

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

/incident.approval

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

When set to true, it only returns pending approvals.

BOOLEAN
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
id ID of the approval instance. INTEGER
author_id Author ID of the approval. INTEGER
type Type ID of the approval. 1: Predefined approval, 2: Spontaneous approval. INTEGER
approval_request_id ID of the approval template. INTEGER
created_at Date when the approval was triggered, in epoch or ISO-8601 format depending on the date_format parameter. STRING

/incident.approval.accept

Manages the acceptance of an approval.
Accepts an approval.

Parameters

Name Description Type
user_id required

ID of the user who will accept the approval.

INTEGER
approval_id required

Approval ID to be accepted.

INTEGER
note

Note for the approval acceptance.

STRING

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
user_id required

Author ID of the approval.

INTEGER
approval_id required

ID of the approval instance.

INTEGER

Response

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

/incident.approval.cancel

Manages the cancellation of an approval.
Cancels an approval.

Parameters

Name Description Type
user_id required

ID of the user who will cancel the approval.

INTEGER
approval_id required

Approval ID to be cancelled.

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
approval_id required

Approval ID.

INTEGER
only_pending

When set to true, it only returns voters who have not voted.

BOOLEAN

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
user_id required

ID of the user will reject the approval.

INTEGER
approval_id required

Approval ID to be rejected.

INTEGER
note

Note for the approval rejection.

STRING

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
name Name of the attached file. STRING
url URL of the attached file. STRING
extension Extension of the attached file. STRING
hash Hash of the attached file. STRING
id ID of the attached file. INTEGER

/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.
Requests collaboration from the defined user.

Parameters

Name Description Type
user_id

User ID.

INTEGER
users_id

Users IDs.

ARRAY
author_id required

Author ID. Must be the ID of the user that asks for collaboration.

INTEGER
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
Lists the collaborators IDs.

Parameters

Name Description Type
request_id required

Request ID.

INTEGER

/incident.comment

Manages the replies from a given request.
Adds a reply to a request.

Parameters

Name Description Type
comment required

Comment to be added.

TEXT
is_solution

Mark as solution. 1: Is solution, 0: Is not solution.

BOOLEAN
attachments

Attachments IDs.

ARRAY
author_id required

Author ID.

INTEGER
customer_visible

Mark as internal. 0: Internal, 1: Public.

BOOLEAN
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
error Description of the error. STRING
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
date_format

Indicate the date format. The available formats are 'epoch' or 'iso8601'. If null, epoch format is returned.

STRING
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
request_id required

Request ID.

INTEGER

Response

Returns an array of objects with the following structure:

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

/incident.custom_approval

Manages the custom approvals.
Requests a custom approval in the given request.

Parameters

Name Description Type
description

Custom approval description.

TEXT
approval_id required

Custom approval ID.

INTEGER
author_id required

Author ID of the approval request.

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

/incident.custom_field

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

Custom field UID.

INTEGER
author_id required

Author ID.

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
Deletes value in the associated custom field.

Parameters

Name Description Type
custom_field_uid required

Custom field UID.

INTEGER
author_id required

Author ID.

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

/incident.external_entity

Manages the external entities linked to a request.
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
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
name External entity name. STRING
status Entity status. 1: Enabled, 0: Deleted. BOOLEAN
ext_ref_id External entity reference ID. INTEGER
type Entity type. Always 100. STRING
ref_id External entity ID. INTEGER
link_id Relation ID. INTEGER

/incident.link

Manages the requests linked to a request.
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
error Description of the error. STRING
info Description of the result. STRING
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

/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
group Name of the group for this CI. STRING
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

/incident.observer

Manages the request's observers.
Adds a user as observer.

Parameters

Name Description Type
user_id

User ID.

INTEGER
users_id

Users IDs.

ARRAY
author_id required

Author ID.

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

/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
agent_id

Agent ID.

INTEGER
group_id required

Help desk ID.

INTEGER
author_id required

Author 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
keyword required

Keyword to search CIs.

STRING
exact_match

Indicates if the results must be an exact match or not.

BOOLEAN
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
error Error code STRING
info Description of the result 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
rating required

Request rating. Rate the solution on a scale of 1-5, 1 being the lowest and 5 being the highest.

INTEGER
id required

Request ID.

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
description required

Approval description.

TEXT
approval_user_id required

User ID from the approval voter.

INTEGER
author_id required

Author ID.

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
date_format

Indicate the date format. The available formats are 'epoch' or 'iso8601'. If null, epoch format is returned.

STRING
comments

When set to true, it includes the comments of the request.

BOOLEAN

Response

Returns an array of objects with the following structure:

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

/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
email

Agent email.

STRING
username

Agent username.

STRING
id

Agent ID.

INTEGER

Response

Returns an array of objects with the following structure:

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

/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
group Name of the group for this CI. STRING
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

/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
email

Customer email.

STRING
username

Customer username.

STRING
id

Customer ID.

INTEGER

Response

Returns an array of objects with the following structure:

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

/incidents.by.helpdesk

Manages open requests by help desk.
Lists the open requests from a help desk.

Parameters

Name Description Type
helpdesk_ids

Help desks IDs.

ARRAY
helpdesk_id

Help desk 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. 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
status_ids

Status IDs.

ARRAY
status_id

Status ID.

INTEGER
limit

Number of items per page.

INTEGER

Response

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

/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
view_id required

View ID.

INTEGER
limit

Number of items per page.

INTEGER

Response

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

/incidents.details.by.view

Lists the requests with their details from a view ID.
Lists the requests with their details from a view ID.

Parameters

Name Description Type
order_by

The order in which the results should be sorted. "asc" if the results should be sorted in ascending order, or "desc" if they should be sorted in descending order. If null, requests will be returned sorted in ascending order.

STRING
page_key

Hash key of the results page to retrieve. If null, the first page of results will be returned.

STRING
view_id required

View ID.

INTEGER
sort_by

Attribute upon which the sorting of the results will be performed. "id" if results should be sorted by the request ID, or "last_update" if they should be sorted by the request's last update date. If null, requests will be returned sorted by ID.

STRING

Response

Name Description Type
metadata Provides resource objects that are related to the primary data, including the labels of the columns from the view. ARRAY
next_page_key Hash key of the next page of results. If null, the results page retrieved is the last one. STRING
data Contains a JSON array (with pagination, 10 requests per page) representing the primary data of the requests in the request view. ARRAY

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

/internalnotes

Manages internal notes.
Updates the info of an internal note.

Parameters

Name Description Type
description

Note description.

STRING
title

Note title.

STRING
author_id required

Author ID.

INTEGER
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
Creates an internal note.

Parameters

Name Description Type
object_type required

Entity type ID. 1: User, 2: Helpdesk, 3: Company, 4: Users Group, 5: External Entity.

INTEGER
object_id required

Entity ID.

INTEGER
author_id required

Author ID.

INTEGER
title required

Note title.

STRING
description required

Note description.

STRING

Response

Name Description Type
Status Returns 'OK' if the internal note was correctly created; or 'ERROR' if something went wrong. STRING
Lists all the internal notes, or one in particular.

Parameters

Name Description Type
object_type

Entity type ID. 1: User, 2: Helpdesk, 3: Company, 4: Users Group, 5: External Entity.

INTEGER
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

Response

Returns an array of objects with the following structure:

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

/kb.articles

Manages articles from the Knowledge Base.
Modifies an article given a certain ID.

Parameters

Name Description Type
description

Article description.

STRING
is_private

True if the article is for internal use only.

BOOLEAN
id required

Article ID.

INTEGER
category_id

Category ID.

INTEGER
content

Article content.

STRING
title

Article title.

STRING
author_id required

Author ID.

INTEGER
responsible_id

Article responsible. If it's null, the assigned responsible user will be the same as the author.

INTEGER

Response

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

Parameters

Name Description Type
description

Article description.

STRING
attachments

Array of attachments.

ARRAY
is_private

True if the article is for internal use only.

BOOLEAN
category_id required

Category ID.

INTEGER
content required

Article content.

STRING
title required

Article title.

STRING
author_id required

Author ID.

INTEGER
responsible_id

Article responsible. If it's null, the assigned responsible user will be the same as the author.

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
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
solved_requests Amount of requests that this article helped to solve. INTEGER
attachments Array with the ID, name and URL of each attachment. ARRAY
views Amount of views that the article has. INTEGER
responsible_id Responsible ID. INTEGER
creation_date Creation date in epoch. STRING
rating Average scoring of the article. FLOAT
id Article ID. INTEGER
category_id Category ID. INTEGER
last_update_date Last update date in epoch. STRING
author_id Author ID. INTEGER
content Content of the article. STRING
title Article title. 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

/kb.articles.attachments

Manages the attachments from a Knowledge Base article.
Adds attachments to an article.

Parameters

Name Description Type
attachments

Array of attachments.

ARRAY
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

Response

Name Description Type
status Returns 'OK' if the attachment was correctly added; or 'ERROR' if something went wrong. STRING
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
name Attachment Filename. STRING
status Returns 'OK' if the query was correctly executed; or 'ERROR' if something went wrong. STRING
url Attachment URL. 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

/kb.articles.by.category

Manages Knowledge Base articles by category.
Lists all the articles that belong to a certain category.

Parameters

Name Description Type
category_id required

Category ID.

INTEGER
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
solved_requests Amount of requests that this article helped to solve. INTEGER
attachments Array with the ID, name and URL of each attachment. ARRAY
views Amount of views that the article has. INTEGER
responsible_id Responsible ID. INTEGER
creation_date Creation date in epoch. STRING
rating Average scoring of the article. FLOAT
id Article ID. INTEGER
category_id Category ID. INTEGER
last_update_date Last update date in epoch. STRING
author_id Author ID. INTEGER
content Content of the article. STRING
title Article title. 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
solved_requests Amount of requests that this article helped to solve. INTEGER
attachments Array with the ID, name and URL of each attachment. ARRAY
views Amount of views that the article has. INTEGER
responsible_id Responsible ID. INTEGER
creation_date Creation date in epoch. STRING
rating Average scoring of the article. FLOAT
id Article ID. INTEGER
category_id Category ID. INTEGER
last_update_date Last update date in epoch. STRING