How Can We Help?

< Back

API Details

 
In this chapter we give the full advanced documentation on Deepser API.
We assume you have already read the prevoius chapters:

 


API Endpoint

You access the resource by sending an HTTP request to the Deepser API server, after being authenticated.
The server replies with a response that contains either the data you requested, or the status indicator, or even both.
Common characteristics of Deepser REST API resources are as follows: (deepdeskhost is your domain)

  • To access the API you have to call the endpoint at: http[s]://deepdeskhost/api/rest/.
  • You request a particular resource by adding a particular path to the base URL that specifies the resource.
  • The server replies with a response that contains either the data you requested, or the status indicator, or even both.

 


 

Main Methods

You can access entities of Deepser, using the actions implemented by the API:

  • Retrieve: to get a single resource (HTTP GET)
  • Create: to create a single resource (HTTP POST)
  • Update: to update a single resource (HTTP PUT)
  • Delete: to delete a single resource (HTTP DELETE)
  • Multiple Retrieve: to get multiple resources (HTTP GET)
  • Multiple Create: to create multiple resources (HTTP POST)
  • Multiple Update: : to update multiple resources (HTTP PUT)

Note: Multiple Delete is not allowed for Security Reasons.

 

We will now explain in details every action.
In this guide the examples are all made using the Company entity.
We assume your Deepser installation host is http://deepdeskhost/.
After having explored the methods, we will list a detail of entities accessible by the API.

 

Retrieve

HTTP Method: GET
Base Syntax: http://deepdeskhost/api/rest/[entity]/[id]
Example Syntax: http://deepdeskhost/api/rest/company/4
Description: retrieves the entity data, given an entity ID.
Example Result: http://deepdeskhost/api/rest/company/4
[php]
{
“entity_id”: “4”,
“parent_id”: “1”,
“sort_order”: null,
“name”: “ACME UK”,
“description”: “ACME UK”,
“phone”: “08567565”,
“fax”: “8587575”,
“address”: “Carnaigehall Street”,
“city”: “London”,
“state”: “London”,
“country”: “UK”,
“zip_code”: “10000”,
“notes”: null,
“logo”: “company/image/a/c/acme_uk.png”,
“primary_contact”: “4\\nobel”,
“mailbox_id”: “0”,
“status”: “1”,
“formtemplate_id”: “56”,
“updated_at”: “2018-08-01 15:04:59”,
“created_at”: “2018-07-12 08:39:16”,
}
[/php]

 

Note that every custom field created in Deepser is retrieved by the API. Custom fields have the prefix cust_ before their name.
So, for example, if a user creates a field named website, the REST API will return a JSON property called cust_website.

 

Multiple Retrieve

HTTP Method: GET
Base Syntax: http://deepdeskhost/api/rest/[entities]?[filters]&[parameters]
Example Syntax: http://deepdeskhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&limit=2
Description: retrieves the entities data, given some filters or parameters.
Example Result: http://into.deep.lite/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&limit=2
[php]
{
“totalRecords”: 3,
“items”: [
{
“entity_id”: “1”,
“parent_id”: “0”,
“sort_order”: null,
“name”: “ACME International”,
“description”: “ACME International – Main Company of the group”,
“phone”: “0288396”,
“fax”: “998266”,
“address”: “Madison Square Garden”,
“city”: “NY”,
“state”: “NY”,
“country”: “USA”,
“zip_code”: “00195”,
“notes”: null,
“logo”: “company/image/a/c/acme_usa.png”,
“primary_contact”: “4\\euclid”,
“mailbox_id”: “0”,
“status”: “1”,
“formtemplate_id”: “56”,
“updated_at”: “2018-07-12 08:43:13”,
“created_at”: “2018-06-19 13:30:41”,
“payment_status”: null
},
{
“entity_id”: “2”,
“parent_id”: “1”,
“sort_order”: null,
“name”: “ACME France”,
“description”: “ACME France”,
“phone”: null,
“fax”: null,
“address”: “Roux de Strasse”,
“city”: “Paris”,
“state”: “Paris”,
“country”: “France”,
“zip_code”: “75000”,
“notes”: null,
“logo”: “company/image/a/c/acme_fr_1.png”,
“primary_contact”: “4\\euclid”,
“mailbox_id”: “0”,
“status”: “1”,
“formtemplate_id”: “56”,
“updated_at”: “2018-07-12 08:43:56”,
“created_at”: “2018-06-19 13:33:57”,
“payment_status”: null
}
]
}
[/php]
Where:

  • totalRecords is the number of items corresponding to the conditions of the query (note that is more than the limit we set).
  • items is a JSON array with all entities retrieved (eventually limited to the limit parameter).

 

