Service Desk Developer Manual
Service Desk Developer Manual
Service Desk Developer Manual
API usage
Author: InvGate
Contact: info@invgate.com
Organization: InvGate
Version: 1

Abstract

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

   API call list


   assets

Manages the assets

   GET

Returns all incidents ids linked to each asset, grouped by incidents statuses

Url: {Service-Desk-Server}/api/v1/assets

Parameters:

  • assets_ids:
    • Description: Assets ids
    • Type: ARRAY
    • Required: True
  • assets_source_id:
    • Description: Assets source id
    • Type: INTEGER
    • Required: True

Response: Returns an ARRAY with objects or one object with the following structure:

  • incidents_by_assets:
    • Description: Incidents linked to assets, grouped by statuses
    • Type: ARRAY
  • assets_id:
    • Description: ID of the assets
    • Type: INTEGER

   breakingnews

Manages the breaking news

   PUT

Modifies a given Breaking News

Url: {Service-Desk-Server}/api/v1/breakingnews

Parameters:

  • body:
    • Description: body
    • Type: TEXT
    • Required: False
  • status_id:
    • Description: status the breaking news will have
    • Type: INTEGER
    • Required: False
  • title:
    • Description: title
    • Type: TEXT
    • Required: False
  • affected_helpdesk_ids:
    • Description: helpdesks that are affected
    • Type: ARRAY
    • Required: False
  • resolution_time:
    • Description: estimated resolution time, must be a timestamp that reflects the estimated resolution
    • Type: INTEGER
    • Required: False
  • affected_group_ids:
    • Description: groups that are affected
    • Type: ARRAY
    • Required: False
  • creator_id:
    • Description: creator of the change, if none its provided then it will be system (this will be used when changing the status)
    • Type: INTEGER
    • Required: False
  • type_id:
    • Description: type of breaking news
    • Type: INTEGER
    • Required: False
  • id:
    • Description: breaking news ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: TEXT
  • info:
    • Description: Description of the result
    • Type: TEXT

   POST

Creates a new Breaking News

Url: {Service-Desk-Server}/api/v1/breakingnews

Parameters:

  • body:
    • Description: body
    • Type: TEXT
    • Required: True
  • title:
    • Description: title
    • Type: TEXT
    • Required: True
  • affected_helpdesk_ids:
    • Description: helpdesks that are affected
    • Type: ARRAY
    • Required: False
  • resolution_time:
    • Description: estimated resolution time, must be a timestamp that reflects the estimated resolution
    • Type: INTEGER
    • Required: True
  • affected_group_ids:
    • Description: groups that are affected
    • Type: ARRAY
    • Required: False
  • creator_id:
    • Description: creator of the breaking news, if none its provided then it will be system
    • Type: INTEGER
    • Required: False
  • type_id:
    • Description: type of breaking news
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: TEXT
  • id:
    • Description: ID of the created object
    • Type: STRING

   GET

Returns the requested breaking news.

Url: {Service-Desk-Server}/api/v1/breakingnews

Parameters:

  • id:
    • Description: breaking news ID
    • Type: INTEGER
    • Required: True

Response:

  • body:
    • Description: Body of the object
    • Type: TEXT
  • status_id:
    • Description: Status of the object
    • Type: STRING
  • title:
    • Description: Title of the object
    • Type: TEXT
  • created_at:
    • Description: Timestamp of creation date
    • Type: STRING
  • affected_helpdesk_ids:
    • Description: Array with IDs of affected helpdesks
    • Type: ARRAY
  • resolution_time:
    • Description: Timestamp of resolution time
    • Type: STRING
  • affected_group_ids:
    • Description: Array with IDs of affected groups
    • Type: ARRAY
  • type_id:
    • Description: Type of the object
    • Type: INTEGER
  • created_by_id:
    • Description: ID of the author
    • Type: STRING
  • id:
    • Description: ID of the object
    • Type: STRING

   breakingnews.all

Lists the breaking news

   GET

Lists all the breaking news.

Url: {Service-Desk-Server}/api/v1/breakingnews.all

Response: Returns an ARRAY with BreakingNews objects


   breakingnews.attributes.status

Allows the listing of the status.

   GET

Lists all the status of breaking news, if an ID its provided only one will be listed.

Url: {Service-Desk-Server}/api/v1/breakingnews.attributes.status

Parameters:

  • id:
    • Description: status ID
    • Type: INTEGER
    • Required: False

Response: Returns an ARRAY with objects with this structure

  • id:
    • Description: Status ID
    • Type: INTEGER
  • name:
    • Description: Status name
    • Type: STRING

   breakingnews.attributes.type

Allows the listing of the types.

   GET

Lists all the types of breaking news, if an ID its provided only one will be listed.

Url: {Service-Desk-Server}/api/v1/breakingnews.attributes.type

Parameters:

  • id:
    • Description: Type ID
    • Type: INTEGER
    • Required: False

Response: Returns an ARRAY with objects with this structure

  • id:
    • Description: Type ID
    • Type: INTEGER
  • name:
    • Description: Type name
    • Type: STRING

   breakingnews.status

Manages the updates of the breaking news

   POST

Creates a new update to the given Breaking News

Url: {Service-Desk-Server}/api/v1/breakingnews.status

Parameters:

  • body:
    • Description: body
    • Type: TEXT
    • Required: True
  • creator_id:
    • Description: creator of the status update of the breaking news, if none its provided then it will be system
    • Type: INTEGER
    • Required: False
  • id:
    • Description: breaking news ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: TEXT

   GET

Returns the updates of the requested breaking news.

Url: {Service-Desk-Server}/api/v1/breakingnews.status

Parameters:

  • id:
    • Description: breaking news ID
    • Type: INTEGER
    • Required: True

Response:

  • body:
    • Description: Body of the object
    • Type: TEXT
  • created_at:
    • Description: Timestamp of creation date
    • Type: STRING
  • creator_id:
    • Description: ID of the author
    • Type: STRING

   cf.field.options

LEGACY! -> Use Options.list or Options.Tree. Requests for configuring the settings of the custom fields

   PUT

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

Url: {Service-Desk-Server}/api/v1/cf.field.options

Parameters:

  • key_values:
    • Description: Dictionary [{key:value}] with values to be added
    • Type: ARRAY
    • Required: True
  • type:
    • Description: Type of configuration to change. Types: key-value
    • Type: STRING
    • Required: True
  • uid:
    • Description: Custom Field ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: TEXT
  • info:
    • Description: Description of the result
    • Type: TEXT
  • total:
    • Description: Number of modified/added values
    • Type: INTEGER

   POST

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

Url: {Service-Desk-Server}/api/v1/cf.field.options

Parameters:

  • key_values:
    • Description: Dictionary [{key:value}] with values to be added
    • Type: ARRAY
    • Required: True
  • type:
    • Description: Type of configuration to change. Types: key-value
    • Type: STRING
    • Required: True
  • uid:
    • Description: Custom Field ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: TEXT
  • info:
    • Description: Description of the result
    • Type: TEXT
  • total:
    • Description: Number of modified/added values
    • Type: INTEGER

   DELETE

Erases keys from the custom fields configuration.

Url: {Service-Desk-Server}/api/v1/cf.field.options

Parameters:

  • keys:
    • Description: Array [key1,key2] of keys to be erased
    • Type: ARRAY
    • Required: True
  • type:
    • Description: Type of configuration to change. Types: key-value
    • Type: STRING
    • Required: True
  • uid:
    • Description: Custom Field ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: TEXT
  • info:
    • Description: Description of the result
    • Type: TEXT
  • total:
    • Description: Number of deleted values
    • Type: INTEGER

   GET

