Integria IMS API

Go back to Integria IMS Documentation Index

Integria IMS external API is used by making remote calls through HTTP or HTTPS on the /include/api.php file. With this method, it is possible to integrate third party applications with Integria IMS. The use of the API is done through a call with defined parameters that returns a value or a list of values.

The API call prototype is as follows:

http:///include/api.php

Where is the IP address or public URL where Integria IMS is installed. The API method only accepts the following parameters ( ), any other parameters will be ignored:

user (mandatory): Name of the Integria IMS user who accesses the data, it is used to verify ACL rules.
user_pass (mandatory): User password.
op (mandatory): Operation to be carried out. The operations are detailed below.
pass (mandatory if enabled ): API specific password, configured in Integria IMS Console.
params: List of parameters that will be passed to the function separated by a token.
token: Character that separates the different parameters (the comma , is used by default).
return_type: Call resulting format, it can be XML or CSV (CSV by default).
info: Special parameter with which the version can be obtained before authenticating.

Security

Authentication for Integria IMS API method is carried out in three steps:

Authentication by valid IP address

Security is based on a list of IP addresses that will have access to the tool. This list can be created in Integria IMS configuration menu.

It is important to bear in mind that this authentication method is always active so if you do not want to use it, it will be necessary to enter the asterisk * character to denote that any IP address is authorized.

It is recommended to always use a specific list of IP addresses.

Password authentication

Within Integria IMS configuration menu, it is possible to set a specific password for the API. This password must be sent in the API call without encryption, therefore HTTPS must be used if you want to use this authentication method.

If this password is empty, it means that password authentication is disabled and it is unnecessary to enter the token pass in the API call.

User and user password authentication

It is necessary for all calls (except for information calls) to specify the username (user) and the user's password (user_pass). There is no way to disable this authentication step.

API functions

Return of information about Integria IMS

This is a special function that can be used without authentication, since the information it returns in the same way can be obtained from the login screen publicly.

It returns the installed version of Integria IMS and is useful to verify that an Integria IMS installation is active in this path or to obtain the version before authentication.

Example call:

http://127.0.0.1/integria/include/api.php?info=version

Example result:

Integria IMS OpenSource Edition 5.0.93 Build 210526 MR86

get_incidents

Result: It returns a list of tickets the calling user has access to.

Serialized parameters:

String filter: It displays only tickets that contain that string in the title or description (not required). Empty for all tickets. The use of uppercase and lowercase letters for the search is indifferent.
Status filter: Identify the state (not mandatory). It may take the following values:
- 0 → All (default).
- 1 → New.
- 2 → Not confirmed.
- 3 → Assigned.
- 1 → Re-opened.
- 5 → Pending closure.
- 6 → Pending from a third person.
- 7 → Closed.
- -10 → For all but the closed ones.
Group filter: Group identifier (required). One (1) for all groups.
Priority filter: Priority identifier (optional). It may have the following values:
- 10 → Maintenance.
- 0 → Informative.
- 1 → Low.
- 2 → Average.
- 3 → Severe.
- 4 → Very servere.
- -1 → Any.
Inventory filter: Related inventory identifier (optional). Zero (0) for all or none.
Owner filter: Identifier of the user the incident is assigned to (optional).
Creator filter: Identifier of the user the incidence is assigned to (optional).
Incidence filter: Incidence identifier (optional).

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents&params=day,-10,1,-1,0,admin,user1

Example result in CSV format:

5,"2016-01-19 11:19:42","0000-00-00 00:00:00",incidence_title,admin,1,1,2,"2014-01-19 11:19:42",,1,0,0,,1,0,0,1,0,[email protected],,0,"2014-01-20 14:45:01",,,,0,0,0,0,0,0,0

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents&params=day,-10,1,-1,0,admin,user1&return_type=xml

Example result in XML:

<xml version='1.0' encoding='UTF-8'>
  <incident>
     <id_incidencia><![CDATA[5]]></id_incidencia>
     <inicio><![CDATA[2016-01-19 11:19:42]]></inicio>
     <cierre><![CDATA[0000-00-00 00:00:00]]></cierre>
     <titulo><![CDATA[Titulo incidencia]]></titulo>
     <descripcion><![CDATA[Descripcion]]></descripcion>
     <id_usuario><![CDATA[admin]]></id_usuario>
     <estado><![CDATA[1]]></estado>
     <prioridad><![CDATA[1]]></prioridad>
     <id_grupo><![CDATA[2]]></id_grupo>
     <actualizacion><![CDATA[2016-01-19 11:19:42]]></actualizacion>
     <id_creator><![CDATA[]]></id_creator>
     <notify_email><![CDATA[1]]></notify_email>
     <id_task><![CDATA[0]]></id_task>
     <resolution><![CDATA[0]]></resolution>
     <epilog><![CDATA[]]></epilog>
     <id_parent><![CDATA[1]]></id_parent>
     <sla_disabled><![CDATA[0]]></sla_disabled>
     <affected_sla_id><![CDATA[0]]></affected_sla_id>
     <id_incident_type><![CDATA[1]]></id_incident_type>
     <score><![CDATA[0]]></score>
     <email_copy><![CDATA[[email protected]]]></email_copy>
     <editor><![CDATA[]]></editor>
     <id_group_creator><![CDATA[0]]></id_group_creator>
     <last_stat_check><![CDATA[2016-01-20 14:55:01]]></last_stat_check>
     <closed_by><![CDATA[]]></closed_by>
     <extra_data><![CDATA[]]></extra_data>
     <extra_data2><![CDATA[]]></extra_data2>
     <blocked><![CDATA[0]]></blocked>
     <old_status><![CDATA[0]]></old_status>
     <old_resolution><![CDATA[0]]></old_resolution>
     <old_status2><![CDATA[0]]></old_status2>
     <old_resolution2><![CDATA[0]]></old_resolution2>
     <workunits_hours><![CDATA[0]]></workunits_hours>
     <workunits_count><![CDATA[0]]></workunits_count>
  </incident>