Filters

When we deal with the multiple retrieve method, it is important to understand filters and parameters to get only a subset of data if we don’t need to retrieve all the entities of the system.

Think about filters as the where condition of a SQL Query, while parameters are clauses (limit, sort, etc.) for that query.
Deepser API filters are very simple to implement.
To define filters, just pass additional fields to the HTTP request query string.
The syntax to define filters is here described.
After the request path we define an array called filter.
This array has at least one element with key attribute to define the target field:

 

http://deepdeskhost/api/rest/companies?filter[1][attribute]=field

Where:

  • filter is our array to set filters
  • attribute is a constant key
  • field is the name of the field we want to apply the filter to

 

Then, we must define which kind of filter we want to apply to that field, by populating in the query string the element of the filter array with key corresponding to the kind of filter. The value of that element is the value to look for:

 

http://deepdeskhost/api/rest/companies?filter[1][attribute]=field&filter[1][operator]=value

Where:

  • filter is our array to set filters and the index 1 is the same of the attribute field we are referring to
  • operator is a key with the query operator we want to apply. Operators are described below
  • value is the value of the condition we want to apply to the filter

 

To filter a company by its name, taking all the companies with name starting with the string ‘ACME’, we should raise this GET request:

 

http://deepdeskhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%

 

Obviously, to implement more filters on different fields we can add more elements to our filter array:

 

http://deepdeskhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&filter[2][attribute]=country&filter[2][eq]=USA

This will filter all companies with name starting with ACME and country equals to USA.

 

Filter Operators

When we deal with filters, it is important to understand filter operators to create the query we need.
Here is a list of all operators that can be used:

 

  • eq – “equal to” – returns items with the specified attribute that is equal to the defined value
    http://deepdeskhost/api/rest/companies?filter[1][attribute]=name&filter[1][eq]=ACME
  • neq – “not equal to” – returns items with the specified attribute that is not equal to the defined value
    http://deepdeskhost/api/rest/companies?filter[1][attribute]=name&filter[1][neq]=ACME
  • in – “equals any of” – returns items that are equal to the item(s) with the specified attribute(s)
    http://deepdeskhost/api/rest/companies?filter[1][attribute]=name&filter[1][in]=ACME

    If we want to use multiple values for the in, we can use an additional array, so for example:

    http://deepdeskhost/api/rest/companies?filter[1][attribute]=name&filter[1][in][0]=ACME&filter[1][in][1]=Contoso
  • nin – “not equals any of” – returns items excluding the item with the specified attribute
    http://deepdeskhost/api/rest/companies?filter[1][attribute]=name&filter[1][nin]=ACME
  • gt – “greater than” – returns items with the specified attribute that is greater than the defined value
    http://deepdeskhost/api/rest/companies?filter[1][attribute]=parent_id&filter[1][gt]=0
  • lt – “less than” – returns items with the specified attribute that is less than the defined value
    http://deepdeskhost/api/rest/companies?filter[1][attribute]=parent_id&filter[1][lt]=1
  • like – “like” – returns items with the specified attribute is like the defined value. Use SQL like syntax to define wildcards chars.
    http://deepdeskhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%
  • nlike – “not like” – returns items with the specified attribute is not like the defined value. Use SQL like syntax to define wildcards chars.
    http://deepdeskhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%
  • from, to – “from to” – specifies the range of attributes according to which items will be returned.
    http://deepdeskhost/api/rest/companies?filter[1][attribute]=parent_id&filter[1][from]=2&filter[1][to]=3

 

