InvGate Service Management Developer Manual

Manages the Breaking News.

PUT

/breakingnews

Modifies a set of Breaking News.

Parameters

Name	Description	Type
title	Breaking News title.	`STRING`
status_id	Breaking News status ID. 1: Open, 2: Closed.	`INTEGER`
type_id	Type ID of the breaking news based on importance. 1: High, 2: Medium, 3: Low.	`INTEGER`
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`
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`
creator_id	ID of the Breaking News' creator. If none is provided then it will be the system.	`INTEGER`
resolution_time	Estimated resolution time. Must be a timestamp (epoch format).	`INTEGER`

Response

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

GET

/breakingnews

Returns the requested Breaking News.

Parameters

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

Response

Name	Description	Type
status_id	Breaking News status ID.	`INTEGER`
title	Breaking News title.	`STRING`
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`
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`

POST

/breakingnews

Creates Breaking News.

Parameters

Name	Description	Type
affected_group_ids	Groups that are affected. It is required unless there is at least one help desk affected.	`ARRAY`
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`
title required	Breaking News title.	`STRING`
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`
major_incident_id	ID of the major incident associated with the Breaking News.	`INTEGER`
creator_id	ID of the Breaking News' creator. If none is provided then it will be the system.	`INTEGER`

Response

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

Lists the Breaking News.

GET

/breakingnews.all

Lists all the Breaking News.

Parameters

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

Response

Returns an array of objects with the following structure:

Name	Description	Type
status_id	Breaking News status ID.	`INTEGER`
title	Breaking News title.	`STRING`
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`
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`

Lists the status of the Breaking News.

GET

/breakingnews.attributes.status

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

Parameters

Name	Description	Type
id	Status ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

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

Lists all the Breaking News importance types.

GET

/breakingnews.attributes.type

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

Parameters

Name	Description	Type
id	Importance type ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

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

Manages the updates of the Breaking News.

GET

/breakingnews.status

Returns the updates of the requested Breaking News.

Parameters

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

Response

Returns an array of objects with the following structure:

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

POST

/breakingnews.status

Creates a new update to the given Breaking News.

Parameters

Name	Description	Type
is_solution	Send 1 to close Breaking News. Send 0 to keep open. Default: 0.	`BOOLEAN`
body required	Breaking News body.	`TEXT`
creator_id	ID of the Breaking News' creator. If none is provided then it will be the system.	`INTEGER`
id required	Breaking News ID.	`INTEGER`

Response

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

Lists all the categories with optional text search and pagination.

GET

/categories

Lists all the categories, or the required one if an ID is provided. Supports text search and pagination.

Parameters

Name	Description	Type
search	Search text for category names.	`STRING`
page_size	Number of items per page. Default 20, max 500.	`INTEGER`
page	Page number for pagination.	`INTEGER`
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`

Manages the settings of the list type custom fields.

DELETE

/cf.field.options.list

Erases keys from the list type custom fields configuration.

Parameters

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

Response

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

GET

/cf.field.options.list

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

Parameters

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

Response

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

POST

/cf.field.options.list

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

Parameters

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

Response

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

Lists the configuration of the list type custom fields.

GET

/cf.field.options.list.config

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

Parameters

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

Response

Name	Description	Type
count	The count of configurations in the response.	`INTEGER`
configurations	Returns an array with the list of options with its configurations for the custom field.	`ARRAY`

Manages the settings of the tree type custom fields.

PUT

/cf.field.options.tree

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

Parameters

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

Response

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

DELETE

/cf.field.options.tree

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

Parameters

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

Response

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

GET

/cf.field.options.tree

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

Parameters

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

Response

Returns an array of objects with the following structure:

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

POST

/cf.field.options.tree

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

Parameters

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

Lists the active custom fields.

GET

/cf.fields.all

Returns a list of all the active custom fields.

Response

Returns an array of objects with the following structure:

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

Custom fields by category.

GET

/cf.fields.by.category

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

Parameters

Name	Description	Type
category_id required	Category ID.	`INTEGER`

Response

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

Name	Description	Type
uid	Custom field ID.	`INTEGER`

Lists the active shared custom fields.

GET

/cf.fields.shared.all

Returns a list of all the active shared custom fields.

Response

Returns an array of objects with the following structure:

Name	Description	Type
description	Shared custom field description.	`TEXT`
uid	Shared custom field ID.	`INTEGER`
type	Shared custom field type ID.	`INTEGER`
label	Shared custom field label.	`STRING`

Lists all the supported custom field types.

GET

/cf.fields.types

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

Response

Returns an array with the following structure:

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

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

GET

/cis.by.id

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

Parameters

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

Response

Returns an array of objects with the following structure:

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

Manages companies.

PUT

/companies

Modifies an existing company.

Parameters

Name	Description	Type
external_id	External ID.	`STRING`
name	Company name.	`STRING`
id required	Company ID.	`INTEGER`

Response

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

DELETE

/companies

Erases an existing company.

Parameters

Name	Description	Type
id required	Company ID.	`INTEGER`

Response

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

GET

/companies

Returns all the active companies.

Parameters

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

Response

Returns an array of companies with the following structure:

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

POST

/companies

Creates a new company.

Parameters

Name	Description	Type
external_id	External ID.	`STRING`
name required	Company name.	`STRING`

Response

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

Manages the relationships between users groups and companies.

DELETE

/companies.groups

Suppresses the relationship between a users group and a company.

Parameters

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

Response

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

Name	Description	Type
id	Group ID.	`ARRAY`

GET

/companies.groups

Lists all the users groups related to a company.

Parameters

Name	Description	Type
id required	Company ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

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

POST

/companies.groups

Relates a users group to a company.

Parameters

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

Response

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

Name	Description	Type
id	Group ID.	`ARRAY`

Manages companies observers.

DELETE

/companies.observers

Removes observers from a company.

Parameters

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

Response

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

GET

/companies.observers

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

Parameters

Name	Description	Type
ids	Company IDs.	`ARRAY`

Response

Returns an array of objects with the following structure:

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

POST

/companies.observers

Add users as observers to a company.

Parameters

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

Response

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

Manages the relationships between users and companies.

DELETE

/companies.users

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

Parameters

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

Response

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

Name	Description	Type
id	User ID.	`ARRAY`

GET

/companies.users

Lists the members of a company.

Parameters

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

Response

Returns an array of objects with the following structure:

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

POST

/companies.users

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

Parameters

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

Response

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

Name	Description	Type
id	User ID.	`ARRAY`

Manages data exports.

GET

/data.export

Returns the data export URL.

Parameters

Name	Description	Type
id required	The UUID of the data export report, obtained during report configuration.	`STRING`

Response

Name	Description	Type
status	Returns 'OK' if the data export report was correctly executed; or 'ERROR' if something went wrong.	`STRING`
url	Data export report URL.	`STRING`

Manages groups.

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`