Lists the configuration of the custom fields

Url: {Service-Desk-Server}/api/v1/cf.field.options

Parameters:

  • uid:
    • Description: Custom Field ID
    • Type: INTEGER
    • Required: True

Response:

  • key-value:
    • Description: An array with the key-values dictionary of the given custom field
    • Type: ARRAY

   cf.field.options.list

Requests for configuring the settings of the custom fields of type List

   PUT

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

Url: {Service-Desk-Server}/api/v1/cf.field.options.list

Parameters:

  • key_values:
    • Description: Dictionary [{key:value}] with values to be added
    • Type: ARRAY
    • Required: True
  • type:
    • Description: Type of configuration to change. Types: key-value
    • Type: STRING
    • Required: True
  • uid:
    • Description: Custom Field ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: TEXT
  • info:
    • Description: Description of the result
    • Type: TEXT
  • total:
    • Description: Number of modified/added values
    • Type: INTEGER

   POST

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

Url: {Service-Desk-Server}/api/v1/cf.field.options.list

Parameters:

  • key_values:
    • Description: Dictionary [{key:value}] with values to be added
    • Type: ARRAY
    • Required: True
  • type:
    • Description: Type of configuration to change. Types: key-value
    • Type: STRING
    • Required: True
  • uid:
    • Description: Custom Field ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: TEXT
  • info:
    • Description: Description of the result
    • Type: TEXT
  • total:
    • Description: Number of modified/added values
    • Type: INTEGER

   DELETE

Erases keys from the custom fields configuration.

Url: {Service-Desk-Server}/api/v1/cf.field.options.list

Parameters:

  • keys:
    • Description: Array [key1,key2] of keys to be erased
    • Type: ARRAY
    • Required: True
  • type:
    • Description: Type of configuration to change. Types: key-value
    • Type: STRING
    • Required: True
  • uid:
    • Description: Custom Field ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: TEXT
  • info:
    • Description: Description of the result
    • Type: TEXT
  • total:
    • Description: Number of deleted values
    • Type: INTEGER

   GET

Lists the configuration of the custom fields

Url: {Service-Desk-Server}/api/v1/cf.field.options.list

Parameters:

  • uid:
    • Description: Custom Field ID
    • Type: INTEGER
    • Required: True

Response:

  • key-value:
    • Description: An array with the key-values dictionary of the given custom field
    • Type: ARRAY

   cf.field.options.tree

Requests for configuring the options of the custom fields of type Tree

   PUT

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

Url: {Service-Desk-Server}/api/v1/cf.field.options.tree

Parameters:

  • hash:
    • Description: Hash value of the item to modify
    • Type: STRING
    • Required: True
  • uid:
    • Description: Custom Field ID
    • Type: INTEGER
    • Required: True
  • key:
    • Description: Key defiend by the user, if no value is set the previous value will be used
    • Type: STRING
    • Required: False
  • name:
    • Description: Name of the option, value that the user sees when selecting
    • Type: STRING
    • Required: False

Response:

  • status:
    • Description: OK/ERROR
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: STRING

   POST

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

Url: {Service-Desk-Server}/api/v1/cf.field.options.tree

Parameters:

  • parent_hash:
    • Description: Hash value of the parent, if not set, it will be added to the root
    • Type: STRING
    • Required: False
  • uid:
    • Description: Custom Field ID
    • Type: INTEGER
    • Required: True
  • key:
    • Description: Key defiend by the user, if no value is set the hash will be used as key
    • Type: STRING
    • Required: False
  • name:
    • Description: Name of the option, value that the user sees when selecting
    • Type: STRING
    • Required: True

Response:

  • status:
    • Description: OK/ERROR
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: STRING

   DELETE

Erases option of the custom field and all its children.

Url: {Service-Desk-Server}/api/v1/cf.field.options.tree

Parameters:

  • hash:
    • Description: Hash value of the item to modify
    • Type: STRING
    • Required: True
  • uid:
    • Description: Custom Field ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK/ERROR
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: STRING

   GET

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

Url: {Service-Desk-Server}/api/v1/cf.field.options.tree

Parameters:

  • uid:
    • Description: Custom Field ID
    • Type: INTEGER
    • Required: True

Response: Returns an ARRAY of options, each of which has the following structure:

  • hash:
    • Description: The unique internal identifier of the option.
    • Type: STRING
  • name:
    • Description: Option name
    • Type: STRING
  • key:
    • Description: Key defined by the user for the option.
    • Type: STRING
  • children:
    • Description: Array of options that are childs of the option.
    • Type: ARRAY

   cf.fields.all

Allows requests related to the custom fields

   GET

Returns a list of all the active custom fields

Url: {Service-Desk-Server}/api/v1/cf.fields.all

Response: Returns an ARRAY with objects with the following structure:

  • description:
    • Description: Description of the field
    • Type: TEXT
  • uid:
    • Description: ID of the field
    • Type: STRING
  • label:
    • Description: Label of the field
    • Type: STRING

   cf.fields.by.category

Allows to find the custom field that apply to a category

   GET

Returns a list of the custom fields related to a category

Url: {Service-Desk-Server}/api/v1/cf.fields.by.category

Parameters:

  • category_id:
    • Description: Category ID
    • Type: INTEGER
    • Required: True

Response: Returns an ARRAY with the IDs of the Custom Fields that apply to the category received as parameter.


   cf.fields.types

Lists all the supported custom field types

   GET

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

Url: {Service-Desk-Server}/api/v1/cf.fields.types

Response: Returns an ARRAY with the following structure:

  • id:
    • Description: Type ID
    • Type: STRING
  • name:
    • Description: Type name
    • Type: STRING

   companies

Manager for companies

   POST

Creates a new company

Url: {Service-Desk-Server}/api/v1/companies

Parameters:

  • name:
    • Description: Group name
    • Type: STRING
    • Required: True

Response:

  • id:
    • Description: ID of the created object
    • Type: STRING

   DELETE

Erases an existing company

Url: {Service-Desk-Server}/api/v1/companies

Parameters:

  • id:
    • Description: Company ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: STRING

   GET

Returns all active companies, of one in particular.

Url: {Service-Desk-Server}/api/v1/companies

Parameters:

  • id:
    • Description: Company ID
    • Type: INTEGER
    • Required: False

Response: Returns an ARRAY with objects or one object with the following structure:

  • total:
    • Description: Total of users that it has
    • Type: INTEGER
  • id:
    • Description: ID of the object
    • Type: STRING
  • name:
    • Description: Name of the object
    • Type: STRING

   companies.groups

Allows the configuration of the Users Groups - Companies relationships

   POST

Relates a users group to a company

Url: {Service-Desk-Server}/api/v1/companies.groups

Parameters:

  • id:
    • Description: Company ID
    • Type: INTEGER
    • Required: True
  • groups:
    • Description: Groups IDs
    • Type: ARRAY
    • Required: True

Response: Returns an ARRAY with groups ids as keys and TRUE as values of the created relationships

   DELETE

Suppresses the relationship between a users group and a company

Url: {Service-Desk-Server}/api/v1/companies.groups

Parameters:

  • unlink_users_too:
    • Description: when set to true, it breaks the relationship between the company users and the unlinked group
    • Type: BOOLEAN
    • Required: False
  • id:
    • Description: Company ID
    • Type: INTEGER
    • Required: True
  • groups:
    • Description: Groups IDs
    • Type: ARRAY
    • Required: True