You can write filters using AND, OR logical operators.
To do that follow the examples:

 

  • AND: to define a condition in AND, simply define multiple filters, like:
    http://deepdeskhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&filter[2][attribute]=parent_id&filter[2][gt]=0
  • OR: to define a condition in OR, use this syntax:
    http://deepdeskhost/api/rest/companies?filter[1][attribute]=entity_id&filter[1][0][eq]=1&filter[1][1][eq]=3

    So use multiple index arrays in the filters for the same field.
    To use an OR condition on different fields, use the following syntax:

    http://deepdeskhost/api/rest/companies?filter[1][attribute][0]=entity_id&filter[1][attribute][1]=name&&filter[1][0][eq]=3&filter[1][1][like]=ACME%

 

Parameters

When we deal with retrieve multiple method, it is important to understand parameters to create the query we need.
Here is a list of all parameters that can be used:

 

  • page: specifies the page number which items will be returned.
    http://deepdeskhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%&page=2
  • order: specifies the sort order of returned items.
    http://deepdeskhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%&order=name&dir=asc
  • dir: specifies the order direction: ‘asc’ – returns items in the ascending order; ‘dsc’ – returns items in the descending order.
    http://deepdeskhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%&order=name&dir=asc
  • limit: limits the number of returned items in the response. Note that by default, 10 items are returned in the response. The maximum number is 100 items.
    http://deepdeskhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%&limit=100

If the attribute value consists of several words separated by a whitespace, the ‘%20’ sign is used:

http://deepdeskhost/api/rest/companies?filter[1][attribute]=name&filter[1][eq]=ACME%20International%20LTS

 

Create

HTTP Method: POST
Base Syntax: http://deepdeskhost/api/rest/[entities]/
JSON Payload Syntax: a JSON object with the data to insert

Example Syntax: http://deepdeskhost/api/rest/companies
Example JSON Payload Syntax:
[php]
{
“name” : “ACME Portugal”,
“description” : “ACME Portugal SA.”
}
[/php]
Description: creates the entity, given the payload JSON data.
Example Result: http://deepdeskhost/api/rest/companies
[php]
{
“name”: “ACME Portugal”,
“description”: “ACME Portugal SA.”,
“created_at”: “2018-10-29 15:57:42”,
“updated_at”: “2018-10-29 15:57:42”,
“entity_id”: “8”
}
[/php]
Returns the company created, field entity_id is the ID of the new company.

 

Multiple Create

HTTP Method: POST
Base Syntax: http://deepdeskhost/api/rest/[entities]/
JSON Payload Syntax: A JSON Array containing the objects to insert

Example Syntax: http://deepdeskhost/api/rest/companies
Example JSON Payload Syntax:
[php]
[
{
“name” : “ACME Portugal”,
“parent_id” : “1”,
“description” : “ACME Portugal SA”
},
{
“name” : “ACME Spain”,
“parent_id” : “1”,
“description” : “ACME Portugal SA”
}
]
[/php]
Description: creates the entity, given the payload JSON data.
Example Result: http://deepdeskhost/api/rest/companies
[php]
{
“success”: [
{
“item”: {
“name”: “ACME Portugal”,
“description”: “ACME Portugal SA”,
“created_at”: “2018-10-29 15:59:30”,
“updated_at”: “2018-10-29 15:59:30”,
“entity_id”: “9”
},
“message”: “Resource created successful.”,
“code”: 200
},
{
“item”: {
“name”: “ACME Spain”,
“description”: “ACME Spain SA”,
“created_at”: “2018-10-29 15:59:30”,
“updated_at”: “2018-10-29 15:59:30”,
“entity_id”: “10”
},
“message”: “Resource created successful.”,
“code”: 200
}
]
}
[/php]
Returns a JSON object with 2 arrays: success with all the items created successfully, the code and the message; error with all the items not created due to an error, the error code and the message.

 

Update

HTTP Method: PUT
Base Syntax: http://deepdeskhost/api/rest/[entity]/[id]
JSON Payload Syntax: a JSON object with the data to update