</xml>

get_incident_details

Result: It returns the details of a ticket.

Parameters:

Ticket identifier (required).

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incident_details&params=2

Example result in CSV format:

1,"2010-02-17 01:35:35","0000-00-00 00:00:00",Myfddfe,,demo,1,1,3,3,"2010-02-17 01:50:05",user,1,0,0,,,0,0,0,0

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incident_details&params=2&return_type=xml

Example result in XML:

<xml>
   <id_incidencia>1</id_incidencia>
       <inicio>2010-02-17 01:35:35</inicio>
       <cierre>0000-00-00 00:00:00</cierre>
       <titulo>Myfddfe</titulo>
       <descripcion></descripcion>
       <id_usuario>demo</id_usuario>
       <origen>1</origen>
       <estado>1</estado>
       <prioridad>3</prioridad>
       <id_grupo>3</id_grupo>
       <actualizacion>2010-02-17 01:50:05</actualizacion>
       <id_creator>admin</id_creator>
       <notify_email>1</notify_email>
       <id_task>0</id_task>
       <resolution>0</resolution>
       <epilog></epilog>
       <id_parent></id_parent>
       <sla_disabled>0</sla_disabled>
       <affected_sla_id>0</affected_sla_id>
       <id_incident_type>0</id_incident_type>
       <score>0</score>
</xml>

create_incident

Result: A ticket is created.

User: It is the ticket creator.

Parameters:

Title (required). Empty titles are not supported. To enter commas in this parameter, it must be replaced by (:::), to enter a space you must use %20. For example, to enter Doe, John insert in the URL: Doe:::%20John.
Group identifier (required).
Priority (not mandatory). It may have these values:
- 10 → Maintenance.
- 0 → 1 Informative (informative, by default).
- 1 → 2 Low (low priority).
- 1 → 3 Medium (medium priority).
- 3 → 4 Serious (serious priority).
- 4 → 5 Very serious (very serious priority).
Description (not mandatory). Empty by default. To enter commas in this parameter, it must be replaced by (:::), to enter a space you must use %20. For example, to enter Doe, John insert in the URL: Doe:::%20John.
Inventory identifier (not required). It is possible to create incidents with several inventory objects and they will have to be separated from each other by :
Incidence type identifier (not mandatory) Zero 0 (none) by default.
Copy email (not mandatory): Empty by default.
Owner (not required). By default admin.
Parent ticket identifier (not mandatory). By default, zero 0 (no parent).
State (required). It may take the following values:
- 1 → New (by default).
- 2 → Not confirmed.
- 3 → Assigned.
- 4 → Re-opened.
- 5 → Pending closure.
- 6 → Pending from a third person.
- 7 → Closed.
Info_extra (not mandatory).
Resolution:
- 0 → None (by default).
- 1 → Fixed (solved).
- 2 → Invalid.
- 3 → Won't fix (will not be fixed).
- 4 → Duplicate.
- 5 → Works for me.
- 6 → Incomplete.
- 7 → Expired.
- 8 → Moved.
- 9 → In process.
Info_extra2 (not mandatory).
Info_extra3 (not mandatory).
Info_extra4 (not mandatory).
FieldTypeIncidence1.
FieldTypeIncidence2
FieldTypeIncidence3.
…
FieldTypeIncidenceN.

Example call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_incident&params=Titulo%20de%20la%20incidencia,2,1,Descripcion%20de%20la%incidencia,1:2:3,1,[email protected],admin,0,1

Example result in CSV format:

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_incident&params=Titulo%20de%20la%20incidencia,2,1,Descripcion%20de%20la%incidencia,1:2:3,1,[email protected],admin,0&return_type=xml

Example result in XML:

<xml>
0
</xml>

update_incident

Result: It updates the data of a ticket.

Parameters:

Ticket identifier (required).
Title (required). Empty titles are not supported.
Description (not mandatory). Empty by default.
Epilogue (not mandatory). Empty by default.
Group identifier (required).
Priority (not mandatory). It may have these values:
- 10 → Maintenance.
- 0 → 1 Informative (informative, by default ).
- 1 → 2 Low (low priority).
- 1 → 3 Medium (medium priority).
- 3 → 4 Serious (serious priority).
- 4 → 5 Very serious (very serious priority).
Resolution.
- 0 → None (by default).
- 1 → Fixed (solved).
- 2 → Invalid.
- 3 → Won't fix (will not be fixed).
- 4 → Duplicate.
- 5 → Works for me.
- 6 → Incomplete.
- 7 → Expired.
- 8 → Moved.
- 9 → In process.
State (required). It may take the following values:
- 1 → New (by default).
- 2 → Not confirmed.
- 3 → Assigned.
- 1 → Re-opened.
- 5 → Pending closure.
- 6 → Pending from a third person.
- 7 → Closed.
Owner (not required). By default admin.
Parent ticket identifier (not mandatory). By default, zero 0 (no parent).
Incidence type identifier (not mandatory) Zero 0 (none) by default.
Info_extra (not mandatory).
Info_extra2 (not mandatory).
Info_extra3 (not mandatory).
Info_extra4 (not mandatory).
FieldTypeIncidence1.
FieldTypeIncidence2
FieldTypeIncidence3.
…
FieldTypeIncidenceN.

If you do not want to modify the current value of the ticket type fields, fill in these fields with their corresponding value. In the case of being empty, they will be updated without value.

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&pass=api_pass&op=update_incident&params=4,nuevo%20titulo,nueva%20descripcion,nuevo%20epilogo,4,2,1,3,admin,0,6,,Soporte,Hardware

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&pass=api_pass&op=update_incident&params=4,nuevo%20titulo,nueva%20descripcion,nuevo%20epilogo,4,2,1,1,3,admin,0,6,Soporte,Hardware&return_type=xml

Result example in XML:

<xml>
0
</xml>

add_inventory_to_ticket

Result: It allows you to associate an inventory item to a ticket.

Parameters:

Ticket identifier (required).
Inventory item identifier (required).

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=add_inventory_to_ticket&params=1,2

Example result in CSV:

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=add_inventory_to_ticket&params=1,2&return_type=xml

Example result in XML:

<xml>
1
</xml>

delete_incident

Result: A ticket is deleted.

Parameters:

Ticket identifier (required).

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&pass=api_pass&op=delete_incident&params=3

Example result in CSV format:

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&pass=api_pass&op=delete_incident&params=3&return_type=xml

Result example in XML:

<xml>
0
</xml>

get_incident_workunits

Result: It returns a list with the Workunits associated with a ticket.

Parameters:

Ticket identifier (required).

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=user_pass&pass=api_pass&op=get_incident_workunits&params=3

Example result in CSV format:

3,"2010-02-17 01:48:48",0.25,admin,"Workunit description",0,0,,1
2,"2010-02-17 01:47:41",0.25,admin,"Another workunit description",0,0,,1

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=user_pass&pass=api_pass&op=get_incident_workunits&params=3&return_type=xml

Example result in XML:

<xml>
        <workunit>
                  <id>3</id>
                  <timestamp>2010-02-17 01:48:48</timestamp>
                  <duration>0.25</duration>
                  <id_user>admin</id_user>
                  <description>Workunit description</description>
                  <have_cost>0</have_cost>
                  <id_profile>0</id_profile>
                  <locked></locked>
                  <public>1</public>
        </workunit>
        <workunit>
                  <id>2</id>
                  <timestamp>2010-02-17 01:47:41</timestamp>
                  <duration>0.25</duration>
                  <id_user>admin</id_user>
                  <description>Another workunit description</description>
                  <have_cost>0</have_cost>
                  <id_profile>0</id_profile>
                  <locked></locked>
                  <public>1</public>
        </workunit>
</xml>

create_workunit

Result: Create a Workunit on a ticket.

Parameters:

Ticket identifier (required).
Description (not mandatory). Empty by default.
Duration in hours (not mandatory). By default 0.00 hours.
If it has had a cost (not mandatory). By default, no.
Whether it is public or not (not mandatory). By default, no.
Associated profile identifier (not mandatory). By default zero 0, without associated profile.

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_workunit&params=1,Descripcion,0.5,0,1,1

Example result in CSV format:

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_workunit&params=1,Descripcion,0.5,0,1,1&return_type=xml

Example result in XML:

<xml>
0
</xml>

get_incident_files

Result: It returns a list with the files associated with a ticket.

Parameters:

Ticket identifier (required).

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass=&pass=api_pass&op=get_incident_files&params=1

Example result in CSV format:

1,1,0,0,admin,file1.php,"php example",764026
2,1,0,0,admin,file2.png,"png example",34026

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass=&pass=api_pass&op=get_incident_files&params=1&return_type=xml

Example result in XML:

<xml>
  <file>
      <id_attachment>1</id_attachment>
      <id_incidencia>1</id_incidencia>
      <id_task>0</id_task>
      <id_kb>0</id_kb>
      <id_usuario>admin</id_usuario>
      <filename>file1.php</filename>
      <description>php example</description>
      <size>764026</size>
  </file>
  <file>
      <id_attachment>2</id_attachment>
      <id_incidencia>1</id_incidencia>
      <id_task>0</id_task>
      <id_kb>0</id_kb>
      <id_usuario>admin</id_usuario>
      <filename>file2.png</filename>
      <description>png example</description>
      <size>34026</size>
  </file>
</xml>

download_file

Result: Returns the content of a file as text, in Base64 .

Parameters:

File identifier (required).

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=download_file&params=32

Example result in CSV format:

[file content in base64]

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents&params=day,-10,1&return_type=xml

Example result in XML:

<xml>
[file content in base64]
</xml>

attach_file

Result: Add a file to the file list of a ticket.

Parameters:

Ticket identifier: (not mandatory), zero 0 by default.
File name: (not mandatory).
File size in Bytes: (not mandatory), by default zero 0.
File description: (not mandatory), empty by default.
File content in Base64 (not mandatory) by default is created with empty content.

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=attach_file&params=1,example.txt,234,Fichero
%20de%20ejemplo,aW50ZWdyaWEgcm9ja3M=

Example result in CSV format:

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=attach_file&params=1,example.txt,234,Fichero
%20de%20example,aW50ZWdyaWEgcm9ja3M=&return_type=xml

Example result in XML:

<xml>
0
</xml>

delete_file

Result: It deletes a file from the ticket file list.

Parameters:

File identifier (required).

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=delete_file&params=32

Example result in CSV format:

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=delete_file&params=32&return_type=xml

Example result in XML:

<xml>
0
</xml>

create_user

Result: Call used to create a user and assign it to a role or group. To assign more profiles, use a different call. It returns one 1 if created successfully, zero 0 otherwise.

Parameters:

Username (required). To enter commas in this parameter, it must be replaced by (:::), to enter a space you must use %20. For example, to enter Doe, John insert in the URL: Doe:::%20John.
Group identifier (required).
Profile identifier (required).
Email (not mandatory). Empty by default.
Password (not mandatory). User password, by default it is the user's name.
Description (not mandatory). Empty by default. To enter commas in this parameter, it must be replaced by (:::), to enter a space you must use %20. For example, to enter Doe, John insert in the URL: Doe:::%20John.
Real name (not mandatory). Empty by default.
Externaluser (not mandatory). By default it is zero 0.

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_user&params=jorge,3,4,[email protected],
userpass,description,George%20Surname,1

Example result in CSV format:

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_user&params=jorge,3,4,[email protected],userpass,description,
George%20Surname,1&return_type=xml

Example result in XML:

<xml>
1
</xml>

validate_user

Outcome: It returns one 1 if authentication is successful, zero 0 otherwise.

Parameters:

User: Name of the registered user that you may want to validate (mandatory).
Pass: User password (required).

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?&user=user&user_pass=userpass&pass=api_pass&op=validate_user&params=jorge,jorge_pass

Example result in CSV format:

Call example result in XML:

http://127.0.0.1/integria/include/api.php?&user=user&user_pass=userpass&pass=api_pass&op=validate_user&params=jorge,jorge_pass
&return_type=xml

Example result in XML:

<xml>
1
</xml>

delete_user

Outcome: Call used to delete a user. It returns one 1 if deleted successfully, zero 0 otherwise.

admin cannot be deleted through the API.

Parameters

User: (required).

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=delete_user&params=pepe

Example result in CSV format:

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=delete_user&params=pepe&return_type=xml

Example result in XML:

<xml>
1
</xml>

user_exists

Outcome: Call used to verify whether a user exists. It returns one 1 if it exists, zero 0 if it does not exist.

Parameters:

User: (required).

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=user_exists&params=pepe

Example result in CSV format:

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=user_exists&params=pepe&return_type=xml

Example result in XML:

<xml>
1
</xml>

create_lead

Outcome: Call used to create a lead . It returns one 1 if created successfully, zero 0 otherwise.

Parameters:

Full name (required). To enter commas in this parameter, it must be replaced by (:::), to enter a space you must use %20. For example, to enter Doe, John insert in the URL: Doe:::%20John.
Company (required).
Email (required).
Country (not mandatory). Empty by default.
Estimated sale (not mandatory). Zero 0 by default.
Progress (as a percentage, not mandatory). By default 0%.
Phone number (not mandatory). Empty by default.
Phone number (not mandatory). Empty by default.
Position (not mandatory). Empty by default.
Owner (required). User name.
Language: Language code (required).
- de → Deutch (German).
- en_GB → English.
- es → Spanish.
- fr → Français (French).
- pl → Polski (Polish).
- ru → Русский (Russian).
- zh_CN → 简化字 (Chinese).
Comments (not mandatory). To enter commas in this parameter, it must be replaced by (:::), to enter a space you must use %20. For example, to enter Doe, John insert in the URL: Doe:::%20John.
Category identifier (not required). Zero 0 (none) by default.
Directed by (not required). By default it is zero 0.
Campaign (not mandatory). By default it is zero 0.
Label separator or tags (required if they multiple tags are added).
Tag names: Divided with the separator declared above. If the tags do not exist, they will not be stored.

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_lead&params=Dario%Rodriguez%Perez,Artica+ST,[email protected],Spain,230,0,55566677,6665577,Developer,admin,es,This%20comment%20is%20very%20important,1,0,7,-%7C-,Software-%7C-Hardware-%7C-Tag%20con%20espacios