Response: Returns an ARRAY with groups ids as keys and TRUE as values of the deleted relationships

   GET

Lists all the users groups related to a company

Url: {Service-Desk-Server}/api/v1/companies.groups

Parameters:

  • id:
    • Description: Company ID
    • Type: INTEGER
    • Required: True

Response: Returns an ARRAY with objects with the following structure:

  • total:
    • Description: Total of users that it has
    • Type: INTEGER
  • id:
    • Description: ID of the related group
    • Type: STRING
  • name:
    • Description: Name of the related group
    • Type: STRING

   companies.users

Allows the configuration of users to companies relationships

   POST

Adds a user to a company

Url: {Service-Desk-Server}/api/v1/companies.users

Parameters:

  • id:
    • Description: Company ID
    • Type: INTEGER
    • Required: True
  • users:
    • Description: User IDs
    • Type: ARRAY
    • Required: True

Response: Returns an ARRAY with users ids as keys and TRUE as value if added

   DELETE

Removes a user from a company

Url: {Service-Desk-Server}/api/v1/companies.users

Parameters:

  • id:
    • Description: Company ID
    • Type: INTEGER
    • Required: True
  • users:
    • Description: User IDs
    • Type: ARRAY
    • Required: True

Response: Returns an ARRAY with users ids as keys and TRUE as value if deleted

   GET

Lists the users of a company

Url: {Service-Desk-Server}/api/v1/companies.users

Parameters:

  • id:
    • Description: Company ID
    • Type: INTEGER
    • Required: True

Response: Returns an ARRAY with users with the following structure:

  • username:
    • Description: Username of the user
    • Type: STRING
  • email:
    • Description: Email of the user
    • Type: STRING
  • id:
    • Description: ID of the user
    • Type: STRING
  • name:
    • Description: Full name of the user
    • Type: STRING

   groups

Manager for groups of users

   POST

Creates a group of users.

Url: {Service-Desk-Server}/api/v1/groups

Parameters:

  • name:
    • Description: Group name
    • Type: STRING
    • Required: True

Response:

  • id:
    • Description: ID of the created object
    • Type: STRING

   DELETE

Erases a group of users.

Url: {Service-Desk-Server}/api/v1/groups

Parameters:

  • id:
    • Description: Group ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: STRING

   GET

Returns all active groups of users, or one in particular.

Url: {Service-Desk-Server}/api/v1/groups

Parameters:

  • id:
    • Description: Group ID
    • Type: INTEGER
    • Required: False

Response: Returns an ARRAY with objects or one object with the following structure:

  • total:
    • Description: Total of users that it has
    • Type: INTEGER
  • id:
    • Description: ID of the object
    • Type: STRING
  • name:
    • Description: Name of the object
    • Type: STRING

   groups.users

Allows the configuration of user to group relationships

   POST

Adds a user to a group

Url: {Service-Desk-Server}/api/v1/groups.users

Parameters:

  • id:
    • Description: Groups ID
    • Type: INTEGER
    • Required: True
  • users:
    • Description: User IDs
    • Type: ARRAY
    • Required: True

Response: Returns an ARRAY with users ids as keys and TRUE as value if added

   DELETE

Removes a user from a group

Url: {Service-Desk-Server}/api/v1/groups.users

Parameters:

  • id:
    • Description: Groups ID
    • Type: INTEGER
    • Required: True
  • users:
    • Description: User IDs
    • Type: ARRAY
    • Required: True

Response: Returns an ARRAY with users ids as keys and TRUE as value if deleted

   GET

Lists the users of a group

Url: {Service-Desk-Server}/api/v1/groups.users

Parameters:

  • id:
    • Description: Groups ID
    • Type: INTEGER
    • Required: True

Response: Returns an ARRAY with users with the following structure:

  • username:
    • Description: Username of the user
    • Type: STRING
  • email:
    • Description: Email of the user
    • Type: STRING
  • id:
    • Description: ID of the user
    • Type: STRING
  • name:
    • Description: Full name of the user
    • Type: STRING

   helpdesks

Manager for helpdesks

   GET

Returns all active helpdesks, or one in particular.

Url: {Service-Desk-Server}/api/v1/helpdesks

Parameters:

  • id:
    • Description: helpdesk id
    • Type: INTEGER
    • Required: False
  • include_deleted:
    • Description: true if deleted help desks should be included
    • Type: BOOLEAN
    • Required: False

Response: Returns an ARRAY with objects or one object with the following structure:

  • total_members:
    • Description: Total of members that it has
    • Type: INTEGER
  • name:
    • Description: Name of the object
    • Type: STRING
  • status_id:
    • Description: status of the helpdesk
    • Type: INTEGER
  • engine_id:
    • Description: engine of the helpdesk
    • Type: INTEGER
  • parent_id:
    • Description: ID of the parent
    • Type: INTEGER
  • id:
    • Description: ID of the object
    • Type: INTEGER

   helpdesksandlevels

Manager for helpdesks and levels

   GET

Returns all helpdesks and levels, or one in particular.

Url: {Service-Desk-Server}/api/v1/helpdesksandlevels

Parameters:

  • id:
    • Description: level id
    • Type: INTEGER
    • Required: False
  • include_deleted:
    • Description: true if deleted help desks and levels should be included
    • Type: BOOLEAN
    • Required: False

Response: Returns an ARRAY with objects or one object with the following structure:

  • total_members:
    • Description: Total of members that it has
    • Type: INTEGER
  • level_order:
    • Description: If it is a level, indicates the order. Not present if not
    • Type: INTEGER
  • name:
    • Description: If it is a helpkdesk, indicates the name. Not present if not
    • Type: STRING
  • status_id:
    • Description: Status of the helpdesk or level: 1 enabled, 2 suspend, 3 out time work, 4 disabled
    • Type: INTEGER
  • engine_id:
    • Description: Id engine of the helpdesk or level: 1 round robin, 2 by load, 3 free, 4 manual
    • Type: INTEGER
  • parent_id:
    • Description: ID of the parent
    • Type: INTEGER
  • id:
    • Description: ID of the object
    • Type: INTEGER
  • members_ids:
    • Description: Members that it has
    • Type: ARRAY

   incident

Requests Management

   PUT

Change attributes of a request

Url: {Service-Desk-Server}/api/v1/incident

Parameters:

  • type_id:
    • Description: Type ID
    • Type: INTEGER
    • Required: False
  • description:
    • Description: Description
    • Type: TEXT
    • Required: False
  • title:
    • Description: Title
    • Type: TEXT
    • Required: False
  • priority_id:
    • Description: Priority ID
    • Type: INTEGER
    • Required: False
  • date:
    • Description: Occurred on Timestamp
    • Type: TEXT
    • Required: False
  • source_id:
    • Description: Source ID
    • Type: INTEGER
    • Required: False
  • category_id:
    • Description: Category ID
    • Type: INTEGER
    • Required: False
  • id:
    • Description: Request ID
    • Type: INTEGER
    • Required: True