Example Syntax: http://deepdeskhost/api/rest/company/5
Example JSON Payload Syntax:
[php]
{
“name” : “ACME Germany”,
“parent_id” : “1”,
“description” : “ACME Germany Gmbh”
}
[/php]
Description: creates the entity, given the payload JSON data.
Example Result: http://deepdeskhost/api/rest/companies
[php]
{
“entity_id”: “5”,
“parent_id”: “1”,
“sort_order”: null,
“name”: “ACME Germany”,
“description”: “ACME Germany Gmbh”,
“phone”: null,
“fax”: “+498587575”,
“address”: “Augsburger Strasse”,
“city”: “Berlin”,
“state”: “Berlin”,
“country”: “DE”,
“zip_code”: “10115”,
“notes”: null,
“logo”: null,
“primary_contact”: null,
“mailbox_id”: “0”,
“status”: “1”,
“formtemplate_id”: “0”,
“updated_at”: “2018-10-29 16:14:10”,
“created_at”: “2018-10-29 15:49:33”,
“payment_status”: null
}
[/php]
Returns a JSON Object with all fields of the entity updated (not only updated fields, but ALL fields of that entity).

 

Multiple Update

HTTP Method: PUT
Base Syntax: http://deepdeskhost/api/rest/[entities]/
JSON Payload Syntax: a JSON object with the data to update. Don’t forget to specify the ID of the company to update in the entitiy_id field

Example Syntax: http://deepdeskhost/api/rest/companies
Example JSON Payload Syntax:
[php]
[
{
“name” : “ACME Company Germany Gmbh”
},
{
“entity_id” : “6”,
“name” : “ACME Bulgaria”,
“description” : “ACME Company Bulgaria OOD”
}
]
[/php]
Description: updates the entity, given the payload JSON data.
Example Result: http://deepdeskhost/api/rest/companies/
[php]
{
“error”: [
{
“message”: “Invalid error \”Resource not found. \” or error code missed.”,
“code”: 500
}
],
“success”: [
{
“item”: {
“entity_id”: “6”,
“parent_id”: “1”,
“sort_order”: null,
“name”: “ACME Bulgaria”,
“description”: “ACME Company Bulgaria OOD”,
“phone”: null,
“fax”: null,
“address”: null,
“city”: null,
“state”: null,
“country”: null,
“zip_code”: null,
“notes”: null,
“logo”: null,
“primary_contact”: null,
“mailbox_id”: null,
“status”: null,
“formtemplate_id”: “0”,
“updated_at”: “2018-10-29 16:21:14”,
“created_at”: “2018-10-29 15:52:47”,
“payment_status”: null
},
“message”: “Resource updated successful.”,
“code”: 200
}
]
}
[/php]
Returns a JSON object with 2 arrays: success with all the items created successfully, the code and the message; error with all the items not created due to an error, the error code and the message.

 

Delete

HTTP Method: DELETE
Base Syntax: http://deepdeskhost/api/rest/[entity]/[id]
Example Syntax: http://deepdeskhost/api/rest/company/6
Description: deletes the entity, given an entity ID.
Example Result: http://deepdeskhost/api/rest/company/6
[php]
// this is only in case of an error
{
“messages”: {
“error”: [
{
“code”: 404,
“message”: “Resource not found.”
}
]
}
}
[/php]
If the entity is successfully deleted returns an empty response, else returns a JSON object with error messages.


 

Entities

Here you are the full list of Deepser entities implemented by the API:

  • Company: the companies of Deepser.
  • User: the users of Deepser.
  • Group: the user groups of Deepser.
  • Service Operation: the operations (tickets, incidents, requests, etc.) of Deepser.
  • Service Type: the types of the operations (incidents, requests, changes, phone calls, etc.).
  • Activity: the activities (comments or worklogs) of Deepser.
  • Cmdb CI: the CIs (devices, softwares, etc.) of Deepser.

 

Company

The Company entity is used to manage companies in Deepser.
Companies can be only created by Administrators that can access the Company Module.
Agents and Key Users can only retrieve the Companies.
End Users cannot access this resource via API.

Endpoints

http://deepdeskhost/api/rest/company/[id]
http://deepdeskhost/api/rest/companies

Roles

Here we list all the permissions by user role regarding the API:

 

  Admininistrator Agent Key User User
