Pandora ITSM API

By default, when installing Pandora ITSM, the list of authorized IP addresses is restricted only to local calls (from localhost, 127.0.0.1). You must add the IP address or addresses (separated by commas, spaces, or on different lines) that will work with the PITSM 2.0 API (recommended option).

When pressing the Create Token button, it will be displayed only once, so it must be copied and stored immediately. As many tokens as necessary can be created; each user is responsible for each of them.

Once you have the token generated by the Web Console, use the following address in the web browser's address bar:

https://<IP address or FQDN>/pandoraitsm/api/

The first time it is accessed, the 2.0 API documentation will be updated and organized in a few seconds; click on the Authorize button and in the pop-up window you must enter the token generated previously.

Upon setting a token, the padlock icons will change, and you can start making requests to the API. These requests are classified into:

• POST: To create new elements.
• GET: To display the registered elements.
• PUT: To edit the registered elements.
• DELETE: To delete the registered elements.

In turn, logical groupings of actions and available schemas are offered:

For this, it is recommended to use Curl, which is present in most current operating systems:

curl -X '<action>' \
  'http://<IP_address_or_FQDN>/pandoraitsm/api/v2/<command>/<parameter>' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_private_token>'
  -d '<JSON parameters>'

Where:

• <action> The action to perform:

• POST: To create new elements.
• GET: To display the registered elements.
• PUT: To edit the registered elements.
• DELETE: To delete the registered elements.

• <command> The API command itself, such as ping, etc.
• <parameter> A unique identifier or pagination parameters, depending on each case.
• <your token> The token generated by each user.
• <JSON parameters> The rest of the necessary parameters.

https://<IP address or FQDN>/pandoraitsm/api/v2/pandoraitsm.json

By accessing the previous link, each and every one of the documentation features will be obtained in an automated way, which allows generating documentation with any software compatible with JSON format.

Additionally, in the web interface, each command has a link to its particular schema:

The easiest way to check connectivity and authentication with the PITSM API is done with its ping command:

curl -m 3 -X 'GET' \
  'http://192.168.9.208/pandoraitsm/api/v2/ping' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_private_token>' && echo 

In the web interface, it is accessed through the Authentication (API Endpoints of authentication) section, and the Try out button is pressed (if the padlock icon is open, click it and enter the generated user token), and then the Execute button is pressed. The connection will be successful if the code { “valid”: true } is displayed in the Response body.

The external Pandora ITSM 1.0 API is used by making remote calls via HTTP or HTTPS to the file:

https://<Console_web_URL>/include/api.php

With this method, the integration of third-party applications with Pandora ITSM is possible. The use of the 1.0 API is done through a call with defined parameters that returns a value or a list of values. The 1.0 API call prototype is:

https://<Console_web_URL>/pandoraitsm/include/api.php?<parameters>

Where <Console_web_URL> is the IP address or public URL where Pandora ITSM is installed. The 1.0 API method only accepts the following parameters (<parameters>), any other parameter will be ignored:

• user (mandatory): Name of the Pandora ITSM user accessing the data, used to verify ACL rules.
• user_pass (mandatory): User's password.
• op (mandatory): Operation to perform. Operations are detailed below.
• pass (mandatory if enabled): Specific API password, configured in the Pandora ITSM Console.
• params: List of parameters to be passed to the function separated by a token.
• token: Character that separates the different parameters (by default the comma , is used).
• return_type: Format of the call result, it can be XML or CSV (CSV by default).
• info: Special parameter with which the version can be obtained before authenticating.

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

It is important to note that this authentication method is always active, so if you wish to bypass it, it will be necessary to place the asterisk character * to indicate that any IP address is authorized.

Within the Pandora ITSM configuration menu, it is possible to set a specific password for the API. This password must be sent in the API call unencrypted, therefore HTTPS should always 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 include the pass token in the API call.

It is necessary in all calls (except information ones) to specify the user (user) and the user's password (user_pass).

Authentication based on a bearer token allows each of the registered users in Pandora ITSM to generate their own identifier in one-to-one correspondence. Said bearer token must be inserted into the HTTP headers, that is, it is not part of the full API URL. The sending mechanism corresponds to the application making the connection with the PITSM API.