Response:

  • type_id:
    • Description: Type ID of the request
    • Type: STRING
  • status_id:
    • Description: Status ID of the request
    • Type: STRING
  • assigned_id:
    • Description: Assigned agent ID of the request
    • Type: STRING
  • user_id:
    • Description: Customer ID of the request
    • Type: STRING
  • description:
    • Description: Description of the request
    • Type: STRING
  • closed_reason:
    • Description: Reason of closing. 1: Solution accepted, 2: Solution expired, 3: Customer timeout, 4: Finalized workflow
    • Type: STRING
  • title:
    • Description: Title of the request
    • Type: STRING
  • date_ocurred:
    • Description: Timestamp of ocurred date of the request
    • Type: STRING
  • created_at:
    • Description: Timestamp of creation of the request
    • Type: STRING
  • priority_id:
    • Description: Priority ID of the request
    • Type: STRING
  • last_update:
    • Description: Timestamp of last update of the request
    • Type: STRING
  • solved_at:
    • Description: Timestamp of solution of the request
    • Type: STRING
  • creator_id:
    • Description: Creator ID of the request
    • Type: STRING
  • process_id:
    • Description: Process ID of the request if it is a workflow instance
    • Type: STRING
  • assigned_group_id:
    • Description: Heldespk ID of the request
    • Type: STRING
  • source_id:
    • Description: Source ID of the request
    • Type: STRING
  • closed_at:
    • Description: Timestamp of closed time of the request
    • Type: STRING
  • category_id:
    • Description: Category ID of the request
    • Type: STRING
  • id:
    • Description: ID of the request
    • Type: STRING
  • custom_fields:
    • Description: Array with the custom fields ids as keys and the respective values
    • Type: ARRAY
  • attachments:
    • Description: Array with the IDs of the attachments
    • Type: ARRAY

   POST

Creates a request

Url: {Service-Desk-Server}/api/v1/incident

Parameters:

  • category_id:
    • Description: Category ID
    • Type: INTEGER
    • Required: True
  • description:
    • Description: Description
    • Type: TEXT
    • Required: True
  • type_id:
    • Description: Type ID
    • Type: INTEGER
    • Required: True
  • priority_id:
    • Description: Priority ID
    • Type: INTEGER
    • Required: True
  • date:
    • Description: Occurred on Timestamp
    • Type: TEXT
    • Required: False
  • creator_id:
    • Description: Creator ID
    • Type: INTEGER
    • Required: True
  • source_id:
    • Description: Source ID
    • Type: INTEGER
    • Required: False
  • title:
    • Description: Title
    • Type: TEXT
    • Required: True
  • customer_id:
    • Description: Client ID
    • Type: INTEGER
    • Required: True
  • attachments:
    • Description: Array of attachments.
    • Type: ARRAY
    • Required: False

Response:

  • status:
    • Description: OK
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: STRING
  • request_id:
    • Description: ID of the created ticket
    • Type: STRING

   GET

Returns the information of the given request

Url: {Service-Desk-Server}/api/v1/incident

Parameters:

  • id:
    • Description: Request ID
    • Type: INTEGER
    • Required: True
  • comments:
    • Description: when set to true, it includes the comments of the request
    • Type: BOOLEAN
    • Required: False

Response:

  • attachments:
    • Description: Array with the IDs of the attachments
    • Type: ARRAY
  • type_id:
    • Description: Type ID of the request
    • Type: STRING
  • priority_id:
    • Description: Priority ID of the request
    • Type: STRING
  • solved_at:
    • Description: Timestamp of solution of the request
    • Type: STRING
  • closed_at:
    • Description: Timestamp of closed time of the request
    • Type: STRING
  • id:
    • Description: ID of the request
    • Type: STRING
  • custom_fields:
    • Description: Array with the custom fields ids as keys and the respective values
    • Type: ARRAY
  • user_id:
    • Description: Customer ID of the request
    • Type: STRING
  • closed_reason:
    • Description: Reason of closing. 1: Solution accepted, 2: Solution expired, 3: Customer timeout, 4: Finalized workflow
    • Type: STRING
  • title:
    • Description: Title of the request
    • Type: STRING
  • date_ocurred:
    • Description: Timestamp of ocurred date of the request
    • Type: STRING
  • assigned_id:
    • Description: Assigned agent ID of the request
    • Type: STRING
  • comments:
    • Description: Array with comments of the requests with the Comment structure
    • Type: ARRAY
  • last_update:
    • Description: Timestamp of last update of the request
    • Type: STRING
  • assigned_group_id:
    • Description: Heldespk ID of the request
    • Type: STRING
  • description:
    • Description: Description of the request
    • Type: STRING
  • status_id:
    • Description: Status ID of the request
    • Type: STRING
  • process_id:
    • Description: Process ID of the request if it is a workflow instance
    • Type: STRING
  • created_at:
    • Description: Timestamp of creation of the request
    • Type: STRING
  • creator_id:
    • Description: Creator ID of the request
    • Type: STRING
  • source_id:
    • Description: Source ID of the request
    • Type: STRING
  • category_id:
    • Description: Category ID of the request
    • Type: STRING

   incident.approval

Manages the approvals instance of a ticket

   GET

Lists the approvals instances that the given ticket has.

Url: {Service-Desk-Server}/api/v1/incident.approval

Parameters:

  • only_pending:
    • Description: when set to true, it only returns pending approvals
    • Type: BOOLEAN
    • Required: False
  • request_id:
    • Description: Request ID
    • Type: INTEGER
    • Required: True

Response: Returns an ARRAY of objects with the following structure:

  • status:
    • Description: -2: Cancelled, -1: Waiting, 0: Rejected, 1: Approved
    • Type: STRING
  • created_at:
    • Description: Timestamp when the approval was triggered
    • Type: STRING
  • approval_request_description:
    • Description: Description of the approval
    • Type: TEXT
  • approval_request_id:
    • Description: ID of the approval template
    • Type: STRING
  • author_id:
    • Description: Author id of the approval
    • Type: STRING
  • type:
    • Description: 1: Predefined approval, 2: Spontaneous approval
    • Type: STRING
  • id:
    • Description: ID of the approval instance
    • Type: STRING

   incident.approval.accept

Manages the acceptance of an approval.

   PUT

Manages the acceptance of an approval.

Url: {Service-Desk-Server}/api/v1/incident.approval.accept

Parameters:

  • approval_id:
    • Description: Approval ID to be accepted.
    • Type: INTEGER
    • Required: True
  • user_id:
    • Description: ID of the user who will accept the approval.
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK or ERROR
    • Type: STRING

   incident.approval.cancel

Manages the cancellation of an approval.

   PUT

Manages the cancellation of an approval.

Url: {Service-Desk-Server}/api/v1/incident.approval.cancel

Parameters:

  • approval_id:
    • Description: Approval ID to be cancelled.
    • Type: INTEGER
    • Required: True
  • user_id:
    • Description: ID of the user who will cancel the approval.
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK or ERROR
    • Type: STRING

   incident.approval.possible_voters

Lists users that could accept or reject the approval.

   GET

Lists users that could accept or reject the approval.

Url: {Service-Desk-Server}/api/v1/incident.approval.possible_voters

Parameters:

  • approval_id:
    • Description: Approval ID
    • Type: INTEGER
    • Required: True
  • only_pending:
    • Description: when set to true, it only returns voters who have not voted.
    • Type: BOOLEAN
    • Required: False

Response: Returns an ARRAY of objects with the following structure:

  • status:
    • Description: -2: Annulled, -1: Waiting, 0: Rejected, 1: Approved, 2:Expired
    • Type: STRING
  • id:
    • Description: ID of the user
    • Type: STRING

   incident.approval.reject

Manages the rejection of an approval.

   PUT

Manages the rejection of an approval.

Url: {Service-Desk-Server}/api/v1/incident.approval.reject

Parameters:

  • approval_id:
    • Description: Approval ID to be rejected.
    • Type: INTEGER
    • Required: True
  • user_id:
    • Description: ID of the user will reject the approval.
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK or ERROR
    • Type: STRING

   incident.approval.status

