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.
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
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
resolution_time

Estimated resolution time. Must be a timestamp (epoch format).

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

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

INTEGER

Response

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

Parameters

Name Description Type
id required

Breaking News ID.

INTEGER
affected_group_ids

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

ARRAY
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
resolution_time

Estimated resolution time. Must be a timestamp (epoch format).

INTEGER
body

Breaking News body.

TEXT
creator_id

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

INTEGER
type_id

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

INTEGER

Response

Name Description Type
info Description of the result. STRING
status Returns 'OK' if the Breaking News was correctly modified; or 'ERROR' if something went wrong. STRING
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_at Creation date in epoch or ISO-8601 format depending on the date_format parameter. STRING
id Breaking News ID. INTEGER
affected_group_ids Array with IDs of affected groups. ARRAY
resolution_time Resolution time in epoch or ISO-8601 format depending on the date_format parameter. STRING
status_id Breaking News status ID. INTEGER
title Breaking News title. STRING
affected_helpdesk_ids Array with IDs of affected help desks. ARRAY
created_by_id Breaking News creator ID. INTEGER
body Breaking News body. TEXT
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_at Creation date in epoch or ISO-8601 format depending on the date_format parameter. STRING
id Breaking News ID. INTEGER
affected_group_ids Array with IDs of affected groups. ARRAY
resolution_time Resolution time in epoch or ISO-8601 format depending on the date_format parameter. STRING
status_id Breaking News status ID. INTEGER
title Breaking News title. STRING
affected_helpdesk_ids Array with IDs of affected help desks. ARRAY
created_by_id Breaking News creator ID. INTEGER
body Breaking News body. TEXT
type_id Breaking News type ID. INTEGER

/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
id Status ID. INTEGER
name Status name. STRING

/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
id Importance type ID. INTEGER
name Importance type name. STRING

/breakingnews.status

Manages the updates of the Breaking News.
Creates a new update to the given Breaking News.

Parameters

Name Description Type
id required

Breaking News ID.

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

Send 1 to close Breaking News. Send 0 to keep open. Default: 0.

BOOLEAN

Response

Name Description Type
info Description of the result. STRING
status Returns 'OK' if the Breaking News update was correctly created; or 'ERROR' if something went wrong. 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
created_at Creation date in epoch or ISO-8601 format depending on the date_format parameter. STRING
body Body of the update. TEXT
creator_id Breaking News creator ID. INTEGER

/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
id Category ID. INTEGER
name Category name. STRING
parent_category_id Category parent 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
type required

Type of configuration to change. Types: key-value.

STRING
key_values required

Dictionary {key1: value1, key2: value2, ...} with key-values pairs to be added to the CF list.

ARRAY

Response

Name Description Type
info Description of the result. STRING
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
Erases keys from the list type custom fields configuration.

Parameters

Name Description Type
keys required

Array [key1,key2] of keys to be erased.

ARRAY
uid required

Custom field ID.

INTEGER
type required

Type of configuration to change. Types: key-value.

STRING

Response

Name Description Type
info Description of the result. STRING
status Returns 'OK' if the custom field option was correctly deleted; or 'ERROR' if something went wrong. STRING
total Number of deleted values. INTEGER
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

/cf.field.options.tree

Manages the settings of the tree type custom fields.
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
info Description of the result. STRING
status Returns 'OK' if the custom field option was correctly added; or 'ERROR' if something went wrong. STRING
Erases the options from the tree type custom fields and any of its children.

Parameters

Name Description Type
hash required

Hash value of the item to modify.

STRING
uid required

Custom field ID.

INTEGER

Response

Name Description Type
info Description of the result. STRING
status Returns 'OK' if the custom field option was correctly deleted; or 'ERROR' if something went wrong. STRING
Modifies the configuration of the tree type custom fields. If there is no such key, it will be added.

Parameters

Name Description Type
hash required

Hash value of the item to modify.

STRING
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

Response

Name Description Type
info Description of the result. STRING
status Returns 'OK' if the custom field option was correctly modified; or 'ERROR' if something went wrong. 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
hash The unique internal identifier of the option. STRING
children Array of the option's children. ARRAY
name Option name. STRING
key Key defined by the user for the option. 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
label Custom field name. STRING
type Custom field type ID. INTEGER
categories Categories where custom field applies. STRING
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