POST

/groups

Creates a group of users.

Parameters

Name	Description	Type
name required	Group name.	`STRING`

Response

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

Manages groups observers.

DELETE

/groups.observers

Removes observers from a group.

Parameters

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

Response

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

GET

/groups.observers

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

Parameters

Name	Description	Type
ids	Group IDs.	`ARRAY`

Response

Returns an array of objects with the following structure:

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

POST

/groups.observers

Add users as observers to a group.

Parameters

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

Response

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

Manages the relationships between users and groups.

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`

GET

/groups.users

Lists the members of a group.

Parameters

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

Response

Returns an array of objects with the following structure:

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

POST

/groups.users

Adds a user to a group.

Parameters

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

Response

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

Name	Description	Type
id	User ID.	`ARRAY`

Manages the help desks.

GET

/helpdesks

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

Parameters

Name	Description	Type
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
engine_id	Help desk engine ID.	`INTEGER`
parent_id	Help desk parent ID.	`INTEGER`
name	Help desk name.	`STRING`
status_id	Help desk status ID.	`INTEGER`
id	Help desk ID.	`INTEGER`
total_members	Total of members.	`INTEGER`

Manages help desks observers.

DELETE

/helpdesks.observers

Removes observers from a help desk.

Parameters

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

Response

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

GET

/helpdesks.observers

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

Parameters

Name	Description	Type
ids	Help Desk IDs.	`ARRAY`

Response

Returns an array of objects with the following structure:

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

POST

/helpdesks.observers

Add users as observers to a help desk.

Parameters

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

Response

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

Manages help desks and levels.

GET

/helpdesksandlevels

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

Parameters

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

Manages a request.

PUT

/incident

Change attributes of a request.

Parameters

Name	Description	Type
source_id	Source ID.	`INTEGER`
category_id	Category name can be obtained calling https://releases.invgate.com/service-desk/api/#categories-GET	`INTEGER`
title	Request title.	`STRING`
priority_id	Low = 1, Medium = 2, High = 3, Urgent = 4, Critical = 5	`INTEGER`
id required	Request ID.	`INTEGER`
description	Request description.	`TEXT`
location_id	Location ID.	`INTEGER`
reassignment	Set to true to reassign the request to a help desk according to the new properties.	`BOOLEAN`
type_id	Incident = 1, Service Request = 2, Question = 3, Problem = 4, Change = 5, Major Incident = 6	`INTEGER`
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`
customer_id	Client ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
source_id	Source ID.	`INTEGER`
solved_at	Solution date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
closed_at	Closing date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
description	Request description.	`STRING`
location_id	Location ID.	`INTEGER`
process_id	Process ID of the request if it is a workflow instance.	`INTEGER`
last_update	Last update in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
status_id	Status ID.	`INTEGER`
assigned_id	Assigned agent ID.	`INTEGER`
category_id	Category ID.	`INTEGER`
title	Request title.	`STRING`
priority_id	Priority ID.	`INTEGER`
user_id	Customer ID.	`INTEGER`
id	Request ID.	`INTEGER`
created_at	Creation date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
date_ocurred	Occurrence date in epoch or ISO-8601 format depending on the date_format parameter.	`STRING`
attachments	Array with the IDs of the attachments.	`ARRAY`
type_id	Type 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`
assigned_group_id	Help desk ID.	`INTEGER`
creator_id	Creator ID.	`INTEGER`

GET

/incident

Returns the information of the given request.

Parameters

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

Response

Returns an array of objects with the following structure:

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

POST

/incident

Creates a new request in the system. To include custom fields, read this guide.

Parameters

Name	Description	Type
source_id	Source ID.	`INTEGER`
category_id required	Category name can be obtained calling https://releases.invgate.com/service-desk/api/#categories-GET	`INTEGER`
title required	Request title.	`STRING`
priority_id required	Low = 1, Medium = 2, High = 3, Urgent = 4, Critical = 5	`INTEGER`
description	Request description. Required for requests and Workflows with descriptions.	`TEXT`
location_id	Location ID.	`INTEGER`
attachments	Array of request's attachments.	`ARRAY`
type_id required	Incident = 1, Service Request = 2, Question = 3, Problem = 4, Change = 5, Major Incident = 6	`INTEGER`
related_to	Requests IDs to link.	`ARRAY`
date	Occurred on timestamp in epoch format.	`STRING`
customer_id required	Client ID.	`INTEGER`
creator_id required	Creator ID.	`INTEGER`

Response

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

Manages the approvals instances of a request.

GET

/incident.approval

Lists the approvals instances that the given request has.

Parameters

Name	Description	Type
only_pending	When set to true, it only returns pending approvals.	`BOOLEAN`
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 objects with the following structure:

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

Manages the acceptance of an approval.

PUT

/incident.approval.accept

Accepts an approval.

Parameters

Name	Description	Type
approval_id required	Approval ID to be accepted.	`INTEGER`
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`

Manages the voters of an approval.

POST

/incident.approval.add_voter

Adds a voter to an approval.

Parameters

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

Response

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

Manages the cancellation of an approval.

PUT

/incident.approval.cancel

Cancels an approval.

Parameters

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

Response

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

Manages the users that could accept or reject the approval.

GET

/incident.approval.possible_voters

Lists users that could accept or reject the approval.

Parameters

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

Manages the rejection of an approval.

PUT

/incident.approval.reject

Rejects an approval.

Parameters

Name	Description	Type
approval_id required	Approval ID to be rejected.	`INTEGER`
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`

Lists the statuses of the approvals.

GET

/incident.approval.status

Lists the statuses of the approvals.

Response

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

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

Lists the available approvals types.

GET

/incident.approval.type

Lists the available approvals types.

Response

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

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

Lists the status of the approval votes.

GET

/incident.approval.vote_status

Lists the status of the approval votes.

Response

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

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

Manages the attachments of the requests.

GET

/incident.attachment

Returns the requested attachment.

Parameters

Name	Description	Type
id required	Attachment ID.	`INTEGER`

Response

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

Lists all the priorities.

GET

/incident.attributes.priority

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

Parameters

Name	Description	Type
id	Priority ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

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

Lists all the requests sources.

GET

/incident.attributes.source

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

Parameters

Name	Description	Type
id	Source ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

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

Lists all the status.

GET

/incident.attributes.status

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

Parameters

Name	Description	Type
id	Status ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

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

Lists all the types.

GET

/incident.attributes.type

Lists all the types. If an ID is provided, only the one that matches the specified ID will be listed. Use the status filter to include deleted types.

Parameters

Name	Description	Type
status	Filter by status: active\|deleted\|all.	`STRING`
id	Type ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
status	Type status: 'active' or 'deleted'.	`STRING`
is_system	Whether the type is a system-defined one.	`BOOLEAN`
name	Type name.	`STRING`
id	Type ID.	`INTEGER`

Manages the cancellation of a request.

POST

/incident.cancel

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`

