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
resolution_time

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

INTEGER
type_id

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

INTEGER
status_id

Breaking News status ID.

INTEGER
affected_group_ids

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

ARRAY
body

Breaking News body.

TEXT
affected_helpdesk_ids

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

ARRAY
title

Breaking News title.

STRING
creator_id

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

INTEGER
id required

Breaking News ID.

INTEGER

Response

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

Parameters

Name Description Type
resolution_time

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

INTEGER
type_id required

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

INTEGER
affected_group_ids

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

ARRAY
body required

Breaking News body.

TEXT
affected_helpdesk_ids

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

ARRAY
title required

Breaking News title.

STRING
creator_id

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

INTEGER

Response

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

Breaking News ID.

INTEGER
body required

Breaking News body.

TEXT

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

/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
parent_category_id Category parent ID. INTEGER
name Category name. STRING
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
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
total Number of modified/added values. INTEGER
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
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
total Number of deleted values. INTEGER
info Description of the result. STRING
status Returns 'OK' if the custom field option was correctly deleted; or 'ERROR' if something went wrong. 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

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

Hash value of the item to modify.

STRING
key

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

STRING
name

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

STRING

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
Adds configuration to the tree type custom fields. If the key already exists, the previous value will be overwritten.

Parameters

Name Description Type
key

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

STRING
uid required

Custom field ID.

INTEGER
parent_hash

Hash value of the parent; if not set, it will be added to the root.

STRING
name required

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

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

Custom field ID.

INTEGER
hash required

Hash value of the item to modify.

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
Returns the structure of the tree type custom fields options. The hash is system internal, but it is used to make modifications.

Parameters

Name Description Type
uid required

Custom field ID.

INTEGER

Response

Returns an array of objects with the following structure:

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

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

/cf.fields.by.category

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

Parameters

Name Description Type
category_id required

Category ID.

INTEGER

Response

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

Name Description Type
uid Custom field ID. INTEGER

/cf.fields.types

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

Response

Returns an array with the following structure:

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

/cis.by.id

Manages configuration items from custom fields and shared custom fields by IDs.
Returns an array of CIs, linked through custom fields and shared custom fields, with their IDs and properties.

Parameters

Name Description Type
ci_internal_ids required

Configuration items IDs from Service Desk.

ARRAY
ci_source_id

ID of the ITAM tool integration in Service Desk.

INTEGER

Response

Returns an array of objects with the following structure:

Name Description Type
ci_internal_id Configuration item ID from Service Desk. INTEGER
ci_external_id Configuration item external source ID. 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
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
Returns all the active companies.

Parameters

Name Description Type
name

Company name.

STRING
id

Company ID.

INTEGER

Response

Returns an array of objects with the following structure:

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

/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
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
Lists all the users groups related to a company.

Parameters

Name Description Type
id required

Company ID.

INTEGER

Response

Returns an array of objects with the following structure:

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

/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
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
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
observer_users The observers’ users IDs. ARRAY
name Company name. STRING
id Company 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
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
Lists the members of a company.

Parameters

Name Description Type
id required

Company ID.

INTEGER
user_id

User ID

INTEGER

Response

Returns an array of objects with the following structure:

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

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

Group name.

STRING
id

Group ID.

INTEGER

Response

Returns an array of objects with the following structure:

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

/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
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
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
observer_users The observers’ users IDs. ARRAY
name Group name. STRING
id Group 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
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
Lists the members of a group.

Parameters

Name Description Type
id required

Group ID.

INTEGER
user_id

User ID

INTEGER

Response

Returns an array of objects with the following structure:

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

/helpdesks

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

Parameters

Name Description Type
include_deleted

True if deleted help desks should be included.

BOOLEAN
name

Help desk name.

STRING
id

Help desk ID.

INTEGER

Response

Returns an array of objects with the following structure:

Name Description Type
total_members Total of members. INTEGER
status_id Help desk status ID. INTEGER
engine_id Help desk engine ID. INTEGER
name Help desk name. STRING
id Help desk ID. INTEGER
parent_id Help desk parent 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
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
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
observer_users The observers’ users IDs. ARRAY
name Help Desk name. STRING
id Help Desk 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
total_members Total of members. INTEGER
level_order If it's a level, indicates the order. INTEGER
status_id Status ID. 1: Enabled, 2: Suspend, 3: Out time work, 4: Disabled. INTEGER
members_ids Members IDs. ARRAY
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
id Level ID. INTEGER
parent_id Parent ID. INTEGER

/incident

Manages a request.
PUT
/incident
Change attributes of a request.

Parameters

