Getting started with the IT Glue API

For partners subscribed to the current Enterprise plan.

The IT Glue API 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. Before the API, you would need to use a CSV file to get data to and from your account. 

This article walks you through the process of creating "hello world" code so that you get some practice making calls to our API. 

You'll also learn about our newest endpoint, the Flexible Assets API. This new endpoint gives you a lot of power to automate getting data from external sources into your IT Glue account.

For example, you can create and run a PowerShell script to push domain controller information from Active Directory to populate flexible asset records in IT Glue. PowerShell is a tool that anyone performing Windows system administration tasks will probably be familiar with, but you can use any programming language that supports the creation of HTTPS requests and that can parse JSON, which includes most modern programming languages.


Accessing data / making requests 

IT Glue API Basics

  • Our API is RESTful.
  • All API access must use HTTPS .
  • The base URL for all endpoints and methods is: https://api.itglue.com
  • Data is sent and received as JSON. 
  • Dates are in UTC timezone.
  • HTTP response codes are used to indicate errors.

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 will need Administrator credentials to get your API key.

Some things to note:

  • 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're probably only seeing the first page. You'll need to request the remaining pages in order to get more results.
  • 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.

Let's get started!

By the end of this article, you'll know how to:

  • Make a GET request to list all your organizations
  • Make a GET request to list your flexible asset types 
  • Make a POST request to create a new flexible asset


Flexible asset endpoints and methods

If you have a lot of experience with flexible assets, you'll know that there are two types of flexible asset objects that you can interact with in your account. One is a flexible asset type, which provides the structure for your flexible assets. The other is a flexible asset, which is an object that has been created using the structure pre-defined by a flexible asset type. 

This is the same framework we used for the API. The following flexible asset endpoints and methods are supported:

Endpoints Description
GET /flexible_assets_types Returns a list of flexible asset types in your account.
GET /flexible_assets_types/:id Returns the details of an existing flexible asset type.
GET /flexible_assets Returns a list of flexible assets of a specified type for a given organization.
GET /flexible_assets/:id Returns the details of an existing flexible asset.
POST /flexible_assets Creates a new flexible asset.

 
Step 1: Creating a test environment

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

  1. From IT Glue, create one or more new organizations.
  2. Take note of the name of each test organization. You'll need the names to find the organization IDs further below.
Note: As you are testing the API, PSA syncing can be temporarily disabled by navigating to Account > Integrations and then clicking Actions and then Pause Sync. The change will take effect after any currently running sync completes. After that's done, any data you create in IT Glue to test the API won't accidentally push to your PSA. Remember to delete the organizations before restarting the sync.


Step 2: Getting the API key from IT Glue

You can generate one or more API keys for your account. The ability to generate multiple keys means you can use different keys for different integrations. 

To get a new API key:

  1. Users with an Administrator role can generate the API key by visiting their Account > Settings in IT Glue.
  2. The API keys section is located in a separate API Keys tab.
  3. Give the key a name and then generate the key. Note: You can't view a key again after it has been generated. 
Important: All API endpoints require authentication using a private API key. Whenever you send a request to the API, you send this key along with it so that we know it's you. This means that anyone who has your key will be able to access your data, so it’s important to keep the key safe. 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. 


Step 3: Get your organization IDs

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 will give you a list of all organizations, in the reverse order they were created. The list will include the organization name, the organization ID, and other details. Note the organization IDs. You will need the organization ID of one test organization in step 6.


GET /organizations?sort=-id HTTP/1.1
Host: https://api.itglue.com
Content-Type: application/vnd.api+json
x-api-key: ITG.**************************

Example response showing the details of one organization:



  "data": { 
    "id": "2", 
    "type": "organizations", 
    "attributes": { 
      "name": "Happy Frog", 
      "alert": "EXCHANGE SERVER WAS UPGRADED TO R2 2012", 
      "description": "Based in San Francisco, CA with major offices in Detroit. MI and Tampa, FL. In business since 1994, they have been a managed services client with Kraken Techs since 2009, and have plans to expand into Europe and Asia by 2020.", 
      "organization-type-id": 88, 
      "organization-type-name": "Testing Only", 
      "organization-status-id": 68, 
      "organization-status-name": "Active", 
      "primary": false, 
      "quick-notes": null, 
      "short-name": "happy", 
      "created-at": "2017-07-16T15:51:56.000Z", 
      "updated-at": "2017-07-16T15:53:55.000Z"
    } 
  } 
}