Manages the collaborators of the requests.

GET

/incident.collaborator

Lists the collaborators IDs.

Parameters

Name	Description	Type
request_id required	Request ID.	`INTEGER`

Response

Returns an array of the collaborators' IDs.

Name	Description	Type
id	Collaborator ID.	`ARRAY`

POST

/incident.collaborator

Requests collaboration from the defined user.

Parameters

Name	Description	Type
author_id required	Author ID. Must be the ID of the user that asks for collaboration.	`INTEGER`
request_id required	Request ID.	`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`

Manages the replies from a given request.

GET

/incident.comment

Gets the replies from a given request.

Parameters

Name	Description	Type
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`
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 objects with the following structure:

Name	Description	Type
attachments	Attachment IDs.	`ARRAY`
message	Message of the comment.	`STRING`
msg_num	Number of the message in the request.	`INTEGER`
incident_id	Request ID.	`INTEGER`
reference	ID of the comment that is replying to.	`INTEGER`
id	Comment ID.	`INTEGER`
is_solution	Indicates if this comment is the solution of the request. 1: if is the solution, 0: if not.	`BOOLEAN`
author_id	Author ID.	`INTEGER`
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`

POST

/incident.comment

Adds a reply to a request.

Parameters

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

Response

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

Manages the custom approvals.

GET

/incident.custom_approval

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

POST

/incident.custom_approval

Requests a custom approval in the given request.

Parameters

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

Response

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

Manages the custom fields from a request.

DELETE

/incident.custom_field

Deletes value in the associated custom field.

Parameters

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

Response

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

PATCH

/incident.custom_field

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

Response

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

POST

/incident.custom_field

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

Parameters

Name	Description	Type
author_id required	Author ID.	`INTEGER`
request_id required	Request 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
status	Returns 'OK' if the values were correctly created; or 'ERROR' if something went wrong.	`STRING`
info	Description of the result.	`STRING`

Manages the external entities linked to a request.

GET

/incident.external_entity

Lists all the external entities linked to a request.

Parameters

Name	Description	Type
request_id required	Request ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

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

POST

/incident.external_entity

Links a request to an external entity.

Parameters

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

Response

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

Manages the requests linked to a request.

GET

/incident.link

Lists all the linked requests from a given request.

Parameters

Name	Description	Type
request_id required	Request ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

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

POST

/incident.link

Links a request to another request.

Parameters

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

Response

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

Manages the linked assets counters.

GET

/incident.linked_cis.counters.from

Returns counters with the number of incidents of each status.

Parameters

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

Response

Returns an array of objects with the following structure:

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

Manages the request's observers.

GET

/incident.observer

Lists all the IDs of the request's observers.

Parameters

Name	Description	Type
request_id required	Request ID.	`INTEGER`

Response

Returns an array with the IDs of the observers.

Name	Description	Type
user_id	User ID.	`INTEGER`

POST

/incident.observer

Adds a user as observer.

Parameters

Name	Description	Type
author_id required	Author ID.	`INTEGER`
request_id required	Request 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`

Promotes a request to a major incident.

POST

/incident.promote.to.major.incident

Promotes the given request to a major incident and returns the ID of the created major incident.

Parameters

Name	Description	Type
author_id required	User ID.	`INTEGER`
request_id required	Request ID.	`INTEGER`
confirm	confirm changes if needed.	`BOOLEAN`

Response

Returns an array of objects with the following structure:

Name	Description	Type
messages	In case of error, contains the error message.	`ARRAY`
success	Promotion Result.	`BOOLEAN`

Manages the requests reassignations to a help desk or agent.

POST

/incident.reassign

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

Parameters

Name	Description	Type
author_id required	Author ID.	`INTEGER`
request_id required	Request ID.	`INTEGER`
group_id required	Help desk 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`

Manages the rejection of a request.

POST

/incident.reject

Rejects a request.

Parameters

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

Response

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

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

POST

/incident.relate.ci.by.keyword

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

Parameters

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

Manages a request reopening.

PUT

/incident.reopen

Reopens a request.

Parameters

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

Response

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

Manages the acceptance of a request's solution.

PUT

/incident.solution.accept

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`

Manages the rejection of a request's solution.

PUT

/incident.solution.reject

Rejects the solution of a request.

Parameters

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

Response

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

Manages the spontaneous approvals from a request.

POST

/incident.spontaneous_approval

Creates a spontaneous approval.

Parameters

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

Response

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

Manages the tasks linked to a given request.

GET

/incident.tasks

Retrieves the list of tasks linked to a specified request.

Parameters

Name	Description	Type
request_id required	Request ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
wf_stage_id	ID of the workflow stage if the task is related to one.	`STRING`
name	Task name.	`STRING`
helpdesk_id	Assigned helpdesk ID.	`INTEGER`
created_at	Task creation date (timestamp).	`INTEGER`
agent_id	Assigned agent ID.	`INTEGER`
status	Task status: 0 = OPEN, 1 = FINISHED, 2 = DELETED, 3 = SKIPPED.	`INTEGER`
is_predefined	Indicates if it comes predefined from a workflow.	`BOOLEAN`
expiration_date	Due date of the task (timestamp).	`INTEGER`
linked_request_id	ID of the linked request (if any).	`INTEGER`
completed_at	Task completion date (timestamp).	`INTEGER`
task_id	Task ID.	`INTEGER`
description	Task description.	`STRING`
is_required	Whether the task is required or not.	`BOOLEAN`
assignment_type	Assignment type: 1 = USER, 2 = HELPDESK.	`INTEGER`

Manages the agent waiting status of the requests.

POST

/incident.waitingfor.agent

Sets the agent waiting status to the request.

Parameters

Name	Description	Type
request_id required	Request ID.	`INTEGER`

Response

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

Manages the customer waiting status of the requests.

POST

/incident.waitingfor.customer

Sets the waiting for customer status to the request.

Parameters

Name	Description	Type
request_id required	Request ID.	`INTEGER`

Response

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

Manages the waiting for date status of the requests.

POST

/incident.waitingfor.date

Sets the waiting for date status to the request.

Parameters

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

Response

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

Manages the waiting for external entities status of the requests.

POST

/incident.waitingfor.external_entity

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

Parameters

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

Response

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

Manages the waiting for another request status.

POST

/incident.waitingfor.incident

Sets the request in the waiting for another request status.

Parameters

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

Response

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

Manages the requests.

GET

/incidents

Lists the requests.

Parameters

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

Response

Returns an array of objects with the following structure:

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

Open requests by agent.

GET

/incidents.by.agent

Lists the requests from a given agent.

Parameters

Name	Description	Type
comments	When set to true, it includes the comments of the request.	`BOOLEAN`
limit	Number of items per page.	`INTEGER`
page_key	Hash key of the results page to retrieve. If null, the first page of results will be returned.	`STRING`
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
source_id	Source ID.	`INTEGER`
comments	Array with comments of the requests with the comment structure.	`ARRAY`
solved_at	Solution date in epoch.	`STRING`
sla_incident_resolution	Resolution 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`
pretty_id	Request pretty ID as configured on the Service Management instance.	`STRING`
next_page_key	Hash key of the next page of results. If null, the results page retrieved is the last one.	`STRING`
last_update	Last update in epoch.	`STRING`
sla_incident_first_reply	First response SLA of the request.	`STRING`
date_ocurred	Occurrence date in epoch.	`STRING`
request_customer_sentiment_initial	Initial customer sentiment for the request. "positive", "neutral", "negative"	`STRING`
status_id	Status ID.	`INTEGER`
assigned_id	Assigned agent ID.	`INTEGER`
category_id	Category ID.	`INTEGER`
title	Request title.	`STRING`
priority_id	Priority ID.	`INTEGER`
user_id	Customer ID.	`INTEGER`
id	Request ID.	`INTEGER`
created_at	Creation date in epoch.	`STRING`
custom_fields	Array with the custom fields IDs as keys and the respective values.	`ARRAY`
attachments	Array with the IDs of the attachments.	`ARRAY`
type_id	Type ID.	`INTEGER`
closed_reason	Reason of closing. 1: Solution accepted, 2: Solution expired, 3: Customer timeout, 4: Finalized workflow.	`INTEGER`
assigned_group_id	Help desk ID.	`INTEGER`
request_customer_sentiment_current	Current customer sentiment for the request. "positive", "neutral", "negative"	`STRING`
creator_id	Creator ID.	`INTEGER`