Name Description Type
priority_id

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

INTEGER
customer_id

Client ID.

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
source_id

Source ID.

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

Request title.

STRING
reassignment

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

BOOLEAN
location_id

Location ID.

INTEGER

Response

Returns an array of objects with the following structure:

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

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

INTEGER
customer_id required

Client ID.

INTEGER
description

Request description. Required for requests and Workflows with descriptions.

TEXT
attachments

Array of request's attachments.

ARRAY
category_id required

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

INTEGER
related_to

Requests IDs to link.

ARRAY
date

Occurred on timestamp in epoch format.

STRING
type_id required

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

INTEGER
source_id

Source ID.

INTEGER
title required

Request title.

STRING
creator_id required

Creator ID.

INTEGER
location_id

Location ID.

INTEGER

Response

Name Description Type
request_id ID of the created request. INTEGER
info Description of the result. STRING
status Returns 'OK' if the request was correctly created; or 'ERROR' if something went wrong. STRING
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
decoded_special_characters

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

BOOLEAN
id required

Request ID.

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

Request ID.

INTEGER
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

Response

Returns an array of objects with the following structure:

Name Description Type
approval_request_description Description of the approval. TEXT
type Type ID of the approval. 1: Predefined approval, 2: Spontaneous approval. INTEGER
status Status ID of the approval. -2: Cancelled, -1: Waiting, 0: Rejected, 1: Approved. INTEGER
approval_request_id ID of the approval template. INTEGER
id ID of the approval instance. INTEGER
author_id Author ID of the approval. 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
approval_id required

Approval ID to be accepted.

INTEGER
user_id required

ID of the user who will accept the approval.

INTEGER

Response

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

/incident.approval.add_voter

Manages the voters of an approval.
Adds a voter to an approval.

Parameters

Name Description Type
approval_id required

ID of the approval instance.

INTEGER
user_id required

Author ID of the approval.

INTEGER

Response

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

/incident.approval.cancel

Manages the cancellation of an approval.
Cancels an approval.

Parameters

Name Description Type
approval_id required

Approval ID to be cancelled.

INTEGER
user_id required

ID of the user who will cancel the approval.

INTEGER

Response

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

/incident.approval.possible_voters

Manages the users that could accept or reject the approval.
Lists users that could accept or reject the approval.

Parameters

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

Approval ID to be rejected.

INTEGER
user_id required

ID of the user will reject the approval.

INTEGER

Response

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

/incident.approval.status

Lists the statuses of the approvals.
Lists the statuses of the approvals.

Response

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

Name Description Type
id Status ID and description. ARRAY

/incident.approval.type

Lists the available approvals types.
Lists the available approvals types.

Response

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

Name Description Type
id Type ID and description. ARRAY

/incident.approval.vote_status

Lists the status of the approval votes.
Lists the status of the approval votes.

Response

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

Name Description Type
id Status ID and description. ARRAY

/incident.attachment

Manages the attachments of the requests.
Returns the requested attachment.

Parameters

Name Description Type
id required

Attachment ID.

INTEGER

Response

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

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

Request ID.

INTEGER
author_id required

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

INTEGER
users_id

Users IDs.

ARRAY
user_id

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

Request ID.

INTEGER
is_solution

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

BOOLEAN
customer_visible

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

BOOLEAN
attachments

Attachments IDs.

ARRAY
author_id required

Author ID.

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

Request ID.

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

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

BOOLEAN

Response

Returns an array of objects with the following structure:

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

/incident.custom_approval

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

Parameters

Name Description Type
request_id required

Request ID.

INTEGER
approval_id required

Custom approval ID.

INTEGER
author_id required

Author ID of the approval request.

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

Request ID.

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 the approval templates that a request has, using the approval ID as key and values with the following structure:

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

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

Request ID.

INTEGER
author_id required

Author ID.

INTEGER
custom_field_uid required

Custom field UID.

INTEGER
values required

Array of values. If only one is required, only the first will be processed. If you are sending files, here you should list the names (with extension) of the files.

ARRAY

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

Parameters

Name Description Type
request_id required

Request ID.

INTEGER
author_id required

Author 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

/incident.external_entity

Manages the external entities linked to a request.
Links a request to an external entity.

Parameters

Name Description Type
request_id required

Request ID.

INTEGER
external_entity_id required

External entity ID.

INTEGER
external_entity_ref_id

External entity reference ID.

STRING

Response