/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
id Custom field type ID. INTEGER
name Custom field type name. STRING

/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_internal_id Configuration item ID from Service Desk. INTEGER
ci_external_id Configuration item external source ID. INTEGER

/companies

Manages companies.
POST
/companies
Creates a new company.

Parameters

Name Description Type
name required

Company name.

STRING
external_id

External ID.

STRING

Response

Name Description Type
id ID of the created object. INTEGER
status Returns 'OK' if the company was correctly created; or 'ERROR' if something went wrong. STRING
name Company name. STRING
external_id External ID. STRING
DELETE
/companies
Erases an existing company.

Parameters

Name Description Type
id required

Company ID.

INTEGER

Response

Name Description Type
status Returns 'OK' if the company was correctly deleted; or 'ERROR' if something went wrong. STRING
Modifies an existing company.

Parameters

Name Description Type
id required

Company ID.

INTEGER
name

Company name.

STRING
external_id

External ID.

STRING

Response

Name Description Type
id Company ID. INTEGER
status Returns 'OK' if the company was correctly modified; or 'ERROR' if something went wrong. STRING
name Company name. STRING
external_id External ID. STRING
Returns all the active companies.

Parameters

Name Description Type
id

Company ID.

INTEGER
name

Company name.

STRING
external_id

External ID.

STRING

Response

Returns an array of companies with the following structure:

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

/companies.groups

Manages the relationships between users groups and companies.
Relates a users group to a company.

Parameters

Name Description Type
id required

Company ID.

INTEGER
groups required

Groups IDs.

ARRAY

Response

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

Name Description Type
id Group ID. ARRAY
Suppresses the relationship between a users group and a company.

Parameters

Name Description Type
id required

Company ID.

INTEGER
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

Response

Returns an array of groups IDs as keys and TRUE as values of the deleted 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
id ID of the related group. INTEGER
name Name of the related group. STRING
total Users total. INTEGER

/companies.observers

Manages companies observers.
Add users as observers to a company.

Parameters

Name Description Type
id required

Company ID.

INTEGER
observer_users required

Users IDs to be added as observers.

ARRAY

Response

Name Description Type
id User ID. INTEGER
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
Removes observers from a company.

Parameters

Name Description Type
id required

Company ID.

INTEGER
observer_users required

Users IDs to be removed as observers.

ARRAY

Response

Name Description Type
id User ID. INTEGER
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
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_groups The groups’ IDs that are observers of the entity. ARRAY
id Company ID. INTEGER
name Company name. STRING
observer_users The observers’ users IDs. ARRAY

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

Company ID.

INTEGER
users required

Users IDs.

ARRAY

Response

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

Name Description Type
id User ID. ARRAY
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
id required

Company ID.

INTEGER
users required

Users IDs.

ARRAY

Response

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

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

/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
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
GET
/groups
Returns all active groups of users, or one in particular if an ID or name is provided.

Parameters

Name Description Type
id

Group ID.

INTEGER
name

Group name.

STRING

Response

Returns an array of objects with the following structure:

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

/groups.observers

Manages groups observers.
Add users as observers to a group.

Parameters

Name Description Type
id required

Group ID.

INTEGER
observer_users required

Users IDs to be added as observers.

ARRAY

Response

Name Description Type
id User ID. INTEGER
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
Removes observers from a group.

Parameters

Name Description Type
id required

Group ID.

INTEGER
observer_users required

Users IDs to be removed as observers.

ARRAY

Response

Name Description Type
id User ID. INTEGER
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
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_groups The groups’ IDs that are observers of the entity. ARRAY
id Group ID. INTEGER
name Group name. STRING
observer_users The observers’ users IDs. ARRAY

/groups.users

Manages the relationships between users and groups.
Adds a user to a group.

Parameters

Name Description Type
id required

Group ID.

INTEGER
users required

Users IDs.

ARRAY

Response

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

Name Description Type
id User ID. ARRAY
DELETE
/groups.users
Removes a user from a group.

Parameters

Name Description Type
id required