Actions Allowed RETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE RETRIEVE  

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

 

Field Meaning
entity_id The unique ID to identify the record.
name The name of the Company, that will be displayed on the select-boxes in the system.
parent_id The field “Parent” can contain the name of another company. If the Company has a parent, it means that we are configuring a sub-company (a branch of the main company). Think about an international corporation that has some local branches (eg: the head office is in the US and some branches in Europe). Thank to the Parent field we can create a hierarchical structure of maximum 2 levels to define companies in the system. The Parent concept can be eventually extended to more levels with a customization but the default configuration of Deepser allows 2 levels: in most cases it is enough to describe a company structure.
If we try to add more than 1 Parent level, the software returns a blocking error in the company form.
description Description of the Company.
status If the company is disabled it will not be displayed in the select-boxes.
mailbox_id This field is used to define that all the emails sent to users of that organization will be sent by a specific mailbox.
This field is rarely used and has the aim to send emails to a specific company from a pre-configured email address. If not set Deepser will use the system settings to send emails: the emails will be sent from the default outgoing mailbox, or, if the record has a specific mailbox set in the field “Outgoing Mailbox”, Deepser will use the specific mailbox only for that records.
logo Company Logo.
address Company Address.
city Company City.
state State / Area.
country Country of the company.
zip_code Zip Code.
primary_contact User of Deepser that is marked as a primary contact for that company.
phone Main phone number.
fax Fax.
notes Internal notes.
formtemplate_id The form template ID used by the record. Please refer to the Formtemplate ID guide of Deepser Docs.
updated_at Last update date of the record.
created_at The creation date of the record.

 

User

The User entity is used to manage users that can login to Deepser.
Users can be only created by Administrators that can access the User Module.
Agents and Key Users can only retrieve the Users.
End Users cannot access this resource via API.

Endpoints

http://deepdeskhost/api/rest/user/[id]
http://deepdeskhost/api/rest/users

Roles

Here we list all the permissions by user role regarding the API:

 

  Admininistrator Agent Key User User
Actions Allowed RETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE RETRIEVE  

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

 

Field Meaning
user_id The unique ID to identify the record.
avatar Icon with the user avatar. If not set, it will be chosen randomly from the system.
username Username used by a user to access the software. It is the field that uniquely identifies the user.
Username is thus used for the login to Deepser. If we create manually a user, we can choose the username we want.

Obviously, user name must be unique otherwise the system will block the creation of a user with a username already in use.
If we insert users with the LDAP integration the username will be the LDAP attribute we chose when configuring the integration, but Deepser prepend a number and a backslash (\) to identify the ID of the LDAP directory from which we are importing the user.
In case of LDAP users, the login screen of Deepser will change, adding a select-box to choose the domain. This select-box is thus mandatory for the users with an LDAP account.
A user manually inserted has, for example, this username: admin or name.surname, or rather the email of the user.
A user imported from LDAP will have, for example, this username: 1\name or 1\name.surname.
Looking at the ID of the LDAP directory we can easily find from which LDAP source the user has been imported.