Name Description Type
info Description of the result. STRING
link_id ID of the created relation. STRING
status Returns 'OK' if the external entity was correctly linked; or 'ERROR' if something went wrong. 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
status Entity status. 1: Enabled, 0: Deleted. BOOLEAN
type Entity type. Always 100. STRING
link_id Relation ID. INTEGER
ref_id External entity ID. INTEGER
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_id required

Request ID.

INTEGER
request_ids required

Request IDs to link.

ARRAY

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

Date timestamp from which the counters are picked.

INTEGER
cis_source_id required

ID of the ITAM tool integration in Service Desk.

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

Request ID.

INTEGER
author_id required

Author ID.

INTEGER
users_id

Users IDs.

ARRAY
user_id

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

Request ID.

INTEGER
group_id required

Help desk ID.

INTEGER
author_id required

Author ID.

INTEGER
agent_id

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

ID of the request to reject.

INTEGER
author_id required

ID of the user rejecting the request.

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

Keyword to search CIs.

STRING
exact_match

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

BOOLEAN

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

Request ID.

INTEGER
author_id

User ID who reopened the ticket.

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

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

INTEGER
comment

Solution comment. This parameter is required if the rating is less than 4.

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

Request ID.

INTEGER
approval_user_id required

User ID from the approval voter.

INTEGER
author_id required

Author ID.

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

Agent email.

STRING
username

Agent username.

STRING
id

Agent ID.

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

ID of the ITAM tool integration in Service Desk.

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

Customer email.

STRING
username

Customer username.

STRING
id

Customer ID.

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

Skip this number of items in the response.

INTEGER
status_id

Status ID.

INTEGER
limit

Number of items per page.

INTEGER
status_ids

Status IDs.

ARRAY

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
limit Number of items per page. INTEGER
requestIds Request IDs. ARRAY
total Total items. INTEGER
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
offset

Skip this amount of requests in the response.

INTEGER
limit

Number of items per page.

INTEGER
view_id required

View ID.

INTEGER

Response

Name Description Type
offset This amount of request were skipped in the response. INTEGER
info Description of the result. STRING
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 returned by the view. ARRAY

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

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

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

View ID.

INTEGER

Response

Name Description Type
data Contains a JSON array (with pagination, 10 requests per page) representing the primary data of the requests in the request view. ARRAY
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

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

/internalnotes

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

Parameters

Name Description Type
title

Note title.

STRING
author_id required

Author ID.

INTEGER
description

Note description.

STRING
id required

Note ID.

INTEGER

Response

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

Parameters

Name Description Type
description required

Note description.

STRING
title required

Note title.

STRING
author_id required

Author ID.

INTEGER
object_id required

Entity ID.

INTEGER
object_type required

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

INTEGER

Response

Name Description Type
Status Returns 'OK' if the internal note was correctly created; or 'ERROR' if something went wrong. STRING
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
Lists all the internal notes, or one in particular.

Parameters

Name Description Type
date_format

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

STRING
object_id

Entity ID.

INTEGER
object_type

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

INTEGER
id required

Note ID.

INTEGER

Response

Returns an array of objects with the following structure:

Name Description Type
last_author Last author ID. INTEGER
object_id Entity ID. INTEGER
created_at Creation date of the note in epoch or ISO-8601 format depending on the date_format parameter. STRING
description Note description. STRING
id Note ID. INTEGER
author_id Author ID. INTEGER
title Note title. STRING
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

/kb.articles

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

Parameters

Name Description Type
description

Article description.

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
category_id

Category ID.

INTEGER
title

Article title.

STRING
author_id required

Author ID.

INTEGER
is_private

True if the article is for internal use only.

BOOLEAN
id required

Article ID.

INTEGER

Response

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

Parameters

Name Description Type
attachments

Array of attachments.

ARRAY
description

Article description.

STRING
content required

Article content.

STRING
responsible_id

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

INTEGER
category_id required

Category ID.

INTEGER
title required

Article title.

STRING
author_id required

Author ID.

INTEGER
is_private

True if the article is for internal use only.

BOOLEAN

Response

Name Description Type
article_id Article ID. INTEGER
status Returns 'OK' if the article was correctly created; or 'ERROR' if something went wrong. STRING
DELETE
/kb.articles
Deletes an article from a given ID.

Parameters

Name Description Type
id required

Article ID.

INTEGER

Response

Name Description Type
status Returns 'OK' if the article was correctly deleted; or 'ERROR' if something went wrong. STRING
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
rating Average scoring of the article. FLOAT
attachments Array with the ID, name and URL of each attachment. ARRAY
solved_requests Amount of requests that this article helped to solve. INTEGER
content Content of the article. STRING
category_id Category ID. INTEGER
author_id Author ID. INTEGER
views Amount of views that the article has. INTEGER
last_update_date Last update date in epoch. STRING
creation_date Creation date in epoch. STRING
responsible_id Responsible ID. INTEGER
title Article title. STRING
id Article ID. INTEGER