Group ID.

INTEGER
users required

Users IDs.

ARRAY

Response

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

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

/helpdesks

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

Parameters

Name Description Type
id

Help desk ID.

INTEGER
name

Help desk name.

STRING
include_deleted

True if deleted help desks should be included.

BOOLEAN

Response

Returns an array of objects with the following structure:

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

/helpdesks.observers

Manages help desks observers.
Add users as observers to a help desk.

Parameters

Name Description Type
id required

Help Desk ID.

INTEGER
observer_users required

Users IDs to be added as observers.

ARRAY

Response

Name Description Type
id User ID. INTEGER
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
Removes observers from a help desk.

Parameters

Name Description Type
id required

Help Desk ID.

INTEGER
observer_users required

Users IDs to be removed as observers.

ARRAY

Response

Name Description Type
id User ID. INTEGER
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
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_groups The groups’ IDs that are observers of the entity. ARRAY
id Help Desk ID. INTEGER
name Help Desk name. STRING
observer_users The observers’ users IDs. ARRAY

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

/incident

Manages a request.
POST
/incident
Creates a request.

Parameters

Name Description Type
date

Occurred on timestamp in epoch format.

STRING
source_id

Source ID.

INTEGER
location_id

Location ID.

INTEGER
description

Request description. Required for requests and Workflows with descriptions.

TEXT
customer_id required

Client ID.

INTEGER
related_to

Requests IDs to link.

ARRAY
creator_id required

Creator ID.

INTEGER
attachments

Array of request's attachments.

ARRAY
title required

Request title.

STRING
type_id required

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

INTEGER
priority_id required

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

INTEGER
category_id required

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

INTEGER

Response

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

Parameters

Name Description Type
id required

Request ID.

INTEGER
customer_id

Client ID.

INTEGER
source_id

Source ID.

INTEGER
location_id

Location ID.

INTEGER
category_id

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

INTEGER
description

Request description.

TEXT
date_format

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

STRING
date

Occurred on timestamp.

STRING
reassignment

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

BOOLEAN
title

Request title.

STRING
priority_id

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

INTEGER
type_id

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

INTEGER

Response

Returns an array of objects with the following structure:

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

Request ID.

INTEGER
decoded_special_characters

Indicate if the message is returned decoded. If null, coded format is returned.

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

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

Note for the approval acceptance.

STRING
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
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
id User ID. INTEGER
status Approval status ID. -2: Annulled, -1: Waiting, 0: Rejected, 1: Approved, 2:Expired. 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
note

Note for the approval rejection.

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

/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
id Source ID. INTEGER
name Source name. STRING

/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
id Status ID. INTEGER
name Status name. STRING

/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
id Type ID. INTEGER
name Type name. STRING

/incident.cancel

Manages the cancellation of a request.
Cancel a request.

Parameters

Name Description Type
author_id required

ID of the user cancelling the request.

INTEGER
request_id required

ID of the request to cancel.

INTEGER
comment

Cancellation message

STRING

Response

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

/incident.collaborator

Manages the collaborators of the requests.
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
request_id required

Request ID.

INTEGER
user_id

User ID.

INTEGER
users_id

Users IDs.

ARRAY

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
customer_visible

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

BOOLEAN
attachments

Attachments IDs.

ARRAY
author_id required

Author ID.

INTEGER
request_id required

Request ID.

INTEGER
is_solution

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

BOOLEAN
comment required

Comment to be added.

TEXT

Response

Name Description Type
error Description of the error. STRING
status Returns 'OK' if the comment was correctly added; or 'ERROR' if something went wrong. STRING
Gets the replies from a given 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
decoded_special_characters

Indicate if the message is returned decoded. If null, coded format is returned.

BOOLEAN
request_id required

Request ID.

INTEGER
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

Response

Returns an array of objects with the following structure:

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

/incident.custom_approval

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

Parameters

Name Description Type
approval_id required

Custom approval ID.

INTEGER
author_id required

Author ID of the approval request.

INTEGER
request_id required

Request ID.

INTEGER
description

Custom approval description.

TEXT

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

/incident.custom_field

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

Author ID.

INTEGER
request_id required

Request ID.