Example result in CSV format:

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_lead&params=Dario%Rodriguez%Perez,Artica+ST,[email protected],Spain,230,0,55566677,6665577,Developer,admin,es,This%20comment%20is%20very%20important,1,0,7,-%7C-,Software-%7C-Hardware-%7C-Tag%20con%20espacios&return_type=xml

Example result in XML:

<xml>
1
</xml>

get_last_invoice_id

Outcome: Call used to get the last invoice identifier. It returns the last invoice identifier, empty if unsuccessful.

Parameters: none.

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_last_invoice_id

Example result in CSV format:

140601_0082

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_last_invoice_id&return_type=xml

Example result in XML:

<xml>
  <last_invoice_id>
    <id><![CDATA[140601_0082]]></id>
  </last_invoice_id>
</xml>

get_invoice

Result: Call to get the information of an invoice. It returns the information of the invoice, empty otherwise.

Parameters:

Invoice identifier: It is the value of the Bill ID field (required).

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_invoice&params=140601_0071

Example result in CSV format:

2,admin,,1,140601_0071,ads,,,,,222.00,0.00,0.00,0.00,0.00,0.00,EUR,,0,0,,2014-01-24,0000-00-00,pending,,,Submitted,en_GB

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_invoice&params=140601_0071&return_type=xml

Example result in XML:

<xml>
 <invoice>
  <id><![CDATA[2]]></id>
  <id_user><![CDATA[admin]]></id_user>
  <id_task><![CDATA[]]></id_task>
  <id_company><![CDATA[1]]></id_company>
  <bill_id><![CDATA[140601_0071]]></bill_id>
  <concept1><![CDATA[ads]]></concept1>
  <concept2><![CDATA[]]></concept2>
  <concept3><![CDATA[]]></concept3>
  <concept4><![CDATA[]]></concept4>
  <concept5><![CDATA[]]></concept5>
  <amount1><![CDATA[222.00]]></amount1>
  <amount2><![CDATA[0.00]]></amount2>
  <amount3><![CDATA[0.00]]></amount3>
  <amount4><![CDATA[0.00]]></amount4>
  <amount5><![CDATA[0.00]]></amount5>
  <tax><![CDATA[0.00]]></tax>
  <currency><![CDATA[EUR]]></currency>
  <description><![CDATA[]]></description>
  <id_attachment><![CDATA[0]]></id_attachment>
 <locked><![CDATA[0]]></locked>
  <locked_id_user><![CDATA[]]></locked_id_user>
  <invoice_create_date><![CDATA[2014-01-24]]></invoice_create_date>
  <invoice_payment_date><![CDATA[0000-00-00]]></invoice_payment_date>
  <status><![CDATA[pending]]></status>
  <reference><![CDATA[]]></reference>
  <internal_note><![CDATA[]]></internal_note>
  <invoice_type><![CDATA[Submitted]]></invoice_type>
  <id_language><![CDATA[en_GB]]></id_language>
 </invoice>
</xml>

create_invoice

Result: Call to create an invoice. It returns two values, the status code (one 1 if the operation was performed, zero 0 if a fault was detected) and a message with the result of the operation.

Parameters:

User identifier (it must exist or empty).
Task identifier (not required). Zero 0 by default.
Company identifier (required).
Invoice identifier (required).
Concept (mandatory). To enter commas in this parameter, it must be replaced by (:::), to enter a space you must use %20. For example, to enter Doe, John insert in the URL: Doe:::%20John.
Amount (required).
Taxes: Tax percentage (not mandatory). By default it is zero 0.
Currency: Text string (required).
Description (not mandatory). Empty by default. To enter commas in this parameter, it must be replaced by (:::), to enter a space you must use %20. For example, to enter Doe, John insert in the URL: Doe:::%20John.
Flag blocked: Boolean (not mandatory). By default it is zero 0 (not blocked).
Blocking user identifier (mandatory if blocked flag is active). Empty by default.
Creation date (not mandatory). By default the current day.
Payment date (not mandatory). By default the current day.
Status (not mandatory). Pending by default.
Reference (not mandatory). Empty by default.
Internal note (not mandatory). Empty by default.
Invoice type (required: Submitted or Received).
Language identifier (not mandatory).
- de → Deutch (German).
- en_GB → English.
- es → Español (Spanish).
- fr → French (French).
- pl → Polski (Polish).
- ru → Русский (Russian).
- zh_CN → 简化字 (Chinese).