/kb.articles.attachments

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

Parameters

Name Description Type
article_id required

Article ID.

INTEGER
author_id required

ID of the user in whose name the update of the article will be done.

INTEGER
attachments

Array of attachments.

ARRAY

Response

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

Parameters

Name Description Type
article_id required

Article ID.

INTEGER
attachment_id required

Attachment 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
url Attachment URL. STRING
id Attachment ID. INTEGER
status Returns 'OK' if the query was correctly executed; or 'ERROR' if something went wrong. STRING
name Attachment Filename. 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
rating Average scoring of the article. FLOAT
attachments Array with the ID, name and URL of each attachment. ARRAY
solved_requests Amount of requests that this article helped to solve. INTEGER
content Content of the article. STRING
category_id Category ID. INTEGER
author_id Author ID. INTEGER
views Amount of views that the article has. INTEGER
last_update_date Last update date in epoch. STRING
creation_date Creation date in epoch. STRING
responsible_id Responsible ID. INTEGER
title Article title. STRING
id Article ID. INTEGER

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

/kb.articles.by.keywords

Manages Knowledge Base articles by keywords.
Searches for articles by keywords.

Parameters

Name Description Type
keywords required

Keywords to search.

STRING
min_search_scoring

Minimum search scoring from 0 to 1, which measures the accuracy of the search results.

FLOAT
limit

Number of results, 25 by default.

INTEGER

Response

Returns an array of objects with the following structure:

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

/kb.categories

Manages Knowledge Base categories.
Modifies a Knowledge Base category.

Parameters

Name Description Type
name

Category name.

STRING
id required

Category ID.

INTEGER
parent_id

Category parent ID.

INTEGER

Response

Name Description Type
status Returns 'OK' if the category was correctly modified; or 'ERROR' if something went wrong. STRING
Creates a new Knowledge Base category.

Parameters

Name Description Type
name required

Category name.

STRING
parent_id required

Category Parent ID.

INTEGER

Response

Name Description Type
category_id Category ID. STRING
status Returns 'OK' if the category was correctly created; or 'ERROR' if something went wrong. STRING
Deletes a Knowledge Base category.

Parameters

Name Description Type
id required

Category ID.

INTEGER

Response

Name Description Type
status Returns 'OK' if the category was correctly deleted; or 'ERROR' if something went wrong. STRING
Lists all the Knowledge Base categories.

Response

Returns an array of objects with the following structure:

Name Description Type
name Category name. STRING
id Category ID. INTEGER
parent_id Category parent ID. INTEGER

/kb.categories.by.ids

Manages Knowledge Base categories by IDs.
Lists Knowledge Base categories by some given IDs.

Parameters

Name Description Type
ids required

Category IDs.

ARRAY

Response

Returns an array of objects with the following structure:

Name Description Type
name Category name. STRING
id Category ID. INTEGER
parent_id Category parent ID. INTEGER

/levels

Retrieves help desks' levels.
GET
/levels
Returns all active help desks' levels, or one in particular.

Parameters

Name Description Type
include_deleted

Set it to 'false' to exclude deleted levels. By default, it will retrieve deleted levels.

BOOLEAN
id

Level ID.

INTEGER

Response

Returns an array of objects or one object with the following structure:

Name Description Type
total_members Total amount of members that the level has. INTEGER
level_order Level order. INTEGER
status_id Status ID. 1: Enabled, 2: Suspend, 3: Out time work, 4: Disabled. INTEGER
members_ids List of members IDs that the level has. ARRAY
engine_id Engine ID. 1: Round robin, 2: By load, 3: Free, 4: Manual. INTEGER
id Level ID. INTEGER

/levels.observers

Manages help desk levels observers.
Add users as observers to a help desk level.

Parameters

Name Description Type
observer_users required

Users IDs to be added as observers.

ARRAY
id required

Level ID.

INTEGER

Response

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

Parameters

Name Description Type
observer_users required

Users IDs to be removed as observers.

ARRAY
id required

Level ID.

INTEGER

Response

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

Parameters

Name Description Type
ids

Level 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
observer_users The observers’ users IDs. ARRAY
name Level name. STRING
id Level ID. INTEGER

/locations

Manages locations.
POST
/locations
Creates a location.

Parameters

Name Description Type
name required

Location name.

STRING
parent_id