This is a scrollable box.


Step 4: Create a new flexible asset type

Open your IT Glue account and create a new flexible asset type. Any number and combination of fields can be used to create new flexible asset types. You'll find a table further below that details the different fields available for creating flexible asset types.

Let's create a very simple flexible asset type called "API Email Example" and give it six fields: a Type field, two Tag fields, two Select (drop-down) fields, and a Text field for a URL:

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


Step 5: Use a GET request to view the JSON object 

After you create a new flexible asset type in your account, send another GET request to get the JSON details of your new flexible asset type: 


GET /flexible_asset_types?sort=-id HTTP/1.1
Host: https://api.itglue.com
x-api-key: ITG.**************************
Content-Type: application/vnd.api+json

This call sends the request to the GET /flexible_asset_types endpoint with a reverse sort parameter (same basic call as in step 3). This gives you a list of all flexible asset types in the reverse order they were created.

Each flexible asset type will have an array of field objects. You will need the JSON details (object ID, plus name-keys for each field) from the "API Email Example" response body to complete the next step. 

Example response showing the details of one flexible asset type:


{
  "data": {
    "id": "33",
    "type": "flexible_asset_types",
    "attributes": {
      "name": "API Email Example", 
      "description": "This is an example",
      "created-at": "2017-07-27T16:20:43.000Z",
      "updated-at": "2017-07-27T16:20:43.000Z",
      "icon": "envelope",
      "show-in-menu": true,
      "fields": [
        {
          "id": 1182,
          "order": 1,   
          "name": "Domains",
          "kind": "Tag",
          "hint": "Tag accepted domains for this email system",
          "tag-type": "Domains",
          "required": true,
          "use-for-title": false,
          "show-in-list": true,
          "name-key": "domains",
          "created-at": "2017-07-27T16:20:43.000Z",
          "updated-at": "2017-07-27T16:20:43.000Z"
        },
        {
          "id": 1183,
          "order": 2,   
          "name": "Type",
          "kind": "Select",
          "hint": "Select the email platform",
          "default-value": "Office 365\nExchange 2016\nExchange 2013\nExchange 2010\nPOP/IMAP"
          "required": true,
          "use-for-title": true,
          "show-in-list": true,
          "name-key": "type",
          "created-at": "2017-07-27T16:20:43.000Z",
          "updated-at": "2017-07-27T16:20:43.000Z"
        },
        {
          "id": 1184,
          "order": 3,   
          "name": "Email Servers",
          "kind": "Tag",
          "hint": "Tag server(s) participating in email delivery",
          "tag-type": "Configurations",
          "required": false,
          "use-for-title": false,
          "show-in-list": true,
          "name-key": "email-servers",
          "created-at": "2017-07-27T16:20:43.000Z",
          "updated-at": "2017-07-27T16:20:43.000Z"
        }, 
        {
          "id": 1185,
          "order": 4,   
          "name": "Location",
          "kind": "Select",
          "hint": "Where is the email hosted",
          "default-value": "Cloud\nOn-Premises"
          "required": false,
          "use-for-title": false,
          "show-in-list": false,
          "name-key": "location",
          "created-at": "2017-07-27T16:20:43.000Z",
          "updated-at": "2017-07-27T16:20:43.000Z"
        },
        {
          "id": 1186,
          "order": 5,   
          "name": "Inbound Delivery",
          "kind": "Select",
          "hint": "How is inbound email delivered",
          "default-value": "Office 365\nGoogle\nProofpoint\nMimecast\nReflexion"
          "required": false,
          "use-for-title": false,
          "show-in-list": true,
          "name-key": "inbound-delivery",
          "created-at": "2017-07-27T16:20:43.000Z",
          "updated-at": "2017-07-27T16:20:43.000Z"
        },
        {            
          "id": 1187,
          "order": 6,   
          "name": "Webmail URL",
          "kind": "Text",
          "required": false,
          "use-for-title": false,
          "show-in-list": true,
          "name-key": "webmail-url",
          "created-at": "2017-07-27T16:20:43.000Z",
          "updated-at": "2017-07-27T16:20:43.000Z"
        },
      ] 
    }
  }
}