Lists the statuses of the Approvals

   GET

Lists the statuses of the approvals.

Url: {Service-Desk-Server}/api/v1/incident.approval.status

Response: Returns an ARRAY with status id as keys and status label as values


   incident.approval.type

Lists the available approvals types

   GET

Lists the available approvals types

Url: {Service-Desk-Server}/api/v1/incident.approval.type

Response: Returns an ARRAY with type id as keys and type label as values


   incident.approval.vote_status

Lists the statuses of the Approval Votes

   GET

Lists the statuses of the approval votes.

Url: {Service-Desk-Server}/api/v1/incident.approval.vote_status

Response: Returns an ARRAY with status id as keys and status label as values


   incident.attachment

Manages the attachments of the requests

   GET

Returns the requested attachment.

Url: {Service-Desk-Server}/api/v1/incident.attachment

Parameters:

  • id:
    • Description: Attachment ID
    • Type: INTEGER
    • Required: True

Response:

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

   incident.attributes.category

Allows the listing of categories.

   GET

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

Url: {Service-Desk-Server}/api/v1/incident.attributes.category

Parameters:

  • id:
    • Description: Category ID
    • Type: INTEGER
    • Required: False

Response: Returns an ARRAY with the following structure:

  • parent_category_id:
    • Description: Category parent ID
    • Type: STRING
  • id:
    • Description: Category ID
    • Type: STRING
  • name:
    • Description: Category name
    • Type: STRING

   incident.attributes.priority

Allows the listing of priorities.

   GET

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

Url: {Service-Desk-Server}/api/v1/incident.attributes.priority

Parameters:

  • id:
    • Description: Priority ID
    • Type: INTEGER
    • Required: False

Response: Returns an ARRAY with the following structure:

  • id:
    • Description: Priority ID
    • Type: STRING
  • name:
    • Description: Priority name
    • Type: STRING

   incident.attributes.source

Allows the listing of sources.

   GET

Lists all the sources, if an ID its provided only one will be listed.

Url: {Service-Desk-Server}/api/v1/incident.attributes.source

Parameters:

  • id:
    • Description: Source ID
    • Type: INTEGER
    • Required: False

Response: Returns an ARRAY with the following structure:

  • id:
    • Description: Source ID
    • Type: STRING
  • name:
    • Description: Source name
    • Type: STRING

   incident.attributes.statuses

Allows the listing of the statuses.

   GET

Lists all the statuses, if an ID its provided only one will be listed.

Url: {Service-Desk-Server}/api/v1/incident.attributes.statuses

Parameters:

  • id:
    • Description: Status ID
    • Type: INTEGER
    • Required: False

Response: Returns an ARRAY with the following structure:

  • id:
    • Description: Status ID
    • Type: STRING
  • name:
    • Description: Status name
    • Type: STRING

   incident.attributes.type

Allows the listing of the types.

   GET

Lists all the types, if an ID its provided only one will be listed.

Url: {Service-Desk-Server}/api/v1/incident.attributes.type

Parameters:

  • id:
    • Description: Type ID
    • Type: INTEGER
    • Required: False

Response: Returns an ARRAY with the following structure:

  • id:
    • Description: Type ID
    • Type: STRING
  • name:
    • Description: Type name
    • Type: STRING

   incident.collaborator

Manages the collaborators of the requests.

   POST

Requests collaboration to the defined users.

Url: {Service-Desk-Server}/api/v1/incident.collaborator

Parameters:

  • users_id:
    • Description: User IDs
    • Type: ARRAY
    • Required: False
  • author_id:
    • Description: Author ID, the ID of the author of this action.
    • Type: INTEGER
    • Required: True
  • user_id:
    • Description: User ID
    • Type: INTEGER
    • Required: False
  • request_id:
    • Description: request ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK/ERROR
    • Type: STRING

   GET

Returns a list of the collaborators IDs.

Url: {Service-Desk-Server}/api/v1/incident.collaborator

Parameters:

  • request_id:
    • Description: request ID
    • Type: INTEGER
    • Required: True

Response: Returns an ARRAY with the ids of the collaborators


   incident.comment

Adds a reply to the request.

   POST

Adds a reply by the given author to the request.

Url: {Service-Desk-Server}/api/v1/incident.comment

Parameters:

  • comment:
    • Description: Reply to be added
    • Type: TEXT
    • Required: True
  • is_solution:
    • Description: Mark as solution
    • Type: BOOLEAN
    • Required: False
  • attachments:
    • Description: Array of attachments.
    • Type: ARRAY
    • Required: False
  • request_id:
    • Description: Request ID
    • Type: INTEGER
    • Required: True
  • author_id:
    • Description: Author ID
    • Type: INTEGER
    • Required: True
  • customer_visible:
    • Description: Mark as internal
    • Type: BOOLEAN
    • Required: False

Response:

  • status:
    • Description: OK/ERROR
    • Type: STRING

   GET

Gets the replies of a given request.

Url: {Service-Desk-Server}/api/v1/incident.comment

Parameters:

  • request_id:
    • Description: Request ID
    • Type: INTEGER
    • Required: True

Response: ARRAY with comments with the following structure:

  • incident_id:
    • Description: ID of the request
    • Type: STRING
  • attachments:
    • Description: Array with the IDs of the attachments of the comment
    • Type: ARRAY
  • reference:
    • Description: ID of the comment that is replied to
    • Type: STRING
  • msg_num:
    • Description: Number of the message in the request
    • Type: STRING
  • created_at:
    • Description: Timestamp of creation
    • Type: STRING
  • is_solution:
    • Description: 1 if this is the solution, 0 otherwise
    • Type: STRING
  • id:
    • Description: ID of the comment
    • Type: STRING
  • author_id:
    • Description: ID of the author
    • Type: STRING
  • customer_visible:
    • Description: 0 if is an internal comment, 1 otherwise
    • Type: STRING
  • message:
    • Description: Message of the comment
    • Type: STRING

   incident.custom_approval

Manages the custom approvals of a given request

   POST

Requests a custom approval in the given request.

Url: {Service-Desk-Server}/api/v1/incident.custom_approval

Parameters:

  • approval_id:
    • Description: Custom Approval ID
    • Type: INTEGER
    • Required: True
  • author_id:
    • Description: Author ID of the approval request
    • Type: INTEGER
    • Required: True
  • description:
    • Description: Custom Approval Description
    • Type: TEXT
    • Required: False
  • request_id:
    • Description: Request ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK/ERROR
    • Type: STRING

   GET

Lists the custom approvals templates that the given request has.

Url: {Service-Desk-Server}/api/v1/incident.custom_approval

Parameters:

  • request_id:
    • Description: Request ID
    • Type: INTEGER
    • Required: True

Response: Returns an ARRAY with approval templates that a ticket has, using the approval ID as key and values with the following structure:

  • status:
    • Description: 1: Active, -1: Deleted
    • Type: STRING
  • description_prompt:
    • Description: Description template
    • Type: STRING
  • title:
    • Description: Title of the approval
    • Type: STRING
  • created_at:
    • Description: Timestamp of creation
    • Type: STRING
  • expired_in:
    • Description: Expiration time in seconds
    • Type: STRING
  • wf_item_id:
    • Description: ID of the phase of the associated process
    • Type: STRING
  • wf_process_id:
    • Description: ID of the associated process
    • Type: STRING
  • expired_approved:
    • Description: Action when expires: 1: Approve, 2: Reject
    • Type: STRING
  • pause_sla:
    • Description: 1/0 Pauses SLA
    • Type: STRING
  • description_required:
    • Description: 0/1 whether description is required or not
    • Type: STRING
  • id:
    • Description: ID of the approval template
    • Type: STRING
  • description:
    • Description: Description of the approval
    • Type: STRING

   incident.custom_field