Parent location ID.

INTEGER

Response

Name Description Type
id Location ID. INTEGER
DELETE
/locations
Erases an existing location and its sublocations.

Parameters

Name Description Type
id required

Location ID.

INTEGER

Response

Name Description Type
status Returns 'OK' if the location was correctly deleted; or 'ERROR' if something went wrong. STRING
Returns all active locations, or one in particular.

Parameters

Name Description Type
id

Location ID.

INTEGER

Response

Returns an array of objects with the following structure:

Name Description Type
total Number of users with this location. INTEGER
name Location name. STRING
id Location ID. INTEGER
parent_id Parent location ID. INTEGER

/locations.observers

Manages locations observers.
Add users as observers to a location.

Parameters

Name Description Type
observer_users required

Users IDs to be added as observers.

ARRAY
id required

Location ID.

INTEGER

Response

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

Parameters

Name Description Type
observer_users required

Users IDs to be removed as observers.

ARRAY
id required

Location ID.

INTEGER

Response

Name Description Type
value Returns 'true' if the users were correctly removed as observers from the location. Returns 'false' if, for any reason, they weren't removed from the location, or if the users weren't observers of the location. BOOLEAN
id User ID. INTEGER
Returns all active locations and their observers, or the observers for the specified locations.

Parameters

Name Description Type
ids

Location 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
observer_users The observers’ users IDs. ARRAY
name Location name. STRING
id Location ID. INTEGER

/locations.users

Manages the relationships between users and locations.
Adds users to a location.

Parameters

Name Description Type
users required

Users IDs linked to the location.

ARRAY
id required

Location ID.

INTEGER

Response

Returns an array of objects with the following structure:

Name Description Type
value Returns 'true' if the user was correctly associated with the location or 'false' if it wasn't. BOOLEAN
id Location ID. INTEGER
Removes users from a location.

Parameters

Name Description Type
users required

Users IDs to be removed from the location.

ARRAY
id required

Location ID.

INTEGER

Response

Returns an array of objects with the following structure:

Name Description Type
value Returns 'true' if the user was correctly removed from the location or 'false' if it wasn't. BOOLEAN
id Location ID. INTEGER
Lists the members of a location.

Parameters

Name Description Type
id required

Location ID.

INTEGER
user_id

User ID

INTEGER

Response

Returns an array of objects with the following structure:

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

/sd.version

Returns the current version of the Service Desk instance.
Returns the current version of the Service Desk instance.

Response

Returns a string with the current version of Service Desk.

Name Description Type
version Service Desk version. STRING

/timetracking

Retrieves time tracking records.
DELETE
/timetracking
Deletes a time log entry from a request.

Parameters

Name Description Type
request_id required

Request ID.

INTEGER
timetracking_id required

Time tracking entry ID

INTEGER
user_id required

Author ID.

INTEGER

Response

Name Description Type
status Returns 'OK' if the time tracking entry was correctly deleted; or 'ERROR' if something went wrong. STRING
Lists all the available time tracking records within a specific time interval or a request ID.

Parameters

Name Description Type
request_id

Request ID. Required if the from parameter is not provided.

INTEGER
date_format

Indicate the date format. The available formats are 'iso8601noT' or 'iso8601'. If null, 'iso8601noT' format is returned, witch is ISO-8601 no T (YYYY-mm-dd H:i).

STRING
to

Ending date and time of the interval (must be in ISO-8601 format). If it's not specified, the current time will be used.

STRING
from

Initial date and time of the interval (must be in ISO-8601 format). Required if the request_id parameter is not provided.

STRING

Response

Returns an array of objects with the following structure:

Name Description Type
incident Request ID. INTEGER
to Ending date and time of the interval (in ISO 8601 format). STRING
comment Comment of the logged period. STRING
timetracking_id Time tracking entry ID. INTEGER
total Total amount of time in seconds. STRING
timetracking_category_id Time tracking category ID. INTEGER
from Initial date and time of the interval (in ISO 8601 format). STRING
status Time tracking entry status. 1: Enabled, 0: Deleted. INTEGER
user_id Author ID. INTEGER

/timetracking.attributes.category

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

Parameters

Name Description Type
id

Time tracking category ID.

INTEGER

Response

Name Description Type
cost_per_hour Cost of a working hour under the category. FLOAT
name Time tracking category name. STRING
id Time tracking category ID. INTEGER
parent_id Time tracking parent category ID INTEGER

/triggers

Gets user defined triggers.
GET
/triggers
If no ID is specified, it returns a list with all the user defined triggers. Otherwise, it returns the trigger matching the specific trigger ID (if it exists).

