Getting started with the IT Glue API

For partners subscribed to the current Enterprise plan.

Introduction

The IT Glue API is a powerful tool for automation and getting data from external sources into your IT Glue account. It provides a direct, machine-friendly way of accessing your data, so that you can pull it into your own applications or integrate with third-party tools that we don't currently integrate with.

In this article, you'll learn how to:

• Generate an API key from IT Glue
• Locate a new organization's object ID using a GET request
• Use a parameter in the GET request to sort the output by a specific field like the object ID
• Locate a new flexible asset type's object ID and field name-keys using GET requests
• Use the requested data to POST (create) new flexible assets

Programmatically accessing data and making requests

If you're an Administrator on your account and you have some programming experience, you’ve got everything you need to start making requests and accessing your data. You need your Administrator credentials to generate an API key.

REST APIs have a base URL to which the endpoint paths are appended. The developer documentation for each endpoint shows the parameters that can be appended to the base URL to form a request (or sent as the body of the request). The base URL for all endpoints and methods is: https://api.itglue.com. EU partners will use https://api.eu.itglue.com.

The following is an example of the form of a request URL:

https://api.itglue.com/organizations?sort=id

which is composed of the following parts:

Base URL:  https://api.itglue.com

Path:/organizations

Query parameter:sort=id

Some things to note:

• All API access must use HTTPS.
• Data is sent and received as JSON.
• Dates are in UTC timezone and in the following format: yyyy-mm-dd (e.g. 2016-03-31).
• By default, you get a paginated set of objects (50 per page is the default). If you're making requests and receiving an incomplete set of results, you might only be seeing the first page. You'll need to request the remaining pages to get more results.
• HTTP response codes are used to indicate errors. The developer documentation provides more information, including details about the kinds of errors each API call might result in and what could cause such errors.
• There is an API payload size limit of 10MB, set by Amazon API Gateway. For more information please see this article. 

Flexible asset resources

In the IT Glue API, there are three Flexible Asset resources that you can interact with:

• Flexible Asset Type - An object that defines the data structure of Flexible Assets as a table containing one or more child field objects with defined field specifications. There are multiple types of fields for different kinds of inputs such as string, text, date, and number.
• Flexible Asset Field - A child object to a parent Flexible Asset type. This object exists to allow you to interact directly with the individual fields of a flexible asset type.
• Flexible Asset - An object created from the data structure pre-defined by a Flexible Asset type.

Instructions

Creating a test environment

We recommend setting up a test environment in your account. As you are accessing the API in production, you'll want to keep your API tests confined to a handful of test organizations.

1. Log in to IT Glue and create one or more new organizations.
2. Note the name of each test organization. You'll need the names to find the organization IDs further in this KB article.

NOTE  PSA syncing can be temporarily disabled by clicking Admin > Integrations and then Actions> Pause Sync. The change takes effect after any running sync jobs complete. This ensures that any test data you create won't accidentally push to your PSA. Remember to delete the test organizations before restarting the sync.

Generating an API key

All API endpoints require authentication using a private API key. You can generate one or more API keys for your account. To generate a new API key:

1. Users with an Administrator role can navigate to Admin > Settings.
2. Click on API Keys > Custom API Keys.
3. Enter a name for the key and click Generate API Key. You will not be able to view a key again after it has been generated.
4. For security, an optional Password Access setting is provided for each API key. Password values can be accessed from the Passwords API only if this setting is enabled.
5. To generate multiple API keys, click the plus sign icon.
   

IMPORTANT  Whenever you send a request to the API, you send your key with it so that we know it's you. This means that anyone who has your key can access your data, so it’s important to keep it private. You can revoke an old API key and generate a new one at any time from your IT Glue account. Any requests made using your old key will no longer work.

Get your organization ID

Now you can start building the first request. The most important part is setting the authorization header to provide the API key.

This first call is a GET request that gives you a list of all organizations in the reverse order they were created. The list includes the organization name, the object ID, and other details. Locate and take note of the ID of one of your test organizations - you will need it when you create a flexible asset later in the process.

Click each of the tabs below:

Create a new flexible asset type

In IT Glue, create a new Flexible Asset type. In the example below, we created a Flexible Asset type called "API Email Example" and gave it six fields: a Type, two Tags, two Select (drop-downs), and a Text field for a URL. In this example, only the first and second fields are required.