Manages requests linked to CIs.

GET

/incidents.by.cis

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

Parameters

Name	Description	Type
group required	Name of the group the CIs belong to. Possible values are "asset", "business_application", "cloud_asset", "database". Legacy PascalCase variants (e.g. "Asset", "BusinessApplication") are also accepted.	`STRING`
ci_ids required	IDs of the CIs.	`ARRAY`
cis_source_id required	ID of the ITAM tool integration in Service Management.	`INTEGER`

Response

Returns an array of objects with the following structure:

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

Manages open requests by customer.

GET

/incidents.by.customer

Lists the open requests from a customer.

Parameters

Name	Description	Type
comments	When set to true, it includes the comments of the request.	`BOOLEAN`
limit	Number of items per page.	`INTEGER`
page_key	Hash key of the results page to retrieve. If null, the first page of results will be returned.	`STRING`
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
source_id	Source ID.	`INTEGER`
comments	Array with comments of the requests with the comment structure.	`ARRAY`
solved_at	Solution date in epoch.	`STRING`
sla_incident_resolution	Resolution 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`
pretty_id	Request pretty ID as configured on the Service Management instance.	`STRING`
next_page_key	Hash key of the next page of results. If null, the results page retrieved is the last one.	`STRING`
last_update	Last update in epoch.	`STRING`
sla_incident_first_reply	First response SLA of the request.	`STRING`
date_ocurred	Occurrence date in epoch.	`STRING`
request_customer_sentiment_initial	Initial customer sentiment for the request. "positive", "neutral", "negative"	`STRING`
status_id	Status ID.	`INTEGER`
assigned_id	Assigned agent ID.	`INTEGER`
category_id	Category ID.	`INTEGER`
title	Request title.	`STRING`
priority_id	Priority ID.	`INTEGER`
user_id	Customer ID.	`INTEGER`
id	Request ID.	`INTEGER`
created_at	Creation date in epoch.	`STRING`
custom_fields	Array with the custom fields IDs as keys and the respective values.	`ARRAY`
attachments	Array with the IDs of the attachments.	`ARRAY`
type_id	Type ID.	`INTEGER`
closed_reason	Reason of closing. 1: Solution accepted, 2: Solution expired, 3: Customer timeout, 4: Finalized workflow.	`INTEGER`
assigned_group_id	Help desk ID.	`INTEGER`
request_customer_sentiment_current	Current customer sentiment for the request. "positive", "neutral", "negative"	`STRING`
creator_id	Creator ID.	`INTEGER`

Manages open requests by help desk.

GET

/incidents.by.helpdesk

Lists the open requests from a help desk.

Parameters

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

Response

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

Manages open requests by sentiment.

GET

/incidents.by.sentiment

Lists the open requests from a sentiment.

Parameters

Name	Description	Type
sentiment_id	Sentiment ID. [negative\|positive\|neutral]	`STRING`
offset	Skip this number of items in the response.	`INTEGER`
limit	Number of items per page.	`INTEGER`
sentiment_ids	Sentiments IDs.	`ARRAY`

Response

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

Manages the open requests by status.

GET

/incidents.by.status

Lists all open requests matching the status specified by parameter.

Parameters

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

Response

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

Manages the requests from a given view ID.

GET

/incidents.by.view

Lists the requests from a view ID.

Parameters

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

Response

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

Lists the requests with their details from a view ID.

GET

/incidents.details.by.view

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`

Manages the requests that were created within the last hour.

GET

/incidents.last.hour

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

Parameters

Name	Description	Type
limit	Number of items per page.	`INTEGER`
page_key	Hash key of the results page to retrieve. If null, the first page of results will be returned.	`STRING`

Response

Returns an array of objects with the following structure:

Name	Description	Type
source_id	Source ID.	`INTEGER`
comments	Array with comments of the requests with the comment structure.	`ARRAY`
solved_at	Solution date in epoch.	`STRING`
sla_incident_resolution	Resolution SLA of the request.	`STRING`
closed_at	Closing date in epoch.	`STRING`
description	Request description.	`STRING`
rating	Stars given to the solution. If there's no rating, this field won't be shown.	`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 Management instance.	`STRING`
next_page_key	Hash key of the next page of results. If null, the results page retrieved is the last one.	`STRING`
last_update	Last update in epoch.	`STRING`
sla_incident_first_reply	First response SLA of the request.	`STRING`
date_ocurred	Occurrence date in epoch.	`STRING`
request_customer_sentiment_initial	Initial customer sentiment for the request. "positive", "neutral", "negative"	`STRING`
status_id	Status ID.	`INTEGER`
assigned_id	Assigned agent ID.	`INTEGER`
category_id	Category ID.	`INTEGER`
title	Request title.	`STRING`
priority_id	Priority ID.	`INTEGER`
user_id	Customer ID.	`INTEGER`
id	Request ID.	`INTEGER`
created_at	Creation date in epoch.	`STRING`
custom_fields	Array with the custom fields IDs as keys and the respective values.	`ARRAY`
attachments	Array with the IDs of the attachments.	`ARRAY`
type_id	Type ID.	`INTEGER`
closed_reason	Reason of closing. 1: Solution accepted, 2: Solution expired, 3: Customer timeout, 4: Finalized workflow.	`INTEGER`
assigned_group_id	Help desk ID.	`INTEGER`
request_customer_sentiment_current	Current customer sentiment for the request. "positive", "neutral", "negative"	`STRING`
creator_id	Creator ID.	`INTEGER`

Manages internal notes.

PUT

/internalnotes

Updates the info of an internal note.

Parameters

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

Response

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

DELETE

/internalnotes

Deletes an internal note.

Parameters

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

Response

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

GET

/internalnotes

Lists all the internal notes, or one in particular.

Parameters

Name	Description	Type
object_id	Entity 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`
id required	Note ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

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