Parameters

Name Description Type
trigger_id

Trigger ID.

INTEGER

Response

Returns an array of objects with the following structure:

Name Description Type
trigger_name Trigger name. STRING
id Trigger ID. INTEGER

/triggers.executions

Gets a list of user defined triggers that were executed in the last hour.
Returns a list detailing each time that a specific trigger was executed in the last hour. If no trigger ID is provided, it returns all the times that user defined triggers were executed in the last hour.

Parameters

Name Description Type
trigger_id

Trigger ID.

INTEGER

Response

Returns an array of objects with the following structure:

Name Description Type
trigger_id Trigger ID. INTEGER
request_id ID of the affected request. INTEGER
id Execution ID. INTEGER
executed_at Execution timestamp. INTEGER

/user

Manages users.
PUT
/user
Updates the info of a user.

Parameters

Name Description Type
username

Username.

STRING
localization

Localization of the user.

STRING
department

User department.

STRING
doc

User national ID number.

STRING
city

User city.

STRING
other

User secondary phone number.

STRING
fax

User fax number.

STRING
country

User country.

STRING
office

User office phone number.

STRING
lastname

User lastname.

STRING
position

User position.

STRING
birthday

User birthday.

STRING
mobile

User mobile phone number.

STRING
language

User language. es: Español, en: English (US), en_GB: English (UK), pt: Português, fr: Français, de: Deutsch, ca: Català, it: Italiano.

STRING
name

User name.

STRING
employee_number

User employee number.

STRING
other-email

User secondary email address.

STRING
manager_id

User's manager ID.

INTEGER
email

User email address.

STRING
phone

User phone number.

STRING
id required

User ID.

INTEGER
address

User home address.

STRING

Response

Name Description Type
status Returns 'OK' if the user was correctly updated; or 'ERROR' if something went wrong. STRING
POST
/user
Creates a new user.

Parameters

Name Description Type
username required

Username.

STRING
position

User position.

STRING
department

User department.

STRING
send_set_password_email

If true, the user will receive an email with a link to set their password.

BOOLEAN
doc

User national ID number.

STRING
city

User city.

STRING
pass

User password.

STRING
other

User secondary phone number.

STRING
fax

User fax number.

STRING
country

User country.

STRING
office

User office phone number.

STRING
lastname required

User lastname.

STRING
localization

Localization of the user.

STRING
birthday

Birthday of the user.

STRING
is_external

An external user can't login to the system and can only interact with it via email.

BOOLEAN
mobile

User mobile phone number.

STRING
force_password_change

If true, the user will be forced to change their password on the next login.

BOOLEAN
name required

User name.

STRING
employee_number

User employee number.

STRING
other-email

User secondary email address.

STRING
manager_id

User's manager ID.

INTEGER
email required

User email address.

STRING
phone

User phone number.

STRING
address

User home address.

STRING

Response

Name Description Type
username Username. STRING
is_deleted Returns 'true' if the user has been deleted. BOOLEAN
role_name User’s role. STRING
position User position. STRING
other_email User secondary email address. STRING
user_type User’s type. Returns 1 if the user is an agent and 2 if it is an end user. INTEGER
department User department. STRING
doc User national ID number. STRING
city User city. STRING
other User secondary phone number. STRING
fax User fax number. STRING
country User country. STRING
office User office phone number. STRING
lastname User lastname. STRING
email User email address. STRING
birthday User birthday. STRING
type User type: 1: System, 2: LDAP, 3: Webservice, 4: Customer, 5: Mailbox. INTEGER
is_external Returns 'true' if the user is external. BOOLEAN
mobile User mobile phone number. STRING
name User name. STRING
employee_number User's employee number. STRING
address User home address. STRING
manager_id User's manager ID. INTEGER
location User localization. STRING
is_disabled Returns 'true' if the user has been disabled. BOOLEAN
phone User phone number. STRING
id User ID. INTEGER
DELETE
/user
Deletes a user.

Parameters

Name Description Type
id required

User ID.

INTEGER

Response

Name Description Type
status Returns 'OK' if the user was correctly deleted; or 'ERROR' if something went wrong. STRING
GET
/user
Returns the info of a user.

Parameters

Name Description Type
include_disabled

Indicate if disabled users should be included. True if they should be included and false if not. If this parameter is not provided then disabled users won't be returned.

BOOLEAN
id required

User ID.

INTEGER

Response