Name: Domains
Kind: Tag 
Hint: Tag accepted domains for this email system
Type: Domains 
Checkboxes: Required, Show in list

Name: Type
Kind: Select 
Hint: Select the email platform
Options: Office 365, Exchange 2016, Exchange 2013, POP/IMAP
Checkboxes: Required, Use for title, Show in list 

Name: Email Servers
Kind: Tag
Hint: Tag server(s) participating in email delivery 
Type: Configurations
Checkboxes: Show in list

Name: Location
Kind: Select
Hint: Where is the email hosted
Options: Cloud, On-Premises

Name: Inbound Delivery
Kind: Select
Hint: How is inbound email delivered
Options: Office 365, Google, Proofpoint, Mimecast, Reflexion
Checkboxes: Show in list

Name: Webmail URL 
Kind: Text
Checkboxes: Show in list

Flexible asset types may contain any number and combination of fields. To decide which field types to use, refer to the table below. For more information, see Flexible asset field definitions.

Option	Description
Checkbox	A true/false field. The checkbox is ticked when the value is set to true.
Date	A date field.
Number	A number field.
Select	A field that provides a set of values in a drop-down menu.
Tag	A field that allows one or more assets to be tagged.
Text	A short text field for adding a small amount of text.
Textbox	A multi-line text field for adding a large body of text.

Use a GET request to locate the Flexible Asset type ID

After you create a new Flexible Asset type in your account, send another GET request to get the JSON object ID of your newFlexible Asset type. When you make this call, you receive a list of allFlexible Asset types in the reverse order they were created. Locate and note the ID of your newly created Flexible Asset type. You'll need the ID further in this KB article.

Click each of the tabs below:

Use a GET request to view the JSON object

This next call sends the request to the GET /flexible_asset_types endpoint with the JSON object ID and the flexible_asset_fields parameter included. You need the JSON object details (name-keys for each field) from the response body to complete the next step. Copy and paste the information to where you can refer to it.

Click each of the tabs below:

Create a flexible asset

Finally, let's create a flexible asset using the flexible asset type you created above.

When creating your flexible asset, pass the values as a JSON object that has defined "traits". Traits are key-value pairs and used to create your Flexible Asset data. An example would look like {"name-key1": 1, "name-key2": 2}. View your Flexible Asset type to identify the name-key for each field you want to populate as well as any fields that may be required.

A Flexible Asset can be tagged with associated organizations, configurations, contacts, etc. which are all separate JSON objects. When creating the trait values, you need to enter the JSON object IDs of the assets being tagged. You can use the API to make additional calls to get the object IDs. However, after you create an asset in your account, IT Glue gives it a URL that references the asset's object ID. If you need a quick way to find an asset's object ID, view the asset in IT Glue and locate the object ID in the URL. Now, construct a POST request.

Click each of the tabs below:

This makes a request to the POST /flexible_assets endpoint that conforms to the field specification of the Flexible Asset type you created earlier. The new Flexible Asset is associated with the organization ID and Flexible Asset type ID you specified in the request. The response returns the created Flexible Asset if successful.

JSON Trait Examples

Trait values must be a valid data type (string, number, array, boolean, or null). Use the following table as a reference when determining what kind of data type to enter.

Field	Name	JSON
Checkbox	Client has signed and acknowledged MSA	{"client-has-signed-and-acknowledged-msa": true}
Date	Signing Date	{"signing-date": "2018-10-31"}
Number	Number of seats	{"number-of-seats": 25}
Select	Field Technician	{"field-technician": "Randy Rios"}
Tag	Emergency Contact	To pass a single tag {"emergency-contact": 4387} To pass multiple tags {"emergency-contact": [4387, 3901, 7891]}
Text	Emergency Contact Telephone Number	{"emergency-contact-telephone-number": "555-234-9876"}
Textbox	Notes	{"notes": "These are the notes."}

Further reading

Learn more about working with the API in the developer docs.

NOTE  Thanks to community member Caleb Albers there is now a PowerShell API wrapper and a place to share information about automating documentation on GitHub at https://github.com/itglue/automation. This collection of tools and code samples was designed to give developers the means to script and automate their Active Directory and IT infrastructure documentation.