Call example with no faults with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&pass=1234&op=create_invoice&params=admin,,1,140601_0082,paso,3.00,,EUR,,,,,,paid,,,Submitted,

Example result with no faults in CSV format:

1,"invoice created"

Example result with no faults in CSV format:

0,"invalid billing id"

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_invoice&params=admin,,1,140601_0082,paso,3.00,,EUR,,,,,,paid,,,Submitted,&return_type=xml

Example output without errors in XML:

<xml>
  <invoice>
    <status><![CDATA[0]]></status>
    <error><![CDATA[invalid billing id]]></error>
   </invoice>
</xml>

create_company

Result: It returns the identifier of the company created.

Parameters:

Name (required). To enter commas in this parameter, it must be replaced by (:::), to enter a space you must use %20. For example, to enter Doe, John insert in the URL: Doe:::%20John.
Address (not mandatory). Empty by default. To enter commas in this parameter, it must be replaced by (:::), to enter a space you must use %20. For example, to enter Doe, John insert in the URL: Doe:::%20John.
Tax identification (not mandatory). Empty by default.
Company role identifier (not mandatory). Zero 0 (none) by default.
Epilogue (not mandatory). Empty by default.
Manager: Name of the user who is in charge of the company (it must exist or set it empty).
Company role identifier (not mandatory). By default it is zero 0.

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_company&params=Artica,AlbertoAguilera,12312312,1,Pais,admin,0

Example result in CSV format:

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_company&params=Artica,AlbertoAguilera,12312312,1,
Country,admin,0&return_type=xml

Example result in XML:

<xml>
  <company>
    <id><![CDATA[6]]></id>
  </company>
</xml>

add_address_to_newsletter

Result: It returns the identifier of the email address created. If it fails, it returns a zero value 0.

Parameters:

Newsletter Id (mandatory and it must exist).
Name (required).
Email (required).

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=integria&op=add_address_to_newsletter&params=2,juan,[email protected]

Result

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=integria&op=add_address_to_newsletter&params=2,juan,[email protected]&return_type=xml

Example result in XML:

<xml>
10
</xml>

get_incident_tracking

Result: It returns a list with the follow-up or tracking of a ticket.

Parameters:

Ticket identifier (required).

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incident_tracking&params=2

Example result in CSV format:

9,2,0,"2010-02-17 01:56:33",demo,0,Created
10,2,2,"2010-02-17 02:06:58",demo,0,"Workunit added"

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incident_tracking&params=2&return_type=xml

Example result in XML:

<xml>
   <tracking>
               <id_it>9</id_it>
               <id_incident>2</id_incident>
               <state>0</state>
               <timestamp>2010-02-17 01:56:33</timestamp>
               <id_user>demo</id_user>
               <id_aditional>0</id_aditional>
               <description>Created</description>
   </tracking>
   <tracking>
               <id_it>10</id_it>
               <id_incident>2</id_incident>
               <state>2</state>
               <timestamp>2010-02-17 02:06:58</timestamp>
               <id_user>demo</id_user>
               <id_aditional>0</id_aditional>
               <description>Workunit added</description>
   </tracking>
</xml>

get_incidents_resolutions

Result: It returns a list with the identifiers and names of the resolutions of the Integria IMS tickets.

Parameters: None.

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents_resolutions

Example result in CSV format:

1,Fixed
2,Invalid
3,"Wont fix"

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents_resolutions&return_type=xml

Example result in XML:

<xml>
       <resolution>
               <id>1</id>
               <name>Fixed</name>
       </resolution>
       <resolution>
               <id>2</id>
               <name>Invalid</name>
       </resolution>
       <resolution>
               <id>3</id>
               <name>Wont fix</name>
       </resolution>
</xml>

get_incidents_status

Result: It returns a list with the identifiers and names of the statuses of Integria IMS tickets.

Parameters: None.

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents_status

Example result in CSV format:

1,New
2,Unconfirmed
3,Assigned

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents_status&return_type=xml

Example result in XML:

<xml>
       <status>
               <id>1</id>
               <name>New</name>
       </status>
       <status>
               <id>2</id>
               <name>Unconfirmed</name>
       </status>
       <status>
               <id>3</id>
               <name>Assigned</name>
       </status>
</xml>

get_incident_priorities

Result: It returns a list with the identifiers and names of the priorities of Integria IMS tickets.

Parameters: None.

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incident_priorities

Example result in CSV format:

10,Maintenance
0,Informative
1,Low
2,Medium
3,Serious
4,Very serious

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incident_priorities&return_type=xml

Example result in XML:

<xml>
       <priority>
               <id>10</id>
               <name>Maintenance</name>
       </priority>
       <priority>
               <id>0</id>
               <name>Informative</name>
       </priority>
       <priority>
               <id>1</id>
               <name>Low</name>
       </priority>
       <priority>
               <id>2</id>
               <name>Medium</name>
       </priority>
       <priority>
               <id>3</id>
               <name>Serious</name>
       </priority>
       <priority>
               <id>4</id>
               <name>Very serious</name>
       </priority>