For the following examples, the command line program cURL is used, version 7.68.

• Verify the curl version with curl -V.
• If more help is needed to use curl, invoke curl -h.
• If the connection needs to be debugged, use the -v parameter (not to be confused with -V used to show the version).
• The -k and -H parameters serve to accept connections with self-signed certificates for HTTPS and send the headers information, respectively.
• Check the bearer token corresponding to the user who will make the API query.
• Now you can make an API query, in the following example get_incidents is used (replace it with your Web Console URL and your bearer token consulted previously):

BEARER="Authorization: Bearer ddd2bc3e9e1f11f193bb027bd0ae4b72"
URL="http://192.168.9.208/pandoraitsm/include/api.php"
API_QUERY="?return_type=xml&user=admin&op=get_incidents"
curl -k -H "$BEARER" $URL$API_QUERY && echo ""

This is a special function that can be used without authenticating and regardless of the IP address queried with, since the returned information can also be obtained publicly from the login screen (if the Hide version token is disabled).

Syntax:

…/api.php?info=version

Result similar to:

Pandora ITSM Enterprise Edition 5.0.109 Build 260603 MR109

Result: Returns a list with the tickets accessible to the user making the call.

Serialized parameters:

• String filter: Shows only the tickets that contain that string in the title or description (not mandatory). Empty for all tickets. The search is case-insensitive.
• Status filter: Status identifier (not mandatory). It can take the following values:
  • 0 → All (by default).
  • 1 → New.
  • 2 → Unconfirmed.
  • 3 → Assigned.
  • 4 → Reopened.
  • 5 → Pending to be closed.
  • 6 → Pending third person.
  • 7 → Closed.
  • -10 → For all except closed ones.
• Group filter: Group identifier (mandatory). One (1) for all groups.
• Priority filter: Priority identifier (optional). It can have any of the following values:
  • 10 → Maintenance.
  • 0 → Informative.
  • 1 → Low.
  • 2 → Medium.
  • 3 → Serious.
  • 4 → Very serious.
  • -1 → Any.
• Inventory filter: Related inventory identifier (optional). Zero (0) for all or none.
• Owner filter: Identifier of the user assigned to the incident (optional).
• Creator filter: Identifier of the user who created the incident (optional).
• Incident filter: Incident identifier (optional).

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents&params=day,-10,1,-1,0,admin,user1

Example result with 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,mail(at)example.com,,0,"2014-01-20 14:45:01",,,,0,0,0,0,0,0,0

Example call with result in XML:

(syntax)

…/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[copyto(at)example.com]]></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>

Result: Returns the details of a ticket.

Parameters:

• ticket identifier (mandatory).

Example call with result in CSV format:

(syntax)

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

Example call with result in XML:

(syntax)

…/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_issue>1</id_issue>
        <start>2010-02-17 01:35:35</start>
        <close>0000-00-00 00:00:00</close>
        <title>Myfddfe</title>
        <description></description>
        <user_id>demo</user_id>
        <source>1</source>
        <state>1</state>
        <priority>3</priority>
        <group_id>3</group_id>
        <update>2010-02-17 01:50:05</update>
        <id_creator>admin</id_creator>
        <notify_email>1</notify_email>
        <id_task>0</id_task>
        <resolution>0</resolution>
        <epilg></epilg>
        <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>

Result: A ticket is created.

User: It is the creator of the ticket.

Parameters:

• Title (mandatory). Empty titles are not allowed. To introduce commas in this parameter, they must be replaced by (:::), to introduce a space, you must use %20. For example, to introduce Doe, John you will have to insert into the URL: Doe:::%20John.
• Group identifier (mandatory).
• Priority (not mandatory). It can have these values:
  • 10 → 0 Maintenance (maintenance).
  • 0 → 1 Informative (informative, by default).
  • 1 → 2 Low (low priority).
  • 2 → 3 Medium (medium priority).
  • 3 → 4 Serious (serious priority).
  • 4 → 5 Very serious (very serious priority).