INTEGER
custom_field_uid required

Custom field UID.

INTEGER

Response

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

Parameters

Name Description Type
author_id required

Author ID.

INTEGER
request_id required

Request ID.

INTEGER
custom_field_uid required

Custom field UID.

INTEGER

Response

Name Description Type
info Deletes value in the associated custom field. STRING
status Returns 'OK' if the values were correctly created; or 'ERROR' if something went wrong. 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.

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

Request ID.

INTEGER
external_entity_ref_id

External entity reference ID.

STRING

Response

Name Description Type
info Description of the result. STRING
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
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
type Entity type. Always 100. STRING
link_id Relation ID. INTEGER
ref_id External entity ID. INTEGER
status Entity status. 1: Enabled, 0: Deleted. BOOLEAN
name External entity name. STRING
ext_ref_id External entity reference 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
error Description of the error. STRING
info Description of the result. STRING
status Returns 'OK' if the request was correctly linked; or 'ERROR' if something went wrong. 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
id Related request ID. INTEGER
title Related request title. 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
group Name of the group for this CI. STRING
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
ci_id ID of the CI. INTEGER

/incident.observer

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

Parameters

Name Description Type
author_id required

Author ID.

INTEGER
request_id required

Request ID.

INTEGER
user_id

User ID.

INTEGER
users_id

Users IDs.

ARRAY

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

Author ID.

INTEGER
request_id required

Request ID.

INTEGER
group_id required

Help desk 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
request_id required

Request ID.

INTEGER
exact_match

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

BOOLEAN
keyword required

Keyword to search CIs.

STRING

Response

Name Description Type
info Description of the result. STRING
status Returns 'OK' if the CIs were correctly related; or 'ERROR' if something went wrong. 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
error Error code STRING
info Description of the result STRING
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
id required

Request ID.

INTEGER
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

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

Request ID.

INTEGER
comment required

Rejection reason.

STRING

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

Request ID.

INTEGER
approval_user_id required

User ID from the approval voter.

INTEGER
description required

Approval description.

TEXT

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
info Description of the result. STRING
status Returns 'OK' if the waiting status was correctly set; or 'ERROR' if something went wrong. 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
info Description of the result. STRING
status Returns 'OK' if the waiting status was correctly set; or 'ERROR' if something went wrong. 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
request_id required

Request ID.

INTEGER
timestamp required

Date timestamp to set.

STRING

Response

Name Description Type
info Description of the result. STRING
status Returns 'OK' if the waiting status was correctly set; or 'ERROR' if something went wrong. 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
request_id required

Request ID.

INTEGER
entity_link_id required

External entity ID to link to the request status.

INTEGER

Response

Name Description Type
info Description of the result. STRING
status Returns 'OK' if the waiting status was correctly set; or 'ERROR' if something went wrong. 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
request_id required

Request ID.

INTEGER
wait_request_id required

Request ID that will be waiting for.

INTEGER

Response

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

/incidents

Manages the requests.
Lists the requests.

Parameters

Name Description Type
date_format

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

STRING
ids required

Request IDs.

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

Agent ID.

INTEGER
username

Agent username.

STRING
email

Agent email.

STRING

Response

Returns an array of objects with the following structure:

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

IDs of the CIs.

ARRAY

Response

Returns an array of objects with the following structure:

Name Description Type
group Name of the group for this 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
ci_id ID of the 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
id

Customer ID.

INTEGER
username

Customer username.

STRING
email

Customer email.

STRING

Response

Returns an array of objects with the following structure:

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

/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
info Description of the result. STRING
status Returns 'OK' if the query was correctly executed; or 'ERROR' if something went wrong. STRING
requestIds Request IDs. ARRAY

/incidents.by.status

Manages the open requests by status.
Lists all open requests matching the status specified by parameter.

Parameters

Name Description Type
limit

Number of items per page.

INTEGER
status_ids

Status IDs.

ARRAY
status_id

Status ID.

INTEGER
offset

Skip this number of items in the response.

INTEGER

Response

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

/incidents.by.view

Manages the requests from a given view ID.
Lists the requests from a view ID.

Parameters

Name Description Type
limit

Number of items per page.