</xml>

get_incident_fields

Result: It returns the custom fields for a given ticket type. If a ticket identifier is also specified, its values will be returned.

Parameters:

Ticket type identifier (required).
Ticket identifier (optional).

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incident_fields&params=4,32

Example result in CSV format:

cHJvYmFuZG8mI3gyMDtsaXN0YQ==,8,8,4,4,"testing list","testing list",text,text,,,1,1,,,0,0,,,1,1,"content test",0

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incident_fields&params=4,32&return_type=xml

Example result in XML:

<xml>
   <field>
       <label_enco>cHJvYmFuZG8mI3gyMDtsaXN0YQ==</label_enco>
       <id>8</id>
       <id_incident_type>4</id_incident_type>
       <label>testing list</label>
       <type>text</type>
       <combo_value></combo_value>
       <show_in_list>1</show_in_list>
       <parent>0</parent>
       <linked_value></linked_value>
       <order>1</order>
       <data>content test</data>
       <blocked>0</blocked>
  </field>
</xml>

get_groups

Result: It returns a list with the identifiers and names of Integria IMS groups.

Parameters: None.

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_groups

Example result in CSV format:

2,"Customer #A"
3,"Customer #B"
4,Engineering

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_groups&return_type=xml

Example result in XML:

<xml>
       <group>
               <id>1</id>
               <name>"Customer #A"</name>
       </group>
       <group>
               <id>2</id>
               <name>"Customer #B"</name>
       </group>
       <group>
               <id>3</id>
               <name>Engineering</name>
       </group>
</xml>

get_users

Result: It returns a list with the users on which the calling user has visibility.

Parameters: None.

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_users

Example result in CSV format:

user1
user2
user3

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents&params=day,-10,1&return_type=xml

Example result in XML:

<xml>
  <id_user>user1</id_user>
  <id_user>user2</id_user>
  <id_user>user3</id_user>
</xml>

get_stats

Result: It returns a value corresponding to the query made.

Parameters:

metric: Statistical values metric, they can be the following:
- total_incidents: Total number of tickets (limited by the maximum number of Integria IMS tickets).
- opened: Total number of open tickets.
- closed: Total number of closed tickets.
- avg_life: Ticket average life in seconds.
- sla_compliance: SLA compliance percentage.
- avg_scoring: Ticket average score from 0 to 10.
- avg_worktime: Average work time on the ticket in seconds.
- string: String to filter ticket search.
- status: String with values separated by commas. It can take values between 1 and 7 (by default 1,2,3,4,5,6,7).
- id_user: Filtered by user (by default “”).
- id_group: Filtered by group (by default one 1).
- id_company: Filtered by company (by default zero 0).
- id_inventory: Filtered by inventory (by default zero 0).
- priority: String with values separated by commas, it can take values 0 (Informative), 1 (Low), 2 (Medium), 3 (Serious), 4 (Very serious) and 10 (Maintenance). By default, all.

Call example to obtain SLA percentage with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_stats&params=sla_compliance

Obtain the total of open tickets with NEW status (code 1), in any group:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_stats&params=opened,,1

Get the total of open tickets (any status, in any group).

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_stats&params=opened

Example result in CSV format:

1,"Sample inventory object"
2,"Another inventory"
3,"Thirdventory"

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_stats&params=sla_compliance&return_type=xml

Example result in XML:

get_incidents_summary

Result: It returns the summary of the ticket status.

Parameters: Field, if the field is added, it will only show that value. The allowed fields are:

new .
unconfirmed .
assigned .
reopened .
verified .
pending_third_person .
closed .
not_closed .
total .

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents_summary&return_type=csv

Example result in CSV format:

NEW,1
UNCONFIRMED,0
ASSIGNED,70
REOPENED,3
VERIFIED,12
PENDING_THIRD_PERSON,308
CLOSED,3382
NOT_CLOSED,393
TOTAL,3776

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents_summary&return_type=xml

Example result in XML:

<xml>
  <new>1</new>
  <unconfirmed>0</unconfirmed>
  <assigned>70</assigned>
  <reopened>3</reopened>
  <verified>12</verified>
  <pending_third_person>308</pending_third_person>
  <closed>3382</closed>
  <not_closed>393</not_closed>
  <total>3776</total>
</xml>

Example of a call with a specific field and result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents_summary&return_type=csv&params=not_closed

Example result in CSV format:

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents_summary&return_type=xml&params=not_closed

Example result in XML:

<xml>
    <data>393</data>
</xml>

get_inventories

Result: It returns a list with the identifiers and names of Integria IMS inventories.

Parameters: None.

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_inventories

Example result in CSV format:

1,"Sample inventory object"
2,"Another inventory"
3,"Thirdventory"

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_inventories&return_type=xml

Example result in XML:

<xml>
   <inventory>
       <id>1</id>
       <name>Sample inventory object</name>
   </inventory>
   <inventory>
       <id>2</id>
       <name>Another inventory</name>
   </inventory>
   <inventory>
       <id>3</id>
       <name>Thirdventory</name>
   </inventory>
</xml>

get_user_exists_in_group

Result: It returns one 1 if the given user exists in any of the given groups. Zero 0 otherwise.

Serialized parameters:

user_id
group_id: They can be several groups separated by a token.

Example call:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=user_exists_in_group&params=test,4,5

get_incident_inventories

Result: It returns a list of inventory items associated with a ticket.

Serialized parameters:

Ticket filter: Ticket identifier (required).

Call example with result in CSV format:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incident_inventories&params=10

Example result in CSV format:

2,1,admin,Sanchez,0,Sancho's computer,0,0,0,0,0000-00-00,new,2013-08-19,0000-00-005,3,admin,InventarioCSV,1,descripcion,0,0,0,1,2017-08-02,new,2016-10-09,2017-10-09

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incident_inventories&params=10&return_type=xml

Example result in XML:

<xml version='1.0' encoding='UTF-8'>
  <inventory>
     <id><![CDATA[2]]></id>
     <id_object_type><![CDATA[1]]></id_object_type>
     <owner><![CDATA[admin]]></owner>
     <name><![CDATA[Sanchez]]></name>
     <public><![CDATA[0]]></public>
     <description><![CDATA[Sancho's computer]]></description>
     <id_contract><![CDATA[0]]></id_contract>
     <id_manufacturer><![CDATA[0]]></id_manufacturer>
     <id_parent><![CDATA[0]]></id_parent>
     <show_list><![CDATA[0]]></show_list>
     <last_update><![CDATA[0000-00-00]]></last_update>
     <status><![CDATA[new]]></status>
     <receipt_date><![CDATA[2013-08-19]]></receipt_date>
     <issue_date><![CDATA[0000-00-00]]></issue_date>
  </inventory>
</xml>

get_last_cron_execution

Result: It returns the time gone by in minutes since the last execution of the Crontask.

Parameters: None.

Example call:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_last_cron_execution

Result:

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_last_cron_execution&return_type=xml

Example result in XML:

<xml>
   <cronjob>
               <last_exec>3</last_exec>
   </cronjob>
</xml>

get_num_queued_emails

Result: It returns the number of emails that are in the queue pending to be sent.

Parameters: None.

Example call:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_num_queued_emails

Result:

Call example result in XML:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_num_queued_emails&return_type=xml

Example result in XML:

<xml>
   <pending_email>
               <num>20</num>
   </pending_email>
</xml>

API extension

To develop new calls for the API you have to take into account that:

The call must be registered as a function in the /include/functions_api.php file, in addition to being included in the valid functions in the /include/api.php file.
The function must return a single value or an array of pairs, for example name-value.
The formatting of the result of the call to XML or CSV is done in the api.php file and should be done automatically.

Examples of functions for the API

Example of a function that returns a single value

Definition in functions_api.php file:

function host_risk ($host_name) {

   $host_id = get_hosts_id($host_name);

   //If there is not a host with this name return false
   if (!$host_id) {
       return false;
   }

   $risk = return_last_risk_agent($host_id);

   return $risk;
}

Call in api.php file:

switch ($op) {

       ...

   case "host_risk":
       if (isset($params['0'])) {
           $result = host_risk ($params['0']);
       } else {
           $result = false;
       }
       break;

      ...
}

Example of a function that returns a list of values

Definition in functions_api.php file:

function all_host_risk() {

   //Get all host
   $hosts = get_hosts();

   //Check if there is host or not
   if (empty($hosts)) {
       return false;
   }

   $result = array();
   foreach ($hosts as $host) {
       $host_name = get_host_name($host['id']);
       $risk = return_last_risk_agent($host['id']);
       $aux = array();
       $aux['name'] = $host_name;
       $aux['data'] = $risk;

       array_push($result, $aux);
   }

   return $result;
}

Call in api.php file:

switch ($op) {

       ...

   case "all_host_risk":
       $result = all_host_risk ();
       break;

       ...

 }

Go back to Integria IMS Documentation index

Table of Contents

Integria IMS API

Security

Authentication by valid IP address

Password authentication

User and user password authentication

API functions

Return of information about Integria IMS

get_incidents

get_incident_details

create_incident

update_incident

add_inventory_to_ticket

delete_incident

get_incident_workunits

create_workunit

get_incident_files

download_file

attach_file

delete_file

create_user

validate_user

delete_user

user_exists

create_lead

get_last_invoice_id

get_invoice

create_invoice

create_company

add_address_to_newsletter

get_incident_tracking

get_incidents_resolutions

get_incidents_status

get_incident_priorities

get_incident_fields

get_groups

get_users

get_stats

get_incidents_summary

get_inventories

get_user_exists_in_group

get_incident_inventories

get_last_cron_execution

get_num_queued_emails

API extension

Examples of functions for the API

Example of a function that returns a single value

Example of a function that returns a list of values