• Description (not mandatory). Empty by default. To introduce commas in this parameter, they must be replaced by (:::), to introduce a space, you must use %20. For example, to introduce Doe, John you will have to insert into the URL: Doe:::%20John.
• Inventory identifier (not mandatory). Incidents can be created with several inventory objects and they will have to be separated from each other by :.
• Incident type identifier (not mandatory). Zero 0 (none) by default.
• Email in copy (not mandatory): Default value is empty.
• Owner (not mandatory). By default admin.
• Parent ticket identifier (not mandatory). By default, zero 0 (without parent).
• Status (mandatory). It can take the following values:
  • 1 → New (by default).
  • 2 → Unconfirmed.
  • 3 → Assigned.
  • 4 → Reopened.
  • 5 → Pending to be closed.
  • 6 → Pending third person.
  • 7 → Closed.
• Info_extra (not mandatory).
• Resolution:
  • 0 → None (none, by default).
  • 1 → Fixed (fixed).
  • 2 → Invalid (invalid).
  • 3 → Won't fix (won't fix).
  • 4 → Duplicate (duplicate).
  • 5 → Works for me (“works for me”).
  • 6 → Incomplete (incomplete).
  • 7 → Expired (expired).
  • 8 → Moved (moved).
  • 9 → In process (in process).
• Info_extra2 (not mandatory).
• Info_extra3 (not mandatory).
• Info_extra4 (not mandatory).
• IncidentTypeField1.
• IncidentTypeField2
• IncidentTypeField3
• …
• IncidentTypeFieldN.

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_incident&params=Title,2,1,Description%20de%20la%incidence,1:2:3,1,copyto(at)example.com,admin,0,1

Example result with CSV format:

0

Example call with result in XML:

(syntax)

…/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,copyto(at)example.com,admin,0&return_type=xml

Example result in XML:

<xml>
0
</xml>

Result: Updates the data of a ticket.

Parameters:

• ticket identifier (mandatory).
• Title (mandatory). Empty titles are not allowed.
• Description (not mandatory). Empty by default.
• Epilogue (not mandatory). Empty by default.
• Group identifier (mandatory).
• Priority (not mandatory). It can have these values:
  • 10 → 0 Maintenance (maintenance).
  • 0 → 1 Informative (informative, by default).
  • 1 → 2 Low (low priority).
  • 2 → 3 Medium (medium priority).
  • 3 → 4 Serious (serious priority).
  • 4 → 5 Very serious (very serious priority).
• Resolution:
  • 0 → None (none, by default).
  • 1 → Fixed (fixed).
  • 2 → Invalid (invalid).
  • 3 → Won't fix (won't fix).
  • 4 → Duplicate (duplicate).
  • 5 → Works for me (“works for me”).
  • 6 → Incomplete (incomplete).
  • 7 → Expired (expired).
  • 8 → Moved (moved).
  • 9 → In process (in process).
• Status (mandatory). It can take the following values:
  • 1 → New (by default).
  • 2 → Unconfirmed.
  • 3 → Assigned.
  • 4 → Reopened.
  • 5 → Pending to be closed.
  • 6 → Pending third person.
  • 7 → Closed.
• Owner (not mandatory). By default admin.
• Parent ticket identifier (not mandatory). By default, zero 0 (without parent).
• Incident 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).
• IncidentTypeField1.
• IncidentTypeField2
• IncidentTypeField3
• …
• IncidentTypeFieldN.

Example call with result in CSV format:

(syntax)

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

Example call with result in XML:

(syntax)

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

Example result in XML:

<xml>
0
</xml>

Result: Allows associating an inventory object with a ticket.

Parameters:

• ticket identifier (mandatory).
• Inventory object identifier (mandatory).

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=add_inventory_to_ticket&params=1,2

Example result in CSV:

1

Example call with result in XML:

(syntax)

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

Result: A ticket is deleted.

Parameters:

• ticket identifier (mandatory).

Example call with result in CSV format:

(syntax)

…/api.php?user=user&pass=api_pass&op=delete_incident&params=3

Example result in CSV format:

0

Example call with result in XML:

(syntax)

…/api.php?user=user&pass=api_pass&op=delete_incident&params=3&return_type=xml

Example result in XML:

<xml>
0
</xml>

Result: Returns a list with the Workunits associated with a ticket.