POST

/internalnotes

Creates an internal note.

Parameters

Name	Description	Type
description required	Note description.	`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`
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`

Manages articles from the Knowledge Base.

PUT

/kb.articles

Modifies an article given a certain ID.

Parameters

Name	Description	Type
content	Article content.	`STRING`
status	Article status ID. 1: Published, 4: Draft, 5: Archived. If null, the status is left unchanged. With KB article versioning enabled, content changes follow the versioned editor: without status, a published article publishes the new version, and a draft or archived article saves a draft; 4 saves the content as a draft without unpublishing the current version; 1 publishes it. Publishing in a category whose approvers must approve the author's versions sends the version to approval instead. Responds 409 if another user has the article open in the editor.	`INTEGER`
category_id	Category ID.	`INTEGER`
title	Article title.	`STRING`
id required	Article ID.	`INTEGER`
description	Article description.	`STRING`
is_private	Mark as private. 1: Is private. 0: Is public. With KB article versioning enabled, if null the visibility is left unchanged.	`BOOLEAN`
author_id required	Author ID.	`INTEGER`
responsible_id	Article responsible. If it's null, the assigned responsible user will be the same as the author; with KB article versioning enabled, it is left unchanged.	`INTEGER`
external_id	External ID of the article. Optional; must be unique among articles. Send an empty string to clear it. If null, it is left unchanged.	`STRING`

Response

Name	Description	Type
status	Returns 'OK' if the article was correctly modified; or 'ERROR' if something went wrong.	`STRING`
version	Number of that version (e.g. "2.0" or "1.1"). Null when KB article versioning is disabled.	`STRING`
version_id	ID of the newest version of the article: the draft in progress if there is one, otherwise the current version. Null when KB article versioning is disabled.	`INTEGER`
version_status	Status of that version: "published", "draft", "pending_approval", "rejected" or "approved". Null when KB article versioning is disabled.	`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`

GET

/kb.articles

Lists all the articles with their properties.

Parameters

Name	Description	Type
offset	Skip this number of items in the response.	`INTEGER`
sort_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, articles will be returned sorted in ascending order.	`STRING`
order_by	Attribute upon which the sorting of the results will be performed. "last_update_date" if they should be sorted by the articles last update date. If null, articles will be returned sorted by ID	`STRING`
limit	Number of items per page.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
content	Content of the article.	`STRING`
category_id	Category ID.	`INTEGER`
title	Article title.	`STRING`
id	Article ID.	`INTEGER`
views	Amount of views that the article has.	`INTEGER`
is_private	If the article is private or not.	`BOOLEAN`
external_id	External ID of the article.	`STRING`
solved_requests	Amount of requests that this article helped to solve.	`INTEGER`
responsible_id	Responsible ID.	`INTEGER`
creation_date	Creation date in epoch.	`STRING`
status	Article status ID. 1: Published, 4: Draft, 5: Archived.	`INTEGER`
attachments	Array with the ID, name and URL of each attachment.	`ARRAY`
last_update_date	Last update date in epoch.	`STRING`
rating	Average scoring of the article.	`FLOAT`
author_id	Author ID.	`INTEGER`
source	Creation origin of the article: web, manual, ai, api, initial_setup, import or external_sync. Read-only.	`STRING`

POST

/kb.articles

Creates an article.

Parameters

Name	Description	Type
content required	Article content.	`STRING`
status	Article status ID. 1: Published, 4: Draft. If null, the article is created as published. With KB article versioning enabled, publishing in a category whose approvers must approve the author's versions creates the article as a draft and sends its version to approval.	`INTEGER`
attachments	Array of attachments.	`ARRAY`
category_id required	Category ID.	`INTEGER`
title required	Article title.	`STRING`
is_private	Mark as private. 1: Is private. 0: Is public.	`BOOLEAN`
description	Article description.	`STRING`
external_id	External ID of the article. Optional; must be unique among articles.	`STRING`
author_id required	Author ID.	`INTEGER`
responsible_id	Article responsible. If it's null, the assigned responsible user will be the same as the author.	`INTEGER`

Response

Name	Description	Type
status	Returns 'OK' if the article was correctly created; or 'ERROR' if something went wrong.	`STRING`
version	Number of that version (e.g. "2.0" or "1.1"). Null when KB article versioning is disabled.	`STRING`
article_id	Article ID.	`INTEGER`
version_id	ID of the newest version of the article: the draft in progress if there is one, otherwise the current version. Null when KB article versioning is disabled.	`INTEGER`
version_status	Status of that version: "published", "draft", "pending_approval", "rejected" or "approved". Null when KB article versioning is disabled.	`STRING`

Manages the attachments from a Knowledge Base article.

DELETE

/kb.articles.attachments

Deletes an attachment from an article.

Parameters

Name	Description	Type
attachment_id required	Attachment ID.	`INTEGER`
author_id	ID of the user in whose name the attachment is removed. With KB article versioning enabled, removing an attachment creates a new version like any content change; if null, the System user is used.	`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`
version	Number of that version (e.g. "2.0" or "1.1"). Null when KB article versioning is disabled.	`STRING`
version_id	ID of the newest version of the article after the change. Null when KB article versioning is disabled.	`INTEGER`
version_status	Status of that version: "published", "draft", "pending_approval", "rejected" or "approved". Null when KB article versioning is disabled.	`STRING`

GET

/kb.articles.attachments

Lists the attachments from an article.

Parameters

Name	Description	Type
article_id required	Article ID.	`INTEGER`

Response

Returns an array of objects with the following structure:

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

POST

/kb.articles.attachments

Adds attachments to an article.

Parameters

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

Response

Name	Description	Type
status	Returns 'OK' if the attachment was correctly added; or 'ERROR' if something went wrong.	`STRING`
version	Number of that version (e.g. "2.0" or "1.1"). Null when KB article versioning is disabled.	`STRING`
version_id	ID of the newest version of the article after the change. Null when KB article versioning is disabled.	`INTEGER`
version_status	Status of that version: "published", "draft", "pending_approval", "rejected" or "approved". Null when KB article versioning is disabled.	`STRING`

Manages Knowledge Base articles by category.

GET

/kb.articles.by.category

Lists all the articles that belong to a certain category.

Parameters

Name	Description	Type
offset	Skip this number of items in the response.	`INTEGER`
limit	Number of items per page.	`INTEGER`
category_id required	Category ID.	`INTEGER`
visibility	Visibility type of the articles to fetch. 1 => Private, 2 => Registered Users, 3 => Public.	`INTEGER`

Response

Returns an array of objects with the following structure:

Name	Description	Type
content	Content of the article.	`STRING`
category_id	Category ID.	`INTEGER`
title	Article title.	`STRING`
id	Article ID.	`INTEGER`
views	Amount of views that the article has.	`INTEGER`
is_private	If the article is private or not.	`BOOLEAN`
external_id	External ID of the article.	`STRING`
solved_requests	Amount of requests that this article helped to solve.	`INTEGER`
responsible_id	Responsible ID.	`INTEGER`
creation_date	Creation date in epoch.	`STRING`
status	Article status ID. 1: Published, 4: Draft, 5: Archived.	`INTEGER`
attachments	Array with the ID, name and URL of each attachment.	`ARRAY`
last_update_date	Last update date in epoch.	`STRING`
rating	Average scoring of the article.	`FLOAT`
author_id	Author ID.	`INTEGER`
source	Creation origin of the article: web, manual, ai, api, initial_setup, import or external_sync. Read-only.	`STRING`

Manages Knowledge Base articles by ID.

GET

/kb.articles.by.ids

Lists articles by ID.

Parameters

Name	Description	Type
ids required	Article IDs.	`ARRAY`

Response

Returns an array of objects with the following structure:

Name	Description	Type
content	Content of the article.	`STRING`
category_id	Category ID.	`INTEGER`
title	Article title.	`STRING`
id	Article ID.	`INTEGER`
views	Amount of views that the article has.	`INTEGER`
is_private	If the article is private or not.	`BOOLEAN`
external_id	External ID of the article.	`STRING`
solved_requests	Amount of requests that this article helped to solve.	`INTEGER`
responsible_id	Responsible ID.	`INTEGER`
creation_date	Creation date in epoch.	`STRING`
status	Article status ID. 1: Published, 4: Draft, 5: Archived.	`INTEGER`
attachments	Array with the ID, name and URL of each attachment.	`ARRAY`
last_update_date	Last update date in epoch.	`STRING`
rating	Average scoring of the article.	`FLOAT`
author_id	Author ID.	`INTEGER`
source	Creation origin of the article: web, manual, ai, api, initial_setup, import or external_sync. Read-only.	`STRING`

Manages Knowledge Base articles by keywords.

GET

/kb.articles.by.keywords

Searches for articles by keywords.

Parameters

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

Response

Returns an array of objects with the following structure:

Name	Description	Type
content	Content of the article.	`STRING`
category_id	Category ID.	`INTEGER`
title	Article title.	`STRING`
id	Article ID.	`INTEGER`
views	Amount of views that the article has.	`INTEGER`
is_private	If the article is private or not.	`BOOLEAN`
external_id	External ID of the article.	`STRING`
solved_requests	Amount of requests that this article helped to solve.	`INTEGER`
responsible_id	Responsible ID.	`INTEGER`
creation_date	Creation date in epoch.	`STRING`
status	Article status ID. 1: Published, 4: Draft, 5: Archived.	`INTEGER`
attachments	Array with the ID, name and URL of each attachment.	`ARRAY`
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`
rating	Average scoring of the article.	`FLOAT`
author_id	Author ID.	`INTEGER`
source	Creation origin of the article: web, manual, ai, api, initial_setup, import or external_sync. Read-only.	`STRING`