Name Description Type
username Username. STRING
is_deleted Returns 'true' if the user has been deleted. BOOLEAN
role_name User’s role. STRING
position User position. STRING
other_email User secondary email address. STRING
user_type User’s type. Returns 1 if the user is an agent and 2 if it is an end user. INTEGER
department User department. STRING
doc User national ID number. STRING
city User city. STRING
other User secondary phone number. STRING
fax User fax number. STRING
country User country. STRING
office User office phone number. STRING
lastname User lastname. STRING
email User email address. STRING
birthday User birthday. STRING
type User type: 1: System, 2: LDAP, 3: Webservice, 4: Customer, 5: Mailbox. INTEGER
is_external Returns 'true' if the user is external. BOOLEAN
mobile User mobile phone number. STRING
name User name. STRING
employee_number User's employee number. STRING
address User home address. STRING
manager_id User's manager ID. INTEGER
location User localization. STRING
is_disabled Returns 'true' if the user has been disabled. BOOLEAN
phone User phone number. STRING
id User ID. INTEGER

/user.by

Fetches users by username or email.
GET
/user.by
Retrieves the user matching the username or email and displays some basic information about the user. At least one of the input parameters is required.

Parameters

Name Description Type
username

Username.

STRING
email

User email address.

STRING

Response

Name Description Type
username Username. STRING
is_deleted Returns 'true' if the user has been deleted. BOOLEAN
role_name User’s role. STRING
position User position. STRING
other_email User secondary email address. STRING
user_type User’s type. Returns 1 if the user is an agent and 2 if it is an end user. INTEGER
department User department. STRING
doc User national ID number. STRING
city User city. STRING
other User secondary phone number. STRING
fax User fax number. STRING
country User country. STRING
office User office phone number. STRING
lastname User lastname. STRING
email User email address. STRING
birthday User birthday. STRING
type User type: 1: System, 2: LDAP, 3: Webservice, 4: Customer, 5: Mailbox. INTEGER
is_external Returns 'true' if the user is external. BOOLEAN
mobile User mobile phone number. STRING
name User name. STRING
employee_number User's employee number. STRING
address User home address. STRING
manager_id User's manager ID. INTEGER
location User localization. STRING
is_disabled Returns 'true' if the user has been disabled. BOOLEAN
phone User phone number. STRING
id User ID. INTEGER

/user.convert

Changes the user type by converting it from external into internal user.
Changes the user from external into internal and sends an email to the user requesting a new password.

Parameters

Name Description Type
id required

User ID.

INTEGER

Response

Name Description Type
status Returns 'OK' if the user was successfully converted from external into internal; or 'ERROR' if something went wrong. STRING

/user.disable

Disables a user.
Disables a user.

Parameters

Name Description Type
id required

User ID.

INTEGER

Response

Name Description Type
status Returns 'OK' if the user was successfully disabled; or 'ERROR' if something went wrong. STRING

/user.enable

Enables a user.
Enables a user.

Parameters

Name Description Type
id required

User ID.

INTEGER

Response

Name Description Type
status Returns 'OK' if the user was successfully enabled; or 'ERROR' if something went wrong. STRING

/user.password

Changes the password of a user.
Changes the password of a user.

Parameters

Name Description Type
force_password_change

If true, the user will be forced to change their password on the next login.

BOOLEAN
id required

User ID.

INTEGER
password required

New password.

STRING

Response

Name Description Type
status Returns 'OK' if the password has been successfully changed; or 'ERROR' if something went wrong. STRING

/user.password.reset

Resets the user's password and sends an action required email to the user.
Sends an email to the user requesting a new password.

Parameters

Name Description Type
type required

Either 'NEW_USER' for new users or 'RESET_PASSWORD' for existing ones.

STRING
id required

User ID.

INTEGER

Response

Name Description Type
status Returns 'OK' if the password has been successfully reset; or 'ERROR' if something went wrong. STRING

/user.token

Creates a session token for a user.
Creates a new session token for the user that matches the input ID.

Parameters

Name Description Type
id required

User ID.

INTEGER

Response

Name Description Type
token The new token ID. STRING

/users

Fetches users and allows filtering by IDs.
GET
/users
Retrieves users and displays some basic information about them. It's possible to specify an array of user IDs in order to filter specific users; otherwise, it retrieves all users.

Parameters

Name Description Type
ids

Users IDs.

ARRAY

Response

Returns an array of objects with the following structure:

Name Description Type
username Username. STRING
is_deleted Returns 'true' if the user has been deleted. BOOLEAN
role_name User’s role. STRING
position User position. STRING
other_email User secondary email address. STRING
user_type User’s type. Returns 1 if the user is an agent and 2 if it is an end user. INTEGER
department User department. STRING
doc User national ID number. STRING
city User city. STRING
other User secondary phone number. STRING
fax User fax number. STRING
country User country. STRING
office User office phone number. STRING
lastname User lastname. STRING
email User email address. STRING
birthday User birthday. STRING
type User type: 1: System, 2: LDAP, 3: Webservice, 4: Customer, 5: Mailbox. INTEGER
is_external Returns 'true' if the user is external. BOOLEAN
mobile User mobile phone number. STRING
name User name. STRING
employee_number User's employee number. STRING
address User home address. STRING
manager_id User's manager ID. INTEGER
location User localization. STRING
is_disabled Returns 'true' if the user has been disabled. BOOLEAN
phone User phone number. STRING
id User ID. INTEGER

/users.by

Fetches users by username, email or any phone numbers.
GET
/users.by
Retrieves users matching username, email or any of their phone numbers and displays basic information about them.

Parameters

Name Description Type
username

Username.

STRING
page_key

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

STRING
phones

User phone number of any kind (main phone number, fax number, office phone number, mobile phone number or other phone number).

STRING
fax_phone

User fax number.

STRING
other_phone

User secondary phone number.

STRING
exact_match

Indicate if the search should return results if (and only if) there are users with an identical value to the parameter. True if the match is exact. If this parameter is not provided then the search will return any users where the search term is contained in the parameter.

BOOLEAN
employee_number

User employee number.

STRING
mobile_phone

User mobile phone number.

STRING
email

User email address.

STRING
include_disabled

Indicate if disabled users should be included. True if they should be included and false if not. If this parameter is not provided then disabled users won't be returned.

BOOLEAN
phone

User phone number.

STRING
office_phone

User office phone number.

STRING

Response

Returns an array of objects (with pagination, 10 objects per page) with the following structure:

Name Description Type
username Username. STRING
is_deleted Returns 'true' if the user has been deleted. BOOLEAN
role_name User’s role. STRING
position User position. STRING
other_email User secondary email address. STRING
user_type User’s type. Returns 1 if the user is an agent and 2 if it is an end user. INTEGER
department User department. STRING
doc User national ID number. STRING
city User city. STRING
other User secondary phone number. STRING
fax User fax number. STRING
country User country. STRING
office User office phone number. STRING
lastname User lastname. STRING
email User email address. STRING
next_page_key Hash key of the next page of results. If null, the results page retrieved is the last one. STRING
birthday User birthday. STRING
type User type: 1: System, 2: LDAP, 3: Webservice, 4: Customer, 5: Mailbox. INTEGER
is_external Returns 'true' if the user is external. BOOLEAN
mobile User mobile phone number. STRING
name User name. STRING
employee_number User's employee number. STRING
address User home address. STRING
manager_id User's manager ID. INTEGER
location User localization. STRING
is_disabled Returns 'true' if the user has been disabled. BOOLEAN
phone User phone number. STRING
id User ID. INTEGER

/users.groups

Retrieves user's groups, companies, helpdesks and locations.
Returns the user's groups, companies, helpdesks and locations.

Parameters

Name Description Type
ids required

Users IDs.

ARRAY

Response

Returns an array of objects with the following structure:

Name Description Type
username Username. STRING
groups Array with the user groups. ARRAY
groups_observed Array with the user observed groups. ARRAY
helpdesks_observed Array with the user observed helpdesks. ARRAY
locations_observed Array with the user observed locations. ARRAY
companies_observed Array with the user observed companies. ARRAY
companies Array with the user companies. ARRAY
locations Array with the user locations. ARRAY
email User email address. STRING
id User ID. INTEGER
helpdesks Array with the user helpdesks/levels. ARRAY

/wf.deploy

Deploys a workflow.
Deploys the last version of the workflow.

Parameters

Name Description Type
workflow_id required

ID of the workflow to be deployed.

INTEGER

Response

Name Description Type
description Confirmation message. INTEGER
workflow_id ID of the deployed workflow. INTEGER
status Returns 'OK' if the workflow was correctly deployed; or 'ERROR' if something went wrong. STRING

/wf.initialfields.by.category

Lists the initial fields needed to create a request from a workflow.
Lists the initial fields needed to create a request from a workflow.

Parameters

Name Description Type
category_id required

ID of the category related to a workflow.

INTEGER

Response

Name Description Type
category_id ID of the category related to a workflow. INTEGER
associated_workflow_name Name of the associated workflow. STRING
associated_workflow_id ID of the associated workflow. INTEGER
workflow_initial_fields ARRAY with all the properties each field has. ARRAY