Parameters:

• ticket identifier (mandatory).

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=user_pass&pass=api_pass&op=get_incident_workunits&params=3

Example result with 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

Example call with result in XML:

(syntax)

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

Result: Creates a Workunit in a ticket.

Parameters:

• ticket identifier (mandatory).
• Description (not mandatory). By default, empty.
• Duration in hours (not mandatory). By default 0.00 hours.
• If it had cost (not mandatory). By default, no.
• If it is public or not (not mandatory). By default, no.
• Associated profile identifier (not mandatory). By default zero 0, without associated profile.

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_workunit&params=1,Descripcion,0.5,0,1,1

Example result with CSV format:

0

Example call with result in XML:

(syntax)

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

Result: Returns a list with the files associated with a ticket.

Parameters:

• ticket identifier (mandatory).

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass=&pass=api_pass&op=get_incident_files&params=1

Example result with CSV format:

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

Example call with result in XML:

(syntax)

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

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

Parameters:

• File identifier (mandatory).

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=download_file&params=32

Example result with CSV format:

[base64 file content]

Example call with result in XML:

(syntax)

…/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>
[base64 file content]
</xml>

Result: Adds a file to the list of files 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), by default empty.
• Base64 file content (not mandatory) by default is created with empty content.

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=attach_file&params=1,example.txt,234,File
%20of%20example,aW50ZWdyaWEgcm9ja3M=

Example result with CSV format:

0

Example call with result in XML:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=attach_file&params=1,example.txt,234,File
%20of%20example,aW50ZWdyaWEgcm9ja3M=&return_type=xml

Example result in XML:

<xml>
0
</xml>

Result: Deletes a file from the list of files of a ticket.

Parameters:

• File identifier (mandatory).

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=delete_file&params=32

Example result with CSV format:

0

Example call with result in XML:

(syntax)

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

Result: Call used to create a user and assign them to a role or group. To assign more profiles, a different call must be used. Returns one 1 if created successfully, zero 0 otherwise.

Parameters:

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

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_user&params=jorge,3,4,jorge(at)lux.com,
userpass,description,Jorge%20Surname,1

Example result with CSV format:

1

Example call with result in XML:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_user&params=jorge,3,4,jorge(at)lux.com,userpass,description,
Jorge%20LastName,1&return_type=xml

Example result in XML:

<xml>
1
</xml>

Result: Returns one 1 if the authentication is correct, zero 0 otherwise.

Parameters:

• User: Name of the registered user to be validated (mandatory).
• Pass: User's password (mandatory).

Example call with result in CSV format:

(syntax)

…/api.php?&user=user&user_pass=userpass&pass=api_pass&op=validate_user&params=jorge,jorge_pass

Example result with CSV format:

1

Example call with result in XML:

(syntax)

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

Result: Call used to delete a user. Returns one 1 if deleted successfully, zero 0 otherwise.

Parameters

• User: (mandatory).

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=delete_user&params=pepe

Example result with CSV format:

1

Example call with result in XML:

(syntax)

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

Result: Call used to verify if a user exists. Returns one 1 if it exists, zero 0 if it does not exist.

Parameters:

• User: (mandatory).

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=user_exists&params=pepe

Example result with CSV format:

1

Example call with result in XML:

(syntax)

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

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

Parameters:

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

Example call with result in CSV format:

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_lead&params=Dario%Rodriguez%Perez,Artica+ST,drp(at)example.com,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 with CSV format:

1

Example call with result in XML:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_lead&params=Dario%Rodriguez%Perez,Artica+ST,drp(at)example.com,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>

Result: Call used to obtain the last invoice identifier. Returns the last invoice identifier, empty if unsuccessful.

Parameters: none.

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_last_invoice_id

Example result with CSV format:

140601_0082

Example call with result in XML:

(syntax)

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

Result: Call to obtain the information of an invoice. Returns the invoice information, empty otherwise.

Parameters:

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

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_invoice&params=140601_0071

Example result with 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

Example call with result in XML:

(syntax)

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

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

Parameters:

• User identifier (must exist or empty).
• Task identifier (not mandatory). Zero 0 by default.
• Company identifier (mandatory).
• Invoice identifier (mandatory).
• Concept (mandatory). To introduce commas in this parameter, they must be replaced by (:::), to introduce a space, you must use %20. For example, to introduce Doe, John you will have to insert into the URL: Doe:::%20John.
• Amount (mandatory).
• Taxes: Tax percentage (not mandatory). By default zero 0.
• Currency: Text string (mandatory).
• Description: (not mandatory). Empty by default. To introduce commas in this parameter, they must be replaced by (:::), to introduce a space, you must use %20. For example, to introduce Doe, John you will have to insert into the URL: Doe:::%20John.
• Locked flag: Boolean (not mandatory). By default zero 0 (not locked).
• Locker user identifier (mandatory if locked flag is active). Empty by default.
• Creation date (not mandatory). Current day by default.
• Payment date: (not mandatory). Current day by default.
• Status (not mandatory). Pending by default.
• Reference (not mandatory). Empty by default.
• Internal note (not mandatory). Empty by default.
• Invoice type (mandatory: Submitted or Received).
• Language identifier (not mandatory).
  • de → Deutsch (German).
  • en_GB → English (English).
  • es → Spanish.
  • fr → Français (French).
  • pl → Polski (Polish).
  • ru → Русский (Russian).
  • zh_CN → 简化字 (Chinese).

Example call without errors with result in CSV format:

(syntax)

…/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 without errors with CSV format:

1,"invoice created"

Example result with errors with CSV format:

0,"invalid billing id"

Example call with result in XML:

(syntax)

…/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 result without errors in XML:

<xml>
  <invoice>
    <status><![CDATA[1]]></status>
    <error><![CDATA[invoice created]]></error>
   </invoice>
</xml>

Example result with errors in XML:

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

Result: Returns the identifier of the created company.

Parameters:

• Name (mandatory). To introduce commas in this parameter, they must be replaced by (:::), to introduce a space, you must use %20. For example, to introduce Doe, John you will have to insert into the URL: Doe:::%20John.
• Address (not mandatory). Empty by default. To introduce commas in this parameter, they must be replaced by (:::), to introduce a space, you must use %20. For example, to introduce Doe, John you will have to insert into the URL: Doe:::%20John .
• Tax identification (not mandatory). Empty by default.
• Company role identifier (not mandatory). By default zero 0 (no role).
• Country (not mandatory). By default, empty.
• Manager: Name of the user in charge of the company (must exist or leave it empty).
• Parent company identifier (not mandatory). By default zero 0.

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=create_company&params=Artica,AlbertoAguilera,12312312,1,Country,admin,0

Example result with CSV format:

6

Example call with result in XML:

(syntax)

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

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

Parameters:

• Id newsletter (mandatory and must exist).
• Name (mandatory).
• Email (mandatory).

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=yourpassword&op=add_address_to_newsletter&params=2,juan,juan(at)mail.com

Result

10

Example call with result in XML:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=yourpassword&op=add_address_to_newsletter&params=2,juan,juan(at)mail.com&return_type=xml

Example result in XML:

<xml>
10
</xml>

Result: Returns a list with the tracking or tracking of a ticket.

Parameters:

• ticket identifier (mandatory).

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incident_tracking&params=2

Example result with 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"

Example call with result in XML:

(syntax)

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

Result: Returns a list with the identifiers and names of the resolutions of the Pandora ITSM tickets.

Parameters: None.

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents_resolutions

Example result with CSV format:

1,Fixed
2,Invalid
3,"Won't fix"
4,Duplicate
5,"Works for me"
6,Incomplete
7,Expired
8,Moved
9,"In process"

Example call with result in XML:

(syntax)

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

Result: Returns a list with the identifiers and names of the statuses of the Pandora ITSM tickets.

Parameters: None.

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents_status

Example result with CSV format:

1,New
2,Unconfirmed
3,Assigned

Example call with result in XML:

(syntax)

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

Result: Returns a list with the identifiers and names of the priorities of the Pandora ITSM tickets.

Parameters: None.

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incident_priorities

Example result with CSV format:

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

Example call with result in XML:

(syntax)