role The role of the user. Please refer to the Roles in your system to get the correct IDs.
firstname First name of the user
lastname Last name of the user
email Email of the user to receive notifications. Email is a very important field if we activate the email integration: Deepser send all the emails to users according to this value.
password Password to log into the system. Password is encrypted in the database. If a user is an LDAP user the password will not be saved in the database, but the system will try to authenticate directly to the LDAP server.
is_active It tells if an user is active in the system. Non-active users are not displayed in the select-boxes of Deepser modules, cannot receive emails and cannot log into the system.
startup_page Page to which the user is redirected after the login. This field contains a list of all the system pages.
locale Language of the user. Deepser has a native support to many languages. It is possibile to translate the software using this short guide: Translate Deepser
timezone Timezone of the user. Timezone is applied when displaying the dates on the interface. Infact, in the Deepser DataBase all dates are stored referring to the system timezone: UTC. This setting allows the system to manage all the dates with consistency and not to have problem with the variaton of dates based on the location of a user.
company_id Company of the user. All users can be part of one (and only one) company. Companies are explained in that guide: Company Guide.
Companies can be grouped in a 2 level structure: one company is the Parent and can have multiple sub-companies. That way we can manage the visibility of the requests allowing, for example, a corporate manager to see all the sub-company requests and allowing a director of a sub-company to see only data of his smaller organization.
is_supervisor If the user is a supervisor he can see data of all users of the company (and sub-companies). This field is very important to determine which data cha see a user within his organization. If the user is a supervisor and can access the back-end (Administrator, Agent, Key-User) he can see all data of his Company and sub-companies. This is true if the user has the field Company Visibility set to Limit Data to Company. On the contrary, the user can see all data in the system.
If we talk about a user with type “User” (an end user/customer), this user can only see the data regarding his requests (and no other). But, if the user is configured as supervisor can see all the Service Operations of his Company (and sub-companies if present).
company_visibility A user with this field set can see only data of his company (and sub-companies). If a user access the back-end this field is very useful to limit the visibility. Think, for example, to an operator that can only manage requests from his brach. If we create a company specifically for the branch and limit the data of the user to that branch, the operator will not see any other company data.
Talking about a user of type “User” this field is always ignored, because the user can only see his records and if the field Is Supervisor is set to true, then he can also see the data of his company.
formtemplate_id The form template ID used by the record. Please refer to the Formtemplate ID guide of Deepser Docs.
modified Last update date of the record.
created The creation date of the record.
display_username The username displayed in the system (typically Firstname + Lastname).

 

Group

The Group entity is used to manage user groups in Deepser.
Groups can be only created by Administrators that can access the Group Module.
Agents and Key Users can only retrieve the Groups.
End Users cannot access this resource via API.

Endpoints

http://deepdeskhost/api/rest/group/[id]
http://deepdeskhost/api/rest/groups
http://deepdeskhost/api/rest/group/[id]/relation/users

Roles

Here we list all the permissions by user role regarding the API:

 

  Admininistrator Agent Key User User
Actions Allowed RETRIEVE
CREATE
UPDATE *
DELETE
RETRIEVE RETRIEVE  

* UPDATE not allowed for endpoint: http://deepdeskhost/api/rest/group/[id]/relation/users

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

 

Field Meaning
entity_id The unique ID to identify the record.
name The name of the group displayed in the system.
description Description of the group.
email Email address of the group.
level Support level of the group
status The status of the group. Typically 1 is Enabled, 0 is Disabled.
company_visibility This is similar to company_visibility of the Users. This is a general setting used to set the visibility for all members of the group.
user_ids An Array containing all the users of the group.
formtemplate_id The form template ID used by the record. Please refer to the Formtemplate ID guide of Deepser Docs.
updated_at Last update date of the record.
created_at The creation date of the record.

 

To get only the users in a group (without all the group information) you must use the GET method with the endpoint:

http://deepdeskhost/api/rest/group/[id]/relation/users

It returns an array with the IDs of the users.

 

To add users in a group you must use the POST method with the endpoint:

http://deepdeskhost/api/rest/group/[id]/relation/users

JSON Payload Syntax: a JSON array with an array of the data to insert

 

[php]
[
[
21,
22
]
]
[/php]

 

To delete users from a group you must use the DELETE method with the endpoint:

http://deepdeskhost/api/rest/group/[id]/relation/users

JSON Payload Syntax: a JSON array with an array of the data to delete

 

[php]
[
[
21,
22
]
]
[/php]

 

Service Operation

The Service Operation entity is used to manage Operations (tickets) in Deepser.
Service Operations can be accessed by every user.

Endpoints

http://deepdeskhost/api/rest/service/operation/[id]
http://deepdeskhost/api/rest/service/operations

Roles

Here we list all the permissions by user role regarding the API:

 

  Admininistrator Agent Key User User
Actions Allowed RETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

 