Custom Fields management for a request

   POST

Creates values for a custom field of 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.

Url: {Service-Desk-Server}/api/v1/incident.custom_field

Parameters:

  • author_id:
    • Description: Author ID
    • Type: INTEGER
    • Required: True
  • custom_field_uid:
    • Description: Custom Field UID
    • Type: INTEGER
    • Required: True
  • values:
    • Description: 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.
    • Type: ARRAY
    • Required: True
  • request_id:
    • Description: Request ID
    • Type: INTEGER
    • Required: True

   GET

Url: {Service-Desk-Server}/api/v1/incident.custom_field

Response:

  • status:
    • Description: OK/ERROR
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: STRING

   incident.external_entity

Links requests to external entities.

   POST

Links a request to an external entity.

Url: {Service-Desk-Server}/api/v1/incident.external_entity

Parameters:

  • external_entity_id:
    • Description: External entity ID
    • Type: INTEGER
    • Required: True
  • external_entity_ref_id:
    • Description: External entity reference ID
    • Type: STRING
    • Required: False
  • request_id:
    • Description: Request ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: STRING
  • link_id:
    • Description: ID of the created relation
    • Type: STRING

   GET

Lists all the external entities linked to a request.

Url: {Service-Desk-Server}/api/v1/incident.external_entity

Parameters:

  • request_id:
    • Description: Request ID
    • Type: INTEGER
    • Required: True

Response: ARRAY with objects with the following structure:

  • status:
    • Description: 1/0 Enabled or deleted entity
    • Type: STRING
  • name:
    • Description: Name of the external entity
    • Type: STRING
  • ref_id:
    • Description: ID of the external entity
    • Type: STRING
  • link_id:
    • Description: ID of the relation
    • Type: STRING
  • type:
    • Description: Always 100
    • Type: STRING
  • ext_ref_id:
    • Description: Reference ID to the external entity
    • Type: STRING

   incident.link

Linked requests manager

   POST

Links a request to another request

Url: {Service-Desk-Server}/api/v1/incident.link

Parameters:

  • request_ids:
    • Description: Request IDs to link
    • Type: ARRAY
    • Required: True
  • request_id:
    • Description: Request ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: STRING

   GET

Lists all the linked requests of a given request

Url: {Service-Desk-Server}/api/v1/incident.link

Parameters:

  • request_id:
    • Description: Request ID
    • Type: INTEGER
    • Required: True

Response: Returns an ARRAY of objects with this structure:

  • id:
    • Description: ID of the related request
    • Type: STRING
  • title:
    • Description: Title of the related request
    • Type: STRING

   incident.observer

Manages the observers of the requests

   POST

Adds a user as observer.

Url: {Service-Desk-Server}/api/v1/incident.observer

Parameters:

  • users_id:
    • Description: User IDs
    • Type: ARRAY
    • Required: False
  • author_id:
    • Description: Author ID
    • Type: INTEGER
    • Required: True
  • user_id:
    • Description: User ID
    • Type: INTEGER
    • Required: False
  • request_id:
    • Description: Request ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK/ERROR
    • Type: STRING

   incident.reassign

Reassigns to a help desk and/or agent

   POST

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

Url: {Service-Desk-Server}/api/v1/incident.reassign

Parameters:

  • author_id:
    • Description: Author ID
    • Type: INTEGER
    • Required: True
  • group_id:
    • Description: Help Desk ID
    • Type: INTEGER
    • Required: True
  • agent_id:
    • Description: Agent ID
    • Type: INTEGER
    • Required: False
  • request_id:
    • Description: Request ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK/ERROR
    • Type: STRING

   incident.reject

Manages the rejection of a request

   POST

Rejects a request.

Url: {Service-Desk-Server}/api/v1/incident.reject

Parameters:

  • author_id:
    • Description: ID of the user rejecting the request
    • Type: INTEGER
    • Required: True
  • request_id:
    • Description: ID of the request to reject
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK or ERROR
    • Type: STRING

   incident.spontaneous_approval

Maneja las aprobaciones espontáneas de una solicitud

   POST

Genera una aprobación dado un usuario y una solicitud determinada.

Url: {Service-Desk-Server}/api/v1/incident.spontaneous_approval

Parameters:

  • author_id:
    • Description: ID del autor del pedido de aprobación
    • Type: INTEGER
    • Required: True
  • approval_user_id:
    • Description: ID del usuario al que se le realizará el pedido
    • Type: INTEGER
    • Required: True
  • description:
    • Description: Descripción de la aprobación
    • Type: TEXT
    • Required: True
  • request_id:
    • Description: ID de la solicitud
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK/ERROR
    • Type: STRING

   incident.waitingfor.agent

Manages the agent waiting status of the requests.

   POST

Sets the agent waiting status to the request.

Url: {Service-Desk-Server}/api/v1/incident.waitingfor.agent

Parameters:

  • request_id:
    • Description: request ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: STRING

   incident.waitingfor.customer

Manages the client waiting status of the requests.

   POST

Sets the status waiting for customer to the request.

Url: {Service-Desk-Server}/api/v1/incident.waitingfor.customer

Parameters:

  • request_id:
    • Description: request ID.
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: STRING

   incident.waitingfor.date

Manages the waiting for date.

   POST

Sets the request in the Waiting for Date status.

Url: {Service-Desk-Server}/api/v1/incident.waitingfor.date

Parameters:

  • timestamp:
    • Description: Date Timestamp to set.
    • Type: STRING
    • Required: True
  • request_id:
    • Description: request ID.
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: STRING

   incident.waitingfor.external_entity

Manages the waiting for external entities status of requests.

   POST

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

Url: {Service-Desk-Server}/api/v1/incident.waitingfor.external_entity

Parameters:

  • entity_link_id:
    • Description: Link ID of the request to external entity
    • Type: INTEGER
    • Required: True
  • request_id:
    • Description: request ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: STRING

   incident.waitingfor.incident

Manages the waiting for another request status.

   POST

Sets the request in the waiting for another request status.

Url: {Service-Desk-Server}/api/v1/incident.waitingfor.incident

Parameters:

  • wait_request_id:
    • Description: request ID that will be wait for.
    • Type: INTEGER
    • Required: True
  • request_id:
    • Description: request ID.
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: STRING

   incidents

Management of requests

   GET

Lists several requests.

Url: {Service-Desk-Server}/api/v1/incidents

Parameters:

  • ids:
    • Description: List of requests
    • Type: ARRAY
    • Required: True
  • comments:
    • Description: when set to true, the replies will be included in the request
    • Type: BOOLEAN
    • Required: False