INTEGER
view_id required

View ID.

INTEGER
offset

Skip this amount of requests in the response.

INTEGER

Response

Name Description Type
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
requestIds Request IDs returned by the view. ARRAY
offset This amount of request were skipped in the response. 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
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
view_id required

View ID.

INTEGER
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

Response

Name Description Type
next_page_key Hash key of the next page of results. If null, the results page retrieved is the last one. STRING
metadata Provides resource objects that are related to the primary data, including the labels of the columns from the view. ARRAY
data Contains a JSON array (with pagination, 1000 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
assigned_group_id Help desk ID. INTEGER
status_id Status ID. INTEGER
sla_incident_first_reply First response SLA of the request. STRING
closed_at Closing date in epoch. STRING
description Request description. STRING
process_id Process ID of the request if it is a workflow instance. INTEGER
date_ocurred Occurrence date in epoch. STRING
title Request title. STRING
priority_id Priority ID. INTEGER
type_id Type ID. INTEGER
last_update Last update in epoch. STRING
user_id Customer ID. INTEGER
created_at Creation date in epoch. STRING
id Request ID. INTEGER
pretty_id Request pretty ID as configured on the Service Desk instance. STRING
source_id Source ID. INTEGER
rating Stars given to the solution. If there's no rating, this field won't be shown. INTEGER
sla_incident_resolution Resolution SLA of the request. STRING
creator_id Creator ID. INTEGER
custom_fields Array with the custom fields IDs as keys and the respective values. ARRAY
closed_reason Reason of closing. 1: Solution accepted, 2: Solution expired, 3: Customer timeout, 4: Finalized workflow. INTEGER
attachments Array with the IDs of the attachments. ARRAY
comments Array with comments of the requests with the comment structure. ARRAY
category_id Category ID. INTEGER
solved_at Solution date in epoch. STRING
assigned_id Assigned agent ID. INTEGER

/internalnotes

Manages internal notes.
Creates an internal note.

Parameters

Name Description Type
object_id required

Entity ID.

INTEGER
author_id required

Author ID.

INTEGER
object_type required

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

INTEGER
description required

Note description.

STRING
title required

Note title.

STRING

Response

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

Parameters

Name Description Type
id required

Note ID.

INTEGER
author_id required

Author ID.

INTEGER

Response

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

Parameters

Name Description Type
id required

Note ID.

INTEGER
description

Note description.

STRING
title

Note title.

STRING
author_id required

Author ID.

INTEGER

Response

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

Parameters

Name Description Type
object_id

Entity ID.

INTEGER
id required

Note ID.

INTEGER
object_type

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

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

/kb.articles

Manages articles from the Knowledge Base.
Creates an article.

Parameters

Name Description Type
title required

Article title.

STRING
is_private

Mark as private. 1: Is private. 0: Is public.

BOOLEAN
attachments

Array of attachments.

ARRAY
content required

Article content.

STRING
category_id required

Category ID.

INTEGER
responsible_id

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

INTEGER
author_id required

Author ID.

INTEGER
description

Article description.

STRING

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
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
Modifies an article given a certain ID.

Parameters

Name Description Type
id required

Article ID.

INTEGER
is_private

Mark as private. 1: Is private. 0: Is public.

BOOLEAN
title

Article title.

STRING
content

Article content.

STRING
responsible_id

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

INTEGER
author_id required

Author ID.

INTEGER
category_id

Category ID.

INTEGER
description

Article description.

STRING

Response

Name Description Type
status Returns 'OK' if the article was correctly modified; or 'ERROR' if something went wrong. STRING
Lists all the articles with their properties.

Parameters

Name Description Type
limit

Number of items per page.

INTEGER
offset

Skip this number of items in the response.

INTEGER

Response

Returns an array of objects with the following structure:

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

/kb.articles.attachments

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

Array of attachments.

ARRAY
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
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
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
id Attachment ID. INTEGER
status Returns 'OK' if the query was correctly executed; or 'ERROR' if something went wrong. STRING
name Attachment Filename. STRING
url Attachment URL. 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
limit

Number of items per page.

INTEGER
category_id required

Category ID.

INTEGER
offset

Skip this num