SAManage API

The SAManage REST API allows customers and developers to expand and build on the SAManage platform.

Introduction

SAManage provides an API that can be used to retrieve and update asset inventory information from your SAManage account. The SAManage API also allows to create, retrieve, update and delete asset information such as computers, software, printers, risks and other assets, contracts and software licenses, and help desk tickets. The API makes it easy to create applications and interface between your business systems and your SAManage account.

Some potential application ideas:

Integrate internal help desk / call center system to view asset information
Automatic contract / license creation from your procurement system
Trigger business processes based on tickets, for example new asset purchase request
Automate asset maintenance and disposal processes
Notify internal stakeholders of new risks and license compliance gaps

The SAManage API is built upon REST principles, making access to these actions consistent and intuitive. Collections are accessed via a URL ending in a plural noun such as '/hardwares', and to target an individual record, append it's numerical id (/hardwares/205778). To tell the API whether you are retrieving, updating, or deleting the record, make use of the "HTTP verbs", GET, PUT, and DELETE (respectively). For example, to create a new record, send a POST request to the collection's URL (/hardwares). The API will respond with a document reflecting your changes.

Tip: When building your API requests, as a best practice we recommend logging into your online SAManage account and reviewing your inventory and asset information. You can than compare the response your API calls receive with the information as shown in the online account.

General Concepts

Service URL

https://app.samanage.com/

Representation Formats

The API supports both XML and JSON formats. To specify the required format, add the format extension to the API call. For example, to retrieve a list of tickets in XML format, send a request to the /hardwares.xml path. To retrieve the same tickets list in JSON format, send the request to /hardwares.json.

Authentication