This is a scrollable box.


Step 6: Create a flexible asset 

Finally, let's update one of your test organizations to populate a flexible asset using the flexible asset type you created above.

When creating flexible assets, all "traits" are represented as key-value pairs. Traits are where your asset data is stored. The key part of the key-value pair is the name-key from one of the fields in the flexible asset type. The flexible asset type determines what kind of data each field (trait) can store. Dates, IDs, numbers, and strings are most common. If you skip a field, a "null" value for that trait will be displayed in the response.

Construct a POST request, like so:


POST /flexible_assets HTTP/1.1
Host: https://api.itglue.com
x-api-key: ITG.**************************
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "flexible-assets",
    "attributes": {
      "organization-id": 2,
      "flexible-asset-type-id": 33,
      "traits": {
        "domains": "happyfrog.com",
        "type": "Office 365",
        "location": "Cloud",
        "select": "Office 365",
        "webmail-url": "https://portal.office.com/" 
      }
    }
  }
}

This makes a request to the POST /flexible_assets endpoint with asset data that matches the structure 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.  

Example response:



  "data": { 
    "id": "401",
    "type": "flexible-assets", 
    "attributes": { 
      "organization-id": 2,
      "organization-name": "Happy Frog",
      "flexible-asset-type-id": 33,
      "flexible-asset-type-name": "API Email Example",
      "name": "Office 365", 
      "traits": {
        "domains": "happyfrog.com", 
        "type": "Office 365",
        "email-servers": null, 
        "location": "Cloud",
        "select": "Office 365",
        "webmail-url": "https://portal.office.com/"
      },
      "created-at": "2017-07-27T17:04:21.000Z", 
      "updated-at": "2017-07-27T17:04:21.000Z"
    }
  }
}


This is a scrollable box.


Next steps

We hope this article has given you the answers to some basic questions and started you thinking about new ways to use flexible assets. Once you realize how flexible assets can provide the means for storing any kind of data, the possibilities really start to open up. We'd love to hear your ideas in our community where there is a section just for flexible asset questions and ideas. 

Happy coding!


Notes on available fields and attributes

The different fields that may be returned for a flexible asset type are listed in the table below. The available attributes change depending on the field.

Field Description JSON Attributes

Checkbox

A simple checkbox.

order, name, hint, show-in-list, required, name-key
Date

A date field in yyyy-mm-dd format. 

order, name, hint, expiration, show-in-list, use-for-title, required, name-key 

Header 

A simple header to group related fields under a heading of your choosing.

order, name, default-value, name-key
Number

A number field.

order, name, default-value, hint, decimals, show-in-list, required, name-key

Password

A single-line text field that does not display its contents visibly by default.

order, name, hint, show-in-list, required, name-key
Percent

A number field that displays as a percentage. 

order, name, default-value, hint, decimals, show-in-list, required, name-key 

Select 

A drop-down menu that allows one value to be selected. 

Requires an default-value attribute, which specifies the values that will be used.

order, name, hint, default-value, show-in-list, use-for-title, required, name-key 
Tag

A text input for choosing one or more tags.

Requires a type attribute, which specifies the type of asset that will be used. 

order, name, hint, type, show-in-list, required, name-key 
Text 

A single-line text field.

order, name, hint, show-in-list, use-for-title, required, name-key

Textbox 

A text-format-enabled, multiple-line text field.

order, name, default-value, hint, show-in-list, required, name-key

Upload 

An upload button for choosing one or more files to upload. 

order, name, hint, show-in-list, required, name-key 

For more information about fields, see Flexible asset field definitions.

       

Where to next?

Was this article helpful?
2 out of 2 found this helpful