The Samanage REST API allows customers and developers to expand and build on the Samanage platform.
Samanage provides an API that can be used to retrieve and update asset inventory information from your Samanage Professional 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.
For European based customers, please use:
You can use XML or JSON format for your request. For example:
curl -H "X-Samanage-Authorization: Bearer TOKEN" -H 'Accept: application/vnd.samanage.v2.1+xml' -X GET https://api.samanage.com/incidents.xml
curl -H "X-Samanage-Authorization: Bearer TOKEN" -H 'Accept: application/vnd.samanage.v2.1+json' -H 'Content-Type: application/json' -X GET https://api.samanage.com/incidents.json
For create and update, the provided data needs to be in the correct format.
To clear fields, use the following format:
The API authentication is token-based. Admins can generate a token for their own user in the user setup page. Then admins can provide that token to the API developer in order for them to gain access to items in Samanage via the API. Admins can also re-generate their tokens from the user setup page, that will invalidate all previously generated tokens.
The tokens are relatively long strings that look like this: AAAZWV0YXkubmF0YW4rNUBzYW1hbmFnZS5jb20hbGciOiJIUzUxMiJ9.eyJ1c2VyX2ljIjoxMjU2OTQzLCJnZW5lcmF0ZWRfYXQiOiIyMDE3LTA2LTA3IDA5OjE3OjI5In0.j_H15qzJJr9vXGAHCThLEOQrE9GGbjMxZJOs5zAf_iqaGqxlIOAmvPpBx0td_C3r7dliAfXXIgdqhZHVoK1KTwAzd1
In order to supply the API token you should pass X-Samanage-Authorization header in the following format: “Bearer API_TOKEN_STRING”. Assuming that the token obtained in the user setup page is AAAZWV0YXkubmF0YW4rNUBzYW1hbmFnZS5jb20hbGciOiJIUzUxMiJ9.eyJ1c2VyX2ljIjoxMjU2OTQzLCJnZW5lcmF0ZWRfYXQiOiIyMDE3LTA2LTA3IDA5OjE3OjI5In0.j_H15qzJJr9vXGAHCThLEOQrE9GGbjMxZJOs5zAf_iqaGqxlIOAmvPpBx0td_C3r7dliAfXXIgdqhZHVoK1KTwAzd1 the API call looks like this:
curl -H “X-Samanage-Authorization: Bearer AAAZWV0YXkubmF0YW4rNUBzYW1hbmFnZS5jb20hbGciOiJIUzUxMiJ9.eyJ1c2VyX2ljIjoxMjU2OTQzLCJnZW5lcmF0ZWRfYXQiOiIyMDE3LTA2LTA3IDA5OjE3OjI5In0.j_H15qzJJr9vXGAHCThLEOQrE9GGbjMxZJOs5zAf_iqaGqxlIOAmvPpBx0td_C3r7dliAfXXIgdqhZHVoK1KTwAzd1” -H “Accept: application/vnd.samanage.v2.1+xml” https://api.samanage.com/hardwares.xml
If the authentication fails, a “401 Unauthorized” message will be returned.
Requests 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.
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.v2.1+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”.
curl -H "X-Samanage-Authorization: Bearer TOKEN" -H "Accept: application/vnd.samanage.v2.1+xml" https://api.samanage.com/hardwares.xml
- 1.0: Deprecated
- 1.1: Changed structure of custom_fields_values
- 1.2: Changed name of “incident_type” to “category” in Catalog items and Incidents
- 1.3: Updates to incidents or comments will not send an email or a notification to the users.
- 2.1: Token based authentication
Every response with a large result set will be paginated. The response will include the pagination data as headers and links (formatted as <url>; rel=”relative”). For example:
Link: <https://api.samanage.com/incidents.xml?page=1>; rel="first",
Xml data will also include pagination details in the response body. For example, the response to /tickets.xml might look like this:
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 -H "X-Samanage-Authorization: Bearer TOKEN" https://api.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 -H "X-Samanage-Authorization: Bearer TOKEN" https://api.samanage.com/hardwares.xml?per_page=100
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.
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.
curl -H "X-Samanage-Authorization: Bearer TOKEN" -H "Accept: application/vnd.samanage.v2.1+xml" -X GET https://api.samanage.com/api.xml
<xml version="1.0" encoding="UTF-8">
<name>Helpdesk Incidents List</name>
<name>Other Assets List</name>
<name>Audit Log List</name>
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”.
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
Here, ip_address is a query parameter that implements a filter where the IP equals 123.456.xxx.xxx.
The following date formats are allowed as input when updating date fields:
- January 21, 2015
- January 21 2015
- Jan 21, 2015
- Jan 21 2015
To set custom fields, use the following data format:
"name": "field name",
"name": "field name",