The API authentication is based on HTTP digest authentication (http://en.wikipedia.org/wiki/Digest_access_authentication). Clients should supply both the username and password created for integration with the API. This username and password should be supplied only upon the first request to the API. All subsequent requests will automatically use the same credentials.
Example:
curl --digest -u "username:password" "https://app.samanage.com/api.xml"
If the authentication fails, a "401 Unauthorized" message will be returned.

Security

Usernames and passwords should never be transferred in plain text over the wire. Instead, use SSL (which can be accessed using https://) to ensure that all communication with the server is encrypted and secured.

Versioning

We expect clients to provide the version number they are ready to work with in the "Accept" HTTP header. Valid "Accept" headers should specify which content type and version number the client is ready to work with. For example, "application/vnd.samanage.v1+xml".

If no "Accept" header is specified, the API will use the latest available version. We strongly recommend indicating the supported version number in the HTTP header, so when we upgrade the API version, your client won't be impacted. We will provide advanced notice when we roll out new versions of the API, so you can benefit from new capabilities.

If you request an API version that is no longer supported, the API will respond with an HTTP status code of "406 - Not Acceptable".

Example:

curl --digest -u "username:password" -H "Accept: application/vnd.samanage.v1+xml" https://app.samanage.com/hardwares.xml

Pagination

Every response with a large result set will be paginated. For example, the response to /tickets.xml might look like this:
<hardwares>
   <page>2</page>

   <per_page>25</per_page>

    <total_entries>159</total_entries>
    <hardware>...</hardware>
   <hardware>...</hardware>
   ...
</hardwares>

You can request a specific page by supplying a "page" parameter. For example, to request the third page of the hardware list, you can use the following command:
curl --digest -u "username:password" http://app.samanage.com/hardwares.xml?page=3

API Calls

Here are a few examples of supported API calls, and the corresponding responses. These examples are shown in the form of 'curl' commands. Curl (http://en.wikipedia.org/wiki/CURL) is a command line utility used to perform HTTP requests, and is available on most Unix systems. However, you can use any tool or language that can submit a corresponding HTTP request. Curl, in the form of libcurl, has bindings in more than 30 languages, which should provide a tool that can be used in whatever language you are working with.

Common Parameters

Every list will accept a page=<page number> parameter. The response will return those assets on the specified page.

API Entry Point

All communication with the API begins with a list of available services. Although it is possible to get to a specific service URL directly, we advise you to start with the api.xml entry point. That way, your program will still work properly if we change the underlying URLs for services in future versions of the API.

Request

GET https://app.samanage.com/api.xml
curl --digest -u "username:password" -H "Accept: application/vnd.samanage.v1+xml" -X GET https://app.samanage.com/api.xml

Response

<?xml version="1.0" encoding="UTF-8"?>
<services>
   <service>
   <href>https://app.samanage.com/hardwares.xml</href>
   <name>Computers List</name>
   </service>
   <service>
   <href>https://app.samanage.com/tickets.xml</href>
   <name>Helpdesk Tickets List</name>
   </service>
   <service>
   <href>https://app.samanage.com/risks.xml</href>
   <name>Risks List</name>
   </service>
   <service>
   <href>https://app.samanage.com/contracts.xml</href>
   <name>Contracts List</name>
   </service>
   <service>
   <href>https://app.samanage.com/softwares.xml</href>
   <name>Software List</name>
   </service>
   <service>
   <href>https://app.samanage.com/solutions.xml</href>
   <name>Solutions List</name>
   </service>
   <service>
   <href>https://app.samanage.com/other_assets.xml</href>
   <name>Other Assets List</name>
   </service>
   <service>
   <href>https://app.samanage.com/vendors.xml</href>
   <name>Vendors List</name>
   </service>
   <service>
   <href>https://app.samanage.com/printers.xml</href>
   <name>Printers List</name>
   </service>
   <service>
   <href>https://app.samanage.com/audits.xml</href>
   <name>Audit Log List</name>
   </service>
</services>

Computers List

Request

GET https://app.samanage.com/hardwares.xml

curl --digest -u "username:password" -H "Accept: application/vnd.samanage.v1+xml" -X GET https://app.samanage.com/hardwares.xml

Parameters

A computers list can be filtered using a variety filters (or any combination of multiple filters). These filters match the views and filters available in the application: category, status, operating_system, processor, tag, manufacturer, domain, site, department, recently_added, not_reporting.
Your request can determine the possible values for each parameter in the "Computers" section. (https://app.samanage.com/hardwares)

Example:

curl --digest -u "username:password" -H "Accept: application/vnd.samanage.v1+xml" -X GET "https://app.samanage.com/hardwares.xml?status=operational&site=boston&manufacturer=dell"

Please note that the recently_added and not_reporting parameters will require you to provide the number of days, and will return new computers added in last <number> days or computers that have not reported in the last <number> days.

Example:

curl --digest -u "username:password" -H "Accept: application/vnd.samanage.v1+xml" -X GET "https://app.samanage.com/hardwares.xml?status=operational&not_reported=10"

The command in the previous example will return all computers which have "operational" status, and have not reported within the last 10 days.

Response
<?xml version="1.0" encoding="UTF-8"?>
<hardwares>
   <page>1</page>
   <per_page>50</per_page>
   <total_entries>62</total_entries>
   <hardware>
   <hidden-softwares-href>https://app.samanage.com/hardwares/12345/softwares.xml?view=system</hidden-softwares-href>
   <operating-system>Windows XP Professional</operating-system>
       <tickets-href>https://app.samanage.com/hardwares/12345/tickets.xml</tickets-href>
   <href>https://app.samanage.com/hardwares/12345.xml</href>
   <site>Boston</site>
   <risks-href>https://app.samanage.com/hardwares/12345/risks.xml</risks-href>
   <updated-at>2009-08-15T10:39:45Z</updated-at>
   <status>Operational</status>
   <name>MAIN</name>
   <tag nil="true"></tag>
   <department>Sales</department>
   <cpu>Pentium M 1.50GHz</cpu>
   <softwares-href>https://app.samanage.com/hardwares/12345/softwares.xml</softwares-href>
   <created-at>2009-08-15T10:39:45Z</created-at>
   <ip>192.168.1.100</ip>
   <audits-href>https://app.samanage.com/hardwares/12345/audits.xml</audits-href>
   <category>Laptop</category>
   <id>12345</id>
   <asset-id>ASSET3747493</asset-id>
   <domain>MY_DOMAIN</domain>
   </hardware>
   ...
</hardwares>

Computer Details (Asset Information)

To receive the details of a single computer, use the request below.

Request

GET https://app.samanage.com/hardwares/<hardware_id>.xml
curl --digest -u "username:password" -H "Accept: application/vnd.samanage.v1+xml" -X GET https://app.samanage.com/hardwares/12345.xml

Response

<?xml version="1.0" encoding="UTF-8"?>
<hardware>
   <href>https://app.samanage.com/hardwares/12345.xml</href>
   <operating-system>Windows XP Professional</operating-system>
   <memory>512</memory>
   <videos>
   <video>
   <chipset>Intel(R) 82852/55 Graphics Controller</chipset>
   <memory>64</memory>
   <name>Intel(R) 82852/82855 GM/GME Graphics Controller</name>
   </video>
   </videos>
   <memories>
   <memory>
   <capacity>256</capacity>
   <description>DIMM 1 (No ECC)</description>
   <memory-type>Unknown</memory-type>
   <name>Physical Memory</name>
   <purpose>System Memory</purpose>
   <slot>1</slot>
   <speed>N/A</speed>
   </memory>
   </memories>
   <printers>
   <printer>
   <driver>hp psc 2100 series</driver>
   <name>hp psc 2100 series</name>
   <port>USB001</port>
   </printer>
   </printers>
   <site>Boston</site>
   <processor-speed>1495</processor-speed>
   <username>John</username>
   <usbs>
   <usb>
   <controller-type>USB Controller</controller-type>
   <description>Intel(R) 82801DB/DBM USB Universal Host Controller - 24C2</description>
   <manufacturer>Intel</manufacturer>
   <name>Intel(R) 82801DB/DBM USB Universal Host Controller - 24C2</name>
   <version>N/A</version>
   </usb>
   </usbs>
   <updated-at>2009-08-15T10:39:45Z</updated-at>
   <status>Operational</status>
   <name>JOHNDOE</name>
   <notes nil="true"></notes>
   <keyboards>
   <keyboard>
   <input-type>Keyboard</input-type>
   <manufacturer nil="true"></manufacturer>
   <name>Enhanced (101- or 102-key)</name>
   </keyboard>
   </keyboards>
   <tag nil="true"></tag>
   <department>Sales</department>
   <description>My main laptop</description>
   <displays>
   <display>
   <description nil="true"></description>
   <manufacturer>Unknown manufacturer code PNP</manufacturer>
   <name></name>
   <serial-number nil="true"></serial-number>
   </display>
   </displays>
   <storages>
   <storage>
   <description>Disk drive</description>
   <manufacturer>(Standard disk drives)</manufacturer>
   <model>//./PHYSICALDRIVE0</model>
   <name>HTS548040M9AT00</name>
   <size>38154</size>
   <storage-type>Fixedxhard disk media</storage-type>
   </storage>
   </storages>
   <cpu> Pentium M 1.50GHz</cpu>
   <bioses>
   <biose>
   <bios-date>N/A</bios-date>
   <manufacturer>IBM</manufacturer>
   <model>2887AVG</model>
   <ssn>99DTZM6</ssn>
   <version>IBM - 1030;Phoenix FirstBIOS(tm) Notebook Pro Version 2.0 for IBM ThinkPad;Ver 1.00PARTTBL- SMBiosVersion: 1VET45WW (1.03 )</version>
   </biose>
   </bioses>
   <ports>
   <port>
   <description>ThinkPad Integrated 56K Modem</description>
   <name>ThinkPad Integrated 56K Modem</name>
   <port-type>Serial</port-type>
   </port>
   <port>
   <description>Communications Port</description>
   <name>Communications Port (COM1)</name>
   <port-type>Serial</port-type>
   </port>
   </ports>
   <created-at>2009-08-15T10:39:45Z</created-at>
   <ip>192.168.1.100</ip>
   <swap>1226</swap>
   <technical-contact>
   <email>johndoe@example.com</email>
   <first-name>John</first-name>
   <last-login>2008-11-04T15:54:08Z</last-login>
   <last-name>Doe</last-name>
   <phone nil="true">23423424234234</phone>
   </technical-contact>
   <sounds>
   <sound>
   <description>SoundMAX Integrated Digital Audio</description>
   <manufacturer>Analog Devices, Inc.</manufacturer>
   <name>SoundMAX Integrated Digital Audio</name>
   </sound>
   </sounds>
   <mice>
   <mouse>
   <input-type>Pointing</input-type>
   <manufacturer>IBM Corporation</manufacturer>
   <name>IBM ThinkPad UltraNav Pointing Device</name>
   </mouse>
   </mice>
   <networks>
   <network>
   <description>Intel(R) PRO/100 VE Network Connection - Packet Scheduler Miniport</description>
   <dhcp>255.255.255.255</dhcp>
   <gateway nil="true"></gateway>
   <ip-address>0.0.0.0</ip-address>
   <mac-address>00:00:00:00:00:00</mac-address>
   <status>Down</status>
   </network>
   <network>
   <description>Intel(R) PRO/Wireless 2200BG Network Connection - Packet Scheduler Miniport</description>
   <dhcp>192.168.1.1</dhcp>
   <gateway>192.168.1.1</gateway>
   <ip-address>192.168.1.100</ip-address>
   <mac-address>00:00:00:00:00:00</mac-address>
   <status>Up</status>
   </network>
   </networks>
   <drives>
   <drive>
   <drive-name nil="true"></drive-name>
   <drive-type>Hard Drive</drive-type>
   <free-space>7163</free-space>
   <name>C:/</name>
   <total-space>33864</total-space>
   </drive>
   </drives>
   <category>Laptop</category>
   <id>12345</id>
   <asset-id>ASSET3747493</asset-id>
   <domain>MY_DOMAIN</domain>
   <risks-href>https://app.samanage.com/hardwares/12345/risks.xml</risks-href>
   <audits-href>https://app.samanage.com/hardwares/12345/audits.xml</audits-href>
   <softwares-href>https://app.samanage.com/hardwares/12345/softwares.xml</softwares-href>
   <hidden-softwares-href>https://app.samanage.com/hardwares/12345/softwares.xml?view=system</hidden-softwares-href>
   <tickets-href>https://app.samanage.com/hardwares/12345/tickets.xml</tickets-href>
</hardware>

Examples

Risks

The request below will return a list of all risks in the account.

GET "https://app.samanage.com/risks.xml"

curl --digest -u "username:password" -H "Accept: application/vnd.samanage.v1+xml" -X GET "https://app.samanage.com/risks.xml"

Tickets

This request will return a list of all tickets in the help desk.

GET "https://app.samanage.com/tickets.xml"

curl --digest -u "username:password" -H "Accept: application/vnd.samanage.v1+xml" -X GET "https://app.samanage.com/tickets.xml"

New Computers Added in Last X Days

Use this request to receive a list of all new computers added to the account in the last X days.

GET "https://app.samanage.com/hardwares.xml?recently_added=7"

curl --digest -u "username:password" -H "Accept: application/vnd.samanage.v1+xml" -X GET "https://app.samanage.com/hardwares.xml?recently_added=7"

Software Summary

This request returns a summary of all software in the account.

GET "https://app.samanage.com/softwares.xml"

curl --digest -u "username:password" -H "Accept: application/vnd.samanage.v1+xml" -X GET "https://app.samanage.com/softwares.xml"

Computer - Software Inventory

Use the command below to get a list of all software items installed on a computer.
GET https://app.samanage.com/softwares.xml
curl --digest -u "username:password" -H "Accept: application/vnd.samanage.v1+xml" -X GET "https://app.samanage.com/hardwares/12345/softwares.xml

Computer - Hidden Software Inventory

This request will return all hidden software installed on this computer. This usually includes any operating system patches and service packs.
GET https://app.samanage.com/softwares.xml
curl --digest -u "username:password" -H "Accept: application/vnd.samanage.v1+xml" -X GET "https://app.samanage.com/hardwares/12345/softwares.xml?view=system

Computer - Audit Records

To see all audit records for a specific computer, use the request below. Audit records usually include any changes in hardware and software. For example, "memory was upgraded to 2GB", as well as new tickets created, or new risks detected. Generally, all changes that take place during the computer’s lifetime are recorded in the audit log.

GET https://app.samanage.com/audits.xml
curl --digest -u "username:password" -H "Accept: application/vnd.samanage.v1+xml" -X GET "https://app.samanage.com/hardwares/12345/audits.xml

Computer - Tickets List

This request returns all help desk tickets associated with a certain computer.
GET https://app.samanage.com/tickets.xml
curl --digest -u "username:password" -H "Accept: application/vnd.samanage.v1+xml" -X GET "https://app.samanage.com/hardwares/12345/tickets.xml

Computer - Ticket Details

Get the details of a specific ticket using the command below.
GET https://app.samanage.com/tickets/<ticket_id>.xml
curl --digest -u "username:password" -H "Accept: application/vnd.samanage.v1+xml" -X GET "https://app.samanage.com/hardwares/12345/tickets/85.xml"

Computer - Risks List

The following request will return all risks associated with a specific computer.

GET https://app.samanage.com/risks.xml
curl --digest -u "username:password" -H "Accept: application/vnd.samanage.v1+xml" -X GET "https://app.samanage.com/hardwares/12345/risks.xml

SAManage API

Introduction

Some potential application ideas:

General Concepts

Service URL

https://app.samanage.com/

Representation Formats

Authentication

Security

Versioning

Example:

Pagination

API Calls

Common Parameters

API Entry Point

Request

Response

Computers List

Request

Parameters

Example:

Example:

Computer Details (Asset Information)

Request

Response

Examples

Risks

Tickets

New Computers Added in Last X Days

Software Summary

Computer - Software Inventory

Computer - Hidden Software Inventory

Computer - Audit Records

Computer - Tickets List

Computer - Ticket Details

Computer - Risks List

Product Tour

Solutions

Resources

Support

Partners

Company