Response:

  • attachments:
    • Description: Array with the IDs of the attachments
    • Type: ARRAY
  • type_id:
    • Description: Type ID of the request
    • Type: STRING
  • priority_id:
    • Description: Priority ID of the request
    • Type: STRING
  • solved_at:
    • Description: Timestamp of solution of the request
    • Type: STRING
  • closed_at:
    • Description: Timestamp of closed time of the request
    • Type: STRING
  • id:
    • Description: ID of the request
    • Type: STRING
  • custom_fields:
    • Description: Array with the custom fields ids as keys and the respective values
    • Type: ARRAY
  • user_id:
    • Description: Customer ID of the request
    • Type: STRING
  • closed_reason:
    • Description: Reason of closing. 1: Solution accepted, 2: Solution expired, 3: Customer timeout, 4: Finalized workflow
    • Type: STRING
  • title:
    • Description: Title of the request
    • Type: STRING
  • date_ocurred:
    • Description: Timestamp of ocurred date of the request
    • Type: STRING
  • assigned_id:
    • Description: Assigned agent ID of the request
    • Type: STRING
  • comments:
    • Description: Array with comments of the requests with the Comment structure
    • Type: ARRAY
  • last_update:
    • Description: Timestamp of last update of the request
    • Type: STRING
  • assigned_group_id:
    • Description: Heldespk ID of the request
    • Type: STRING
  • description:
    • Description: Description of the request
    • Type: STRING
  • status_id:
    • Description: Status ID of the request
    • Type: STRING
  • process_id:
    • Description: Process ID of the request if it is a workflow instance
    • Type: STRING
  • created_at:
    • Description: Timestamp of creation of the request
    • Type: STRING
  • creator_id:
    • Description: Creator ID of the request
    • Type: STRING
  • source_id:
    • Description: Source ID of the request
    • Type: STRING
  • category_id:
    • Description: Category ID of the request
    • Type: STRING

   incidents.by.asset

Requests linked to Assets.

   GET

Returns a list with the request IDs related to the given asset.

Url: {Service-Desk-Server}/api/v1/incidents.by.asset

Parameters:

  • asset_id:
    • Description: Asset ID
    • Type: STRING
    • Required: True

Response:

  • status:
    • Description: OK/ERROR
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: STRING
  • requestIds:
    • Description: Array with the requests ids
    • Type: ARRAY

   incidents.by.helpdesk

Open requests by help desk

   GET

Returns a list of IDs of the open requests of the given help desk.

Url: {Service-Desk-Server}/api/v1/incidents.by.helpdesk

Parameters:

  • helpdesk_id:
    • Description: Help Desk ID
    • Type: INTEGER
    • Required: False
  • helpdesk_ids:
    • Description: List of Help Desks IDs
    • Type: ARRAY
    • Required: False

Response:

  • status:
    • Description: OK/ERROR
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: STRING
  • requestIds:
    • Description: Array with the requests ids
    • Type: ARRAY

   incidents.by.status

Open requests by help desk

   GET

Returns a list of IDs of the requests of the given status/es.

Url: {Service-Desk-Server}/api/v1/incidents.by.status

Parameters:

  • status_ids:
    • Description: List of Status IDs
    • Type: ARRAY
    • Required: False
  • status_id:
    • Description: Status ID
    • Type: INTEGER
    • Required: False

Response:

  • status:
    • Description: OK/ERROR
    • Type: STRING
  • info:
    • Description: Description of the result
    • Type: STRING
  • requestIds:
    • Description: Array with the requests ids
    • Type: ARRAY

   internalnotes

Manager for internal notes

   PUT

Updates the info of an internal note

Url: {Service-Desk-Server}/api/v1/internalnotes

Parameters:

  • author_id:
    • Description: Author ID
    • Type: INTEGER
    • Required: True
  • title:
    • Description: Title of the note
    • Type: STRING
    • Required: False
  • id:
    • Description: Note ID
    • Type: INTEGER
    • Required: True
  • description:
    • Description: Description of the note
    • Type: STRING
    • Required: False

Response:

  • Status:
    • Description: OK
    • Type: STRING

   POST

Creates an internal note

Url: {Service-Desk-Server}/api/v1/internalnotes

Parameters:

  • author_id:
    • Description: Author ID
    • Type: INTEGER
    • Required: True
  • object_type:
    • Description: Entity Type, 1: User, 2: Helpdesk, 3: Company, 4: Users Group, 5: External Entity
    • Type: INTEGER
    • Required: True
  • description:
    • Description: Description of the note
    • Type: STRING
    • Required: True
  • object_id:
    • Description: Entity ID
    • Type: INTEGER
    • Required: True
  • title:
    • Description: Title of the note
    • Type: STRING
    • Required: True

Response:

  • Status:
    • Description: OK
    • Type: STRING

   DELETE

Delete an internal note

Url: {Service-Desk-Server}/api/v1/internalnotes

Parameters:

  • author_id:
    • Description: Author ID
    • Type: INTEGER
    • Required: True
  • id:
    • Description: Note ID
    • Type: INTEGER
    • Required: True

Response:

  • Status:
    • Description: OK
    • Type: STRING

   GET

Returns all internal notes, or one in particular.

Url: {Service-Desk-Server}/api/v1/internalnotes

Parameters:

  • object_type:
    • Description: Entity Type, 1: User, 2: Helpdesk, 3: Company, 4: Users Group, 5: External Entity
    • Type: INTEGER
    • Required: False
  • id:
    • Description: Note ID
    • Type: INTEGER
    • Required: False
  • object_id:
    • Description: Entity ID
    • Type: INTEGER
    • Required: False

Response:

  • info:
    • Type:
  • last_author:
    • Description: Last author ID
    • Type: INTEGER
  • description:
    • Description: Description of the note
    • Type: STRING
  • title:
    • Description: Title of the note
    • Type: STRING
  • created_at:
    • Description: Timestamp of creation of the note
    • Type: INTEGER
  • object_type:
    • Description: Entity Type, 1: User, 2: Helpdesk, 3: Company, 4: Users Group, 5: External Entity
    • Type: INTEGER
  • object_id:
    • Description: Entity ID
    • Type: INTEGER
  • last_update:
    • Description: Timestamp of last update of the note
    • Type: INTEGER
  • author_id:
    • Description: Author ID
    • Type: INTEGER
  • id:
    • Description: Note ID
    • Type: INTEGER

   levels

Manager for helpdesks levels

   GET

Returns all active helpdesks levels, or one in particular.

Url: {Service-Desk-Server}/api/v1/levels

Parameters:

  • id:
    • Description: level id
    • Type: INTEGER
    • Required: False
  • include_deleted:
    • Description: true if deleted levels should be included
    • Type: BOOLEAN
    • Required: False

Response: Returns an ARRAY with objects or one object with the following structure:

  • total_members:
    • Description: Total of members that it has
    • Type: INTEGER
  • level_order:
    • Description: order of the level
    • Type: INTEGER
  • status_id:
    • Description: status of the level
    • Type: INTEGER
  • engine_id:
    • Description: engine of the level
    • Type: INTEGER
  • members_ids:
    • Description: Members that it has
    • Type: ARRAY
  • id:
    • Description: ID of the object
    • Type: INTEGER

   timetracking

Manages time tracking

   GET

Lists the times of the given period

Url: {Service-Desk-Server}/api/v1/timetracking

Parameters:

  • to:
    • Description: Final point of the period (must be in ISO 8601). if its not specified, the current time will be used.
    • Type: STRING
    • Required: False
  • from:
    • Description: Initial point of the period (must be in ISO 8601).
    • Type: STRING
    • Required: True

Response: Returns an ARRAY of objects with the following structure:

  • comment:
    • Description: Comment of the logged period
    • Type: STRING
  • from:
    • Description: Initial point of the period (ISO 8601)
    • Type: STRING
  • to:
    • Description: Final point of the period (ISO 8601)
    • Type: STRING
  • incident:
    • Description: ID of the request
    • Type: STRING
  • user_id:
    • Description: ID of the author
    • Type: STRING
  • total:
    • Description: Total amount of time in seconds
    • Type: STRING

   user