Manages Knowledge Base categories.

PUT

/kb.categories

Modifies a Knowledge Base category.

Parameters

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

Response

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

DELETE

/kb.categories

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`

GET

/kb.categories

Lists all the Knowledge Base categories.

Response

Returns an array of objects with the following structure:

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

POST

/kb.categories

Creates a new Knowledge Base category.

Parameters

Name	Description	Type
parent_id	Category Parent ID.	`INTEGER`
name required	Category name.	`STRING`

Response

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

Manages Knowledge Base categories by IDs.

GET

/kb.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
parent_id	Category parent ID.	`INTEGER`
name	Category name.	`STRING`
id	Category ID.	`INTEGER`

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
engine_id	Engine ID. 1: Round robin, 2: By load, 3: Free, 4: Manual.	`INTEGER`
members_ids	List of members IDs that the level has.	`ARRAY`
status_id	Status ID. 1: Enabled, 2: Suspend, 3: Out time work, 4: Disabled.	`INTEGER`
id	Level ID.	`INTEGER`
total_members	Total amount of members that the level has.	`INTEGER`
level_order	Level order.	`INTEGER`

Manages help desk levels observers.

DELETE

/levels.observers

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`

GET

/levels.observers

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_users	The observers’ users IDs.	`ARRAY`
observer_groups	The groups’ IDs that are observers of the entity.	`ARRAY`
name	Level name.	`STRING`
id	Level ID.	`INTEGER`

POST

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

Manages locations.

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`

GET

/locations

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
parent_id	Parent location ID.	`INTEGER`
total	Number of users with this location.	`INTEGER`
name	Location name.	`STRING`
id	Location ID.	`INTEGER`

POST

/locations

Creates a location.

Parameters

Name	Description	Type
parent_id	Parent location ID.	`INTEGER`
name required	Location name.	`STRING`

Response

Name	Description	Type
id	Location ID.	`INTEGER`

Manages locations observers.

DELETE

/locations.observers

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`

GET

/locations.observers

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_users	The observers’ users IDs.	`ARRAY`
observer_groups	The groups’ IDs that are observers of the entity.	`ARRAY`
name	Location name.	`STRING`
id	Location ID.	`INTEGER`

POST

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

Manages the relationships between users and locations.

DELETE

/locations.users

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`

GET

/locations.users

Lists the members of a location.

Parameters

Name	Description	Type
user_id	User ID	`INTEGER`
id required	Location 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`

POST

/locations.users

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`

Returns the current version of the InvGate Service Management instance.

GET

/sd.version

Returns the current version of the InvGate Service Management instance.

Response

Returns a string with the current version of InvGate Service Management.

Name	Description	Type
version	InvGate Service Management version.	`STRING`

Retrieves time tracking records.

DELETE

/timetracking

Deletes a time log entry from a request.

Parameters

Name	Description	Type
request_id required	Request ID.	`INTEGER`
user_id required	Author ID.	`INTEGER`
timetracking_id required	Time tracking entry ID	`INTEGER`

Response

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

GET

/timetracking

Lists all the available time tracking records within a specific time interval or a request ID.

Parameters

Name	Description	Type
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`
request_id	Request ID. Required if the from parameter is not provided.	`INTEGER`
from	Initial date and time of the interval (must be in ISO-8601 format). Required if the request_id parameter is not provided.	`STRING`
date_format	Indicate the date format. The available formats are 'iso8601noT' or 'iso8601'. If null, 'iso8601noT' format is returned, which is ISO-8601 no T (YYYY-mm-dd H:i).	`STRING`

