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.

We recommend using curl for developing and testing out the various features that the API offers. Another online option to curl is hurl.

General Concepts

Service URL

https://api.samanage.com/

Representation Formats

The API supports the XML format. 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.

Authentication

The API authentication is based on HTTP digest 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://api.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 version 1.0. 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

Version History

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 providing 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" https://app.samanage.com/hardwares.xml?page=3

To control the number of rows returned provide the per_page parameter. (You can request a maximum of 100 rows. When you make a request, the per page parameter you set will be saved until you make a new request.) For example, to request 100 rows with each result page, use the following command:

curl --digest -u "username:password" https://app.samanage.com/hardwares.xml?per_page=100

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= 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://api.samanage.com/api.xml

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

Response

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

Short / long layout:

For all APIs, you can specify the layout (short / long). This affects the length of the returned records, and is relevant for changes, contracts, hardwares, incidents, other assets, problems, and solutions.

To use, add the parameter to the request: “?layout=short” or “?layout=long”. If not present, the default is “short”.

Searching:

You can search for records by using query parameters on top of the base URL. For example, when requesting a list of hardwares, you may want to limit them to only those with a specific IP address. This could be accomplished with a request like GET https://api.samanage.com/hardwares.xml?ip_address=123.456*

Here, ip_address is a query parameter that implements a filter where the IP equals 123.456.xxx.xxx.

Other examples:

https://api.samanage.com/other_assets.xml?asset_id=XXXXXXXX
https://api.samanage.com/hardwares.xml?asset_tag=XXXXXXXX