Field Meaning
entity_id The unique ID to identify the record.
type_id The Type ID of the operation record (it is the numerical ID of the entity type: incident, request, change, etc.).
title The title of the operation. A brief description.
category1 The category (1st level) of the operation. It is an important field to manage the assignment to working teams and to catalog correctly the scope of the activity requested.
category2 The category (2nd level) of the operation. It is an important field to manage the assignment to working teams and to catalog correctly the scope of the activity requested.
category3 The category (3rd level) of the operation. It is an important field to manage the assignment to working teams and to catalog correctly the scope of the activity requested.
description Extended description of the request.
status It is the status of the operation. It is an important value to manage the lifecycle of the request.
priority_id Priority of the operation: the importance from the working team perspective.
urgency_id Urgency of the operation: the importance from the requester user perspective.
submit_username The user that has created the record (he can be different from the Requester User that is the user actually requesting an activity). Think about a secretary that is submitting a request on behalf of his boss. The Submit User is the secretary, while the Requester User is the chief officer.
requester_username User that is actually requesting a service.
assigned_group_id Working team that is working to solve the request.
assigned_username User that has taken in charge the request. He is typically an Agent or a Key User. Deepser lets you assign also to end users if we decide that they can be part of the resolution process.
created_at Creation date of the record.
updated_at Date of the last update on the system.
closed_at Closing date of the record. If a record changes status from closed to re-opened, the this date is reset to null.
archived Every Operation can be archived, for example we can archive all closed Operations of the past 5 years to hide them in the standard grids (but we could see them in the Archived grid).
archived_at Archived date of a request.
updated_by The user that has lat updated the request.
deleted Every Operation can be deleted setting the status to “Deleted” (or other status belonging to the Deleted class). All deleted requests will not be physically deleted from the database, but they will be only marked as deleted (soft delete, so they will be visibile in the Deleted grid). To delete physically use the button “Delete”. The record will not be recoverable anymore.
deleted_at Deleted date of the request.
mailbox_id The mailbox that will be used to send notifications regarding the Operation. If empty the default outgoing mailbox will be used (if set).
due_date The agreed date for the resolution.
version The version of the request. Deepser stores in its DataBase every version of the Operations. We can always know the changes, the user that made a change and the date.
solution The solution of a request, that can be emailed to the requester user or exposed on the portal.
formtemplate_id The formtemplate id of the record.

 

Service Type

The Service Type entity is used to manage the type of Operations in Deepser (eg: Incidents, Tickets, Requests, Phone Calls, etc.).
Service Types can be defined or updated only in the Deepser interface.
Service Types can be only retrieved by Administrators, Agents or Key Users via API.
End Users cannot access this resource via API.

Endpoints

http://deepdeskhost/api/rest/service/type/[id]
http://deepdeskhost/api/rest/service/types

Roles

Here we list all the permissions by user role regarding the API:

 

  Admininistrator Agent Key User User
Actions Allowed RETRIEVE RETRIEVE RETRIEVE  

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

 

Here we list all the fields of the entity to describe their meainings in Deepser:

 

Field Meaning
entity_id The unique ID to identify the record.
name The Name of the Type (eg: Incident, Request, Change, etc.).
description The description of the Type.
icon The icon of the Type.
position The order in which are displayed the Types.
status 1 if the Type is Enabled, 0 if it is Disabled.
formtemplate_id The formtemplate ID of the record.
created_at Creation date of the record.
updated_at Date of the last update on the system.

 

Activity

The Activity entity is used to manage all the comments and worklogs in Deepser.
Activities can be accessed by all user Roles in the API.
Activities API access changes based on the Main Model (model_alias) the Activity is referring to.
At the moment Activity are supported for Service Operation Model only.

Endpoints

http://deepdeskhost/api/rest/service/operation/[operation_id]/activity/[activity_id]
http://deepdeskhost/api/rest/service/operation/[operation_id]/activities

Roles

Here we list all the permissions by user role regarding the API:

 

  Admininistrator Agent Key User User
Actions Allowed RETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE *
CREATE *

* A user can create only Activity of type Comment and the created_by User is forced to the End User itself by default.

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

 