Response

Returns an array of objects with the following structure:

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

POST

/timetracking

Logs the indicated time within a request.

Parameters

Name	Description	Type
to required	Ending date and time of the interval (timestamp format).	`INTEGER`
category_id	Time tracking category ID.	`INTEGER`
from	Initial date and time of the interval (timestamp format). If it's not specified, the current time will be used.	`INTEGER`
user_id required	Author ID.	`INTEGER`
request_id required	Request ID.	`INTEGER`
comment	Add a comment for the logged time.	`STRING`

Response

Name	Description	Type
status	Returns 'OK' if the time tracking entry was correctly created; or 'ERROR' if something went wrong.	`STRING`
timetracking_id	The ID of the created time tracking entry.	`INTEGER`

GET

/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
parent_id	Time tracking parent category ID	`INTEGER`
cost_per_hour	Cost of a working hour under the category.	`FLOAT`
name	Time tracking category name.	`STRING`
id	Time tracking category ID.	`INTEGER`

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`

Gets a list of user defined triggers that were executed in the last hour.

GET

/triggers.executions

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
request_id	ID of the affected request.	`INTEGER`
trigger_id	Trigger ID.	`INTEGER`
executed_at	Execution timestamp.	`INTEGER`
id	Execution ID.	`INTEGER`

Manages users.

PUT

/user

Updates the info of a user.

Parameters

Name	Description	Type
doc	User national ID number.	`STRING`
manager_id	User's manager ID.	`INTEGER`
other	User secondary phone number.	`STRING`
other-email	User secondary email address.	`STRING`
phone	User phone number.	`STRING`
localization	Localization of the user.	`STRING`
address	User home address.	`STRING`
email	User email address.	`STRING`
city	User city.	`STRING`
department	User department.	`STRING`
name	User name.	`STRING`
id required	User ID.	`INTEGER`
lastname	User lastname.	`STRING`
employee_number	User employee number.	`STRING`
office	User office phone number.	`STRING`
language	User language. es: Español, en: English (US), en_GB: English (UK), pt: Portuguese (Brazil), pt_PT: Português (Portugal), fr: Français, de: Deutsch, ca: Català, it: Italiano, nl: Nederlands, el: Ελληνικά.	`STRING`
country	User country.	`STRING`
birthday	User birthday.	`STRING`
position	User position.	`STRING`
username	Username.	`STRING`
fax	User fax number.	`STRING`
mobile	User mobile phone number.	`STRING`

Response

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

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
doc	User national ID number.	`STRING`
location	User localization.	`STRING`
manager_id	User's manager ID.	`INTEGER`
other	User secondary phone number.	`STRING`
is_external	Returns 'true' if the user is external.	`BOOLEAN`
phone	User phone number.	`STRING`
is_deleted	Returns 'true' if the user has been deleted.	`BOOLEAN`
role_name	User’s role.	`STRING`
address	User home address.	`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`
email	User email address.	`STRING`
city	User city.	`STRING`
department	User department.	`STRING`
name	User name.	`STRING`
id	User ID.	`INTEGER`
lastname	User lastname.	`STRING`
is_disabled	Returns 'true' if the user has been disabled.	`BOOLEAN`
employee_number	User's employee number.	`STRING`
office	User office phone number.	`STRING`
country	User country.	`STRING`
birthday	User birthday.	`STRING`
type	User type: 1: System, 2: LDAP, 3: Webservice, 4: Customer, 5: Mailbox.	`INTEGER`
position	User position.	`STRING`
username	Username.	`STRING`
fax	User fax number.	`STRING`
mobile	User mobile phone number.	`STRING`

POST

/user

Creates a new user.

Parameters

Name	Description	Type
doc	User national ID number.	`STRING`
manager_id	User's manager ID.	`INTEGER`
other	User secondary phone number.	`STRING`
force_password_change	If true, the user will be forced to change their password on the next login.	`BOOLEAN`
other-email	User secondary email address.	`STRING`
phone	User phone number.	`STRING`
localization	Localization of the user.	`STRING`
is_external	An external user can't login to the system and can only interact with it via email.	`BOOLEAN`
address	User home address.	`STRING`
email required	User email address.	`STRING`
city	User city.	`STRING`
department	User department.	`STRING`
name required	User name.	`STRING`
lastname required	User lastname.	`STRING`
employee_number	User employee number.	`STRING`
office	User office phone number.	`STRING`
country	User country.	`STRING`
birthday	Birthday of the user.	`STRING`
position	User position.	`STRING`
username	Username.	`STRING`
send_set_password_email	If true, the user will receive an email with a link to set their password.	`BOOLEAN`
fax	User fax number.	`STRING`
pass	User password.	`STRING`
mobile	User mobile phone number.	`STRING`

Response

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

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
doc	User national ID number.	`STRING`
location	User localization.	`STRING`
manager_id	User's manager ID.	`INTEGER`
other	User secondary phone number.	`STRING`
is_external	Returns 'true' if the user is external.	`BOOLEAN`
phone	User phone number.	`STRING`
is_deleted	Returns 'true' if the user has been deleted.	`BOOLEAN`
role_name	User’s role.	`STRING`
address	User home address.	`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`
email	User email address.	`STRING`
city	User city.	`STRING`
department	User department.	`STRING`
name	User name.	`STRING`
id	User ID.	`INTEGER`
lastname	User lastname.	`STRING`
is_disabled	Returns 'true' if the user has been disabled.	`BOOLEAN`
employee_number	User's employee number.	`STRING`
office	User office phone number.	`STRING`
country	User country.	`STRING`
birthday	User birthday.	`STRING`
type	User type: 1: System, 2: LDAP, 3: Webservice, 4: Customer, 5: Mailbox.	`INTEGER`
position	User position.	`STRING`
username	Username.	`STRING`
fax	User fax number.	`STRING`
mobile	User mobile phone number.	`STRING`

Changes the user type by converting it from external into internal user.

POST

/user.convert

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`

Disables a user.

PUT

/user.disable

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`

Enables a user.

PUT

/user.enable

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`

Changes the password of a user.

PUT

/user.password

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`
password required	New password.	`STRING`
id required	User ID.	`INTEGER`

Response

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

Resets the user's password and sends an action required email to the user.

POST

/user.password.reset

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`

Creates a session token for a user.

POST