…/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>Informational</name>
        </priority>
        <priority>
                <id>1</id>
                <name>Low</name>
        </priority>
        <priority>
                <id>2</id>
                <name>Middle</name>
        </priority>
        <priority>
                <id>3</id>
                <name>Severe</name>
        </priority>
        <priority>
                <id>4</id>
                <name>Very serious</name>
        </priority>
</xml>

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

Parameters:

• Type identifier of the ticket (mandatory).
• ticket identifier (optional).

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incident_fields&params=4.32

Example result with CSV format:

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

Example call with result in XML:

(syntax)

…/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>test content</data>
        <blocked>0</blocked>
   </field>
</xml>

Result: Returns a list with the identifiers and names of the Pandora ITSM groups.

Parameters: None.

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_groups

Example result with CSV format:

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

Example call with result in XML:

(syntax)

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

Result: Returns a list with the users visible to the user making the call.

Parameters: None.

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_users

Example result with CSV format:

user1
user2
user3

Example call with result in XML:

(syntax)

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

Result: Returns a value corresponding to the query performed.

Parameters:

• metric: Metric of statistical values, they can be the following:
  • total_incidents: Total number of tickets (limited by the maximum number of tickets in Pandora ITSM).
  • opened: Total number of open tickets.
  • closed: Total number of closed tickets.
  • avg_life: Average life of the tickets in seconds.
  • sla_compliance: Percentage of SLA compliance.
  • avg_scoring: Average scoring of the tickets from 0 to 10.
  • avg_worktime: Average worktime on the ticket in seconds.
  • string: String to filter the tickets. search.
  • status: String with comma-separated values, 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 comma-separated values, it can take the values 0 (Informative), 1 (Low), 2 (Medium), 3 (Serious), 4 (Very serious) and 10 (Maintenance). By default, all.

Example call to obtain SLA percentage with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_stats&params=sla_compliance

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

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_stats&params=opened,,1

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

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_stats&params=opened

Example result with CSV format:

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

Example call with result in XML:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_stats&params=sla_compliance&return_type=xml

Example result in XML:

<xml>
97
</xml>

Result: Returns the summary of the status of the tickets.

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

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

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents_summary&return_type=csv

Example result with CSV format:

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

Example call with result in XML:

(syntax)

…/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 call with a specific field and result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incidents_summary&return_type=csv&params=not_closed

Example result with CSV format:

393

Example call with result in XML:

(syntax)

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

Result: Returns a list with the identifiers and names of the Pandora ITSM inventories.

Parameters: None.

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_inventories

Example result with CSV format:

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

Example call with result in XML:

(syntax)

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

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

Serialized parameters:

• id_user.
• id_group: They can be several groups separated by a token.

Example call:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=user_exists_in_group&params=test,4,5

Result: Returns a list with inventory objects associated with a ticket.

Serialized parameters:

• ticket filter: Identifier of the ticket (mandatory).

Example call with result in CSV format:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_incident_inventories&params=10

Example result with 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,description ,0,0,0,1,2017-08-02,new,2016-10-09,2017-10-09

Example call with result in XML:

(syntax)

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

Result: Returns the time that has passed in minutes since the last execution of the Crontask.

Parameters: None.

Example call:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_last_cron_execution

Result:

3

Example call with result in XML:

(syntax)

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

Result: Returns the number of emails that are queued pending to be sent.

Parameters: None.

Example call:

(syntax)

…/api.php?user=user&user_pass=userpass&pass=api_pass&op=get_num_queued_emails

Result:

20

Example call with result in XML:

(syntax)

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

To develop new calls for the API you must keep in mind that:

• The call must be registered as a function in the <PITSM installation>/include/functions_api.php file, besides being considered among the valid functions in the <PITSM installation>/include/api.php file.
• The function must return a single value or an array of pairs, for example name-value.
• The formatting of the call result to XML or CSV that is performed in the api.php file must be done automatically.

Definition in the functions_api.php file:

functions_api.php

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 the api.php file:

api.php

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

Definition in the functions_api.php file:

functions_api.php

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 the api.php file:

api.php

switch($op) {
 
        ...
 
    case "all_host_risk":
        $result = all_host_risk();
        break;
 
        ...
 
  }

←Back to the Pandora FMS documentation index