Field Meaning
entity_id The unique ID to identify the record.
type 1 for Comments, 2 for Worklogs.
description The description of the Activity.
portal_visibility If 0 the Activity is not visibile to the End Users. If 1 it is visibile in the User Portal.
position The order in which are displayed the Types.
started_at Date when the activity has started.
ended_at Date when the activity has ended.
duration The duration of the activity.
created_by The user who created the record.
model_alias The Deepser model the Activity refers to. For example, if the activity is related to a ticket (operation) the model_alias will be deep_service/operation.
model_id The Deepser model ID the Activity refers to. It is the unique ID of the model identified by model_alias field.
status The status of the Activity (Enabled / Disabled).
formtemplate_id The formtemplate ID of the record.
created_at Creation date of the record.
updated_at Date of the last update on the system.

 

Cmdb CI

The CMDB CI entity is used to manage all CIs in Deepser (devices, softwares, contracts, etc.).
CIs can be created by Administrators, Agents and Key Users.
End Users cannot access this resource via API.

Endpoints

http://deepdeskhost/api/rest/cmdb/ci/[id]
http://deepdeskhost/api/rest/cmdb/cis

Roles

Here we list all the permissions by user role regarding the API:

 

  Admininistrator Agent Key User User
Actions Allowed RETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE
DELETE
 

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

 

Field Meaning
name The name of the CI. Usually a brief description.
type_id The type of the CI. It is a very important value to manage the organization of the CMDB.
subtype_id The Subtype of the CI. It is a very important value to manage the organization of the CMDB.
category1 The category (1st Level) of the CI. It can be used according to the category of the Service module, in order to link Operations and CIs.
category2 The category (2nd Level) of the CI. It can be used according to the category of the Service module, in order to link Operations and CIs.
category3 The category (3rd Level) of the CI. It can be used according to the category of the Service module, in order to link Operations and CIs.
description Large description of the CI.
status The status of the CI. It is an important value to manage the lifecycle of the element.
priority_id Priority of the CI from the operator perspective.
urgency_id Urgency of the CI from the requester user perspective.
business_impact_id Business Impact of the CI from the organization perspective. If a CI is not available, the business impact represents the enormity of the situation and can be in terms of people, finances, systems, etc. For example, it can describe: the number of people affected by the CI outage or the potencial financial losses, or the number of other systems affected.
serial_number The serial number of the CI.
notes Large Notes field.
front_image The main image of the CI.
back_image The back image of the CI. For example, if the CI is a rack, we can take a photo of the back side in order to see the connections or the cables.
assigned_company_id Company that has taken in charge the CI. It is typically a Service Provider Company that has to monitor the CI. This field is very important to give the right visibility on the CIs. If a user has company restricted visibility, he cannot see CIs of other companies. Notice that a user with restricted company visibility can always see both CIs with its company in the Assigned Company OR Owner Company field.
assigned_group_id User Group that has taken in charge the CI. It is typically a Service Provider Group of agents/key users that has to monitor the CI. This field can be left blank if there is no specific group assigned to the CI, otherwise it can be used to restrict permissions to groups.
assigned_username The users who has taken in charge the CI. It is typically a Service Provider agent/key user that has to monitor the CI. This field can be left blank if there is no specific user assigned to the CI, otherwise it can be used to restrict permissions to single users.
owner_company_id Company that is the owner of the CI. It is typically a Customer Company that uses the CI. This field is very important to give the right visibility on the CIs. If a user has company restricted visibility, he cannot see CIs of other companies. Notice that a user with restricted company visibility can always see both CIs with its company in the Assigned Company OR Owner Company field.
owner_group_id User Group that owns the CI. It is typically a Customer or User Group of end users that can open requests on the CI. This field can be left blank if there is no specific group that owns the CI, otherwise it can be used to restrict permissions to groups (eg: when a user submits a request it could link only CIs owned by his user group).
owner_username User that owns the CI. It is typically a Customer or end user who can open requests on the CI. This field can be left blank if there is no specific user that owns the CI, otherwise it can be used to restrict permissions to users (eg: when a user submits a request it could link only CIs owned by himself).
version The version of the CI. Deepser stores in its DataBase every version of the CIs. We can always know the changes, the user that made a change and the date.
created_at Creation date of the record.
updated_at Date of the last update on the system.
updated_by The user that has lat updated the CI.
Previous Introduction to Deepser API
Table of Contents