Manages users

   PUT

Updates the info of a user

Url: {Service-Desk-Server}/api/v1/user

Parameters:

  • username:
    • Type: STRING
    • Required: False
  • city:
    • Type: STRING
    • Required: False
  • fax:
    • Type: STRING
    • Required: False
  • name:
    • Type: STRING
    • Required: False
  • office:
    • Type: STRING
    • Required: False
  • mobile:
    • Type: STRING
    • Required: False
  • lastname:
    • Type: STRING
    • Required: False
  • address:
    • Type: STRING
    • Required: False
  • birthday:
    • Type: STRING
    • Required: False
  • id:
    • Type: INTEGER
    • Required: True
  • phone:
    • Type: STRING
    • Required: False
  • other:
    • Type: STRING
    • Required: False
  • manager_id:
    • Type: INTEGER
    • Required: False
  • doc:
    • Type: STRING
    • Required: False
  • department:
    • Type: STRING
    • Required: False
  • position:
    • Type: STRING
    • Required: False
  • country:
    • Type: STRING
    • Required: False
  • email:
    • Type: STRING
    • Required: False
  • other-email:
    • Type: STRING
    • Required: False

Response:

  • Status:
    • Description: OK
    • Type: STRING

   POST

Creates a new user

Url: {Service-Desk-Server}/api/v1/user

Parameters:

  • username:
    • Type: STRING
    • Required: True
  • city:
    • Type: STRING
    • Required: False
  • fax:
    • Type: STRING
    • Required: False
  • name:
    • Type: STRING
    • Required: True
  • office:
    • Type: STRING
    • Required: False
  • phone:
    • Type: STRING
    • Required: False
  • mobile:
    • Type: STRING
    • Required: False
  • lastname:
    • Type: STRING
    • Required: True
  • address:
    • Type: STRING
    • Required: False
  • birthday:
    • Type: STRING
    • Required: False
  • other:
    • Type: STRING
    • Required: False
  • doc:
    • Type: STRING
    • Required: False
  • manager_id:
    • Type: INTEGER
    • Required: False
  • pass:
    • Type: STRING
    • Required: False
  • department:
    • Type: STRING
    • Required: False
  • position:
    • Type: STRING
    • Required: False
  • country:
    • Type: STRING
    • Required: False
  • email:
    • Type: STRING
    • Required: True
  • other-email:
    • Type: STRING
    • Required: False

Response:

  • Status:
    • Description: OK
    • Type: STRING

   DELETE

Deletes a user

Url: {Service-Desk-Server}/api/v1/user

Parameters:

  • id:
    • Description: User ID
    • Type: INTEGER
    • Required: True

Response:

  • Status:
    • Description: OK
    • Type: STRING

   GET

Returns the info of a user

Url: {Service-Desk-Server}/api/v1/user

Parameters:

  • id:
    • Description: User ID
    • Type: INTEGER
    • Required: True

Response:

  • username:
    • Description: Username of the user
    • Type: STRING
  • city:
    • Description: City of the user
    • Type: STRING
  • fax:
    • Description: Fax number of the user
    • Type: STRING
  • name:
    • Description: Name of the user
    • Type: STRING
  • office:
    • Description: Office phone number of the user
    • Type: STRING
  • mobile:
    • Description: Mobile phone number of the user
    • Type: STRING
  • lastname:
    • Description: Lastname of the user
    • Type: STRING
  • address:
    • Description: Address of the user
    • Type: STRING
  • other_email:
    • Description: Email2 of the user
    • Type: STRING
  • birthday:
    • Description: Birthday of the user
    • Type: STRING
  • id:
    • Description: ID of the user
    • Type: STRING
  • phone:
    • Description: Phone number of the user
    • Type: STRING
  • other:
    • Description: Other phone number of the user
    • Type: STRING
  • manager_id:
    • Description: Manager ID of the user
    • Type: STRING
  • doc:
    • Description: Document of the user
    • Type: STRING
  • department:
    • Description: Department of the user
    • Type: STRING
  • position:
    • Description: Position of the user
    • Type: STRING
  • country:
    • Description: Country of the user
    • Type: STRING
  • email:
    • Description: Email of the user
    • Type: STRING

   user.by

User info by username or email

   GET

Returns the user information by username or email

Url: {Service-Desk-Server}/api/v1/user.by

Parameters:

  • username:
    • Description: Username
    • Type: STRING
    • Required: False
  • email:
    • Description: Email
    • Type: STRING
    • Required: False

Response:

  • username:
    • Description: Username of the user
    • Type: STRING
  • type:
    • Description: Type of the user, 1: System, 2: LDAP, 3: Webservice, 4: Customer, 5: Mailbox
    • Type: STRING
  • id:
    • Description: ID of the user
    • Type: STRING
  • email:
    • Description: Email of the user
    • Type: STRING

   user.convert

Changes the user type

   POST

Changes the user type from MAIL to system, and sends an email to restore the password

Url: {Service-Desk-Server}/api/v1/user.convert

Parameters:

  • id:
    • Description: User ID
    • Type: INTEGER
    • Required: True

Response:

  • status:
    • Description: OK
    • Type: STRING

   user.password

Changes the password of a user

   PUT

Changes the password of a user

Url: {Service-Desk-Server}/api/v1/user.password

Parameters:

  • password:
    • Type: STRING
    • Required: True
  • id:
    • Description: User ID
    • Type: INTEGER
    • Required: True

Response:

  • Status:
    • Description: OK
    • Type: STRING

   user.password.reset

Sends a notification email to a user

   POST

Sends an email of type NEW_USER and flags the user for a password change

Url: {Service-Desk-Server}/api/v1/user.password.reset

Parameters:

  • type:
    • Description: Type of message to send (NEW_USER o RESET_PASSWORD)
    • Type: STRING
    • Required: True
  • id:
    • Description: User ID
    • Type: INTEGER
    • Required: True

Response:

  • Status:
    • Description: OK
    • Type: STRING

   user.token

Creates a login token for the user

   POST

Returns {token:ID}

Url: {Service-Desk-Server}/api/v1/user.token

Parameters:

  • id:
    • Description: User ID
    • Type: INTEGER
    • Required: True

Response:

  • token:
    • Description: Created token
    • Type: STRING

   users

Returns the user/s information by ID/s

   GET

Returns the user/s information by ID/s

Url: {Service-Desk-Server}/api/v1/users

Parameters:

  • ids:
    • Description: User IDs
    • Type: ARRAY
    • Required: True

Response: Returns ARRAY or single object with the following structure:

  • username:
    • Description: Username of the user
    • Type: STRING
  • id:
    • Description: ID of the user
    • Type: STRING
  • email:
    • Description: Email of the user
    • Type: STRING

   users.groups

Manages the User groups

   GET

Returns the user groups

Url: {Service-Desk-Server}/api/v1/users.groups

Parameters:

  • ids:
    • Description: User IDs
    • Type: ARRAY
    • Required: True

Response: Returns ARRAY of objects with the following structure:

  • username:
    • Description: Username of the user
    • Type: STRING
  • companies:
    • Description: Array with the companies of the user
    • Type: ARRAY
  • email:
    • Description: Email of the user
    • Type: STRING
  • groups:
    • Description: Array with the groups of the user
    • Type: ARRAY
  • helpdesks:
    • Description: Array with the helpdesks/levels of the user
    • Type: ARRAY
  • id:
    • Description: ID of the user
    • Type: STRING