/user.token

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`

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
include_disabled	True if disabled users should be included.	`BOOLEAN`
ids	Users IDs.	`ARRAY`

Response

Returns an array of objects with the following structure:

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

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
office_phone	User office phone number.	`STRING`
page_key	Hash key of the results page to retrieve. If null, the first page of results will be returned. Ignored when page or page_size is sent (offset pagination).	`STRING`
fax_phone	User fax number.	`STRING`
employee_number	User employee number.	`STRING`
phone	User phone number.	`STRING`
mobile_phone	User mobile phone number.	`STRING`
other_phone	User secondary phone number.	`STRING`
phones	User phone number of any kind (main phone number, fax number, office phone number, mobile phone number or other 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`
username	Username.	`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`
email	User email address.	`STRING`

Response

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

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

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

GET

/users.groups

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
locations	Array with the user locations.	`ARRAY`
groups_observed	Array with the user observed groups.	`ARRAY`
groups	Array with the user groups.	`ARRAY`
helpdesks	Array with the user helpdesks/levels.	`ARRAY`
companies	Array with the user companies.	`ARRAY`
username	Username.	`STRING`
helpdesks_observed	Array with the user observed helpdesks.	`ARRAY`
id	User ID.	`INTEGER`
locations_observed	Array with the user observed locations.	`ARRAY`
companies_observed	Array with the user observed companies.	`ARRAY`
email	User email address.	`STRING`

Deploys a workflow.

PUT

/wf.deploy

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
status	Returns 'OK' if the workflow was correctly deployed; or 'ERROR' if something went wrong.	`STRING`
description	Confirmation message.	`INTEGER`
workflow_id	ID of the deployed workflow.	`INTEGER`

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

GET

/wf.initialfields.by.category

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_id	ID of the associated workflow.	`INTEGER`
workflow_initial_fields	ARRAY with all the properties each field has.	`ARRAY`
associated_workflow_name	Name of the associated workflow.	`STRING`

Gets the information of a workflow request.

GET

/wf.request

Returns the general information of a workflow request, the steps it went through with the values loaded in their fields, and the current value of every workflow variable. Steps the workflow has not reached yet are not returned.

Parameters

Name	Description	Type
step_id	ID of a step in the workflow definition. When set, only that step is returned, along with the variables it references.	`STRING`
language	Language used to translate the labels of the workflow fields. If null, the language configured on the instance is used.	`STRING`
id required	Request ID.	`INTEGER`
variable_id	ID of a workflow variable. When set, only that variable is returned, along with the steps that reference it.	`STRING`
date_format	Indicate the date format. The available formats are 'epoch' or 'iso8601'. If null, epoch format is returned.	`STRING`
all_executions	When set to true, every execution of each step is returned. By default only the last execution of each step is returned.	`BOOLEAN`

Response

Returns an object with the following structure:

Name	Description	Type
source_id	Source ID.	`INTEGER`
solved_at	Solution date as an epoch number, or as an ISO-8601 string when the date_format parameter asks for it.	`INTEGER`
closed_at	Closing date as an epoch number, or as an ISO-8601 string when the date_format parameter asks for it.	`INTEGER`
description	Request description. On workflow requests this is the description configured in the workflow, not a value loaded by the customer: those are in the fields of the steps.	`STRING`
location_id	Location ID.	`INTEGER`
created_at	Creation date as an epoch number, or as an ISO-8601 string when the date_format parameter asks for it.	`INTEGER`
last_update	Last update as an epoch number, or as an ISO-8601 string when the date_format parameter asks for it.	`INTEGER`
assigned_group_id	Help desk ID.	`INTEGER`
category_id	Category ID.	`INTEGER`
title	Request title.	`STRING`
status_id	Status ID.	`INTEGER`
user_id	Customer ID.	`INTEGER`
id	Request ID.	`INTEGER`
steps	Array with the steps the request went through, in chronological order. Each step has id (the step ID in the workflow definition), name, type, state ("completed" or "current"), parent_step_id (only for steps inside a building block), occurrences (how many times the workflow went through the step) and executions. Each execution has occurrence, state, started_at, completed_at, completed_by (the ID of the user that completed the execution, which on automatic steps is the System user, and null while the execution is not completed), assigned_id, assigned_group_id and fields. Each field has id (the ID of the field in this step), variable_id, field_id (the custom field ID), label, type, value and value_label.	`ARRAY`
priority_id	Priority ID.	`INTEGER`
pretty_id	Request pretty ID as configured on the Service Management instance.	`STRING`
current_variables_values	Array with the current value of every workflow variable. Each variable has id, name, name_source ("alias", "fixed_label", "field_label" or "id", telling how the name was resolved), type, field_id, value and value_label.	`ARRAY`
date_ocurred	Occurrence date as an epoch number, or as an ISO-8601 string when the date_format parameter asks for it.	`INTEGER`
type_id	Type ID.	`INTEGER`
closed_reason	Reason of closing. 1: Solution accepted, 2: Solution expired, 3: Customer timeout, 4: Finalized workflow.	`INTEGER`
assigned_id	Assigned agent ID.	`INTEGER`
workflow	Object with the workflow of the request: workflow_id (stable ID of the workflow across versions), process_id (ID of the deployed version running this request), name, description, state ("running", "finalized", "rejected" or "cancelled"), current_step_id, current_step_name, started_at and finished_at.	`ARRAY`
creator_id	Creator ID.	`INTEGER`

Manages values in a workflow instance field of type list.

GET

/workflow.field.list.values

Retrieves current values from a workflow instance field of type list.

Parameters

Name	Description	Type
field_id required	ID of the variable visible in the workflows variable panel.	`STRING`
request_id required	ID of the workflow instance.	`INTEGER`

Response

Name	Description	Type
status	Returns "OK" if the operation was successful; or "ERROR" if something went wrong.	`STRING`
field_id	The ID of the instance field.	`STRING`
request_id	ID of the workflow instance.	`INTEGER`
values	Current values of the field.	`ARRAY`

POST

/workflow.field.list.values

Adds or sets values in a workflow instance field of type list. Use operation "add" to append values (default) or "set" to replace all values.

Parameters

Name	Description	Type
value	Single value to add or set. Use this OR values parameter.	`STRING`
field_id required	ID of the variable visible in the workflows variable panel.	`STRING`
author_id	User ID for logging purposes. Defaults to system user if not provided.	`INTEGER`
request_id required	ID of the workflow instance to update.	`INTEGER`
values	Array of values to add or set. Use this OR value parameter.	`ARRAY`
operation	Operation: "add" (append values, default) or "set" (replace all values).	`STRING`

Response

Name	Description	Type
status	Returns "OK" if the operation was successful; or "ERROR" if something went wrong.	`STRING`
description	Description of the operation result.	`STRING`
field_id	The ID of the instance field that was updated.	`STRING`
request_id	ID of the workflow instance that was updated.	`INTEGER`
values	Current values of the field after the operation.	`ARRAY`

InvGate Service Management Developer Manual

API Usage

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Response

Parameters

Response

Response

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters