Development for the Inspection Support Network

This site documents way to develop with and for the Inspection Support Network™

System Concepts

The Inspection Support Network (ISN) has a few different development concepts which need to be understood before designing your integration:

Service Domain

An individual's ISN can be launched from any URL. Customers can have a "white labeled" domain which they may use for ISN. Before an application talks to an individual ISN's API End Point (see below). A service domain is literally the user's domain without any additional pathing information. An example might be 4isn.com or inspectionsupport.net.

Company Key

All ISNs require the use of a Company Key. The Company Key is a unique "slug" key which ISN provides to each and every client. Company Key are strictly first-come-first-serve and help individualize an ISN. Every ISN has a unique key which exists in lower case, alpha-numeric (and can include a dash character). Every ISN client should be able to disclose their company key to you. Additionally, all company keys are available in the ISNs URL.

API Endpoints

All ISNs are sandboxed such that each client is provided their own runtime space and own unique URL. The API endpoint for the specific ISN is thus located within their own unique URL. Therefore, before calling the ISN’s individual REST API you must determine the URL for the API. URLs are constructed using the Service Domain plus the Company Key. If a service domain is inspectionsupport.net and the company key is test then the API Endpoints will be available at: https://inspectionsupport.net/test/

Access Key / Secret Access Key

All users in ISN have username(s) and password(s) which work perfectly on the API, however, we prefer that 3rd party vendors request an Access Key and a Secret Access Key from the User(s). The keys allow the individual users to cancel their keys without resetting passwords. Both username/password and access_key/secret_access_key pairs will authenticate a user into ISN from the REST API. So you can opt to use either method. However, we do suggest for all 3rd party development that keys are used to help protect the user.

We share with our users that the Access Keys are used by 3rd party applications to safely and security communicate ISN account information without disclosing their username and password directly to a 3rd Party. For user protection, users are instructed to never share their secret access keys with anyone. A user can generate a new set of keys at anytime by clicking on the Generate New Keys button in their Settings area.






Yes, there are two APIs

The ISN maintains two (2) different REST APIs - the Admin API helps find the end point for the ISN API so that customers do not need to know where their ISN is at.

If you know where your ISN is at (what URL it is and what your company key is) you DO NOT need to use the Admin API

If you DO NOT know where your ISN is at -OR- you are another vendor looking to support multiple ISN users you should absolutely use the Admin API






isnadmin.com - the Admin API

ISNs do not all exist at the same URL due to unique values for Company Key and the ability to have your own Service Domain. ISN URLs can be obtained by calling the ISN ADMIN API which is documented at http://api.isnadmin.com At this URL you can even make sample calls and test the endpoints to ensure you understand the return values and required parameters. The ISN ADMIN REST API contains a GET call which allows retrieval of an ISN’s URL via username and password provided to the 3rd Party from the ISN operations team.

In order to use the Admin API at isnadmin.com you must have an integration username and password.

Request a integration Username and Password

      

          $integration_user = '34503650283750270350263598203528735';
          $integration_pass = '49762993523y59273958729876567293875';
          $company_key = 'test';

          // this example uses guzzle - http://guzzlephp.org/

          require_once 'vendor/autoload.php';
          use Guzzle\Http\Client;

          // Create a client and provide a base URL
          $client = new Client('https://isnadmin.com/rest');

          // Create a request with basic Auth
          $request = $client->get('/isn/url?companykey='.$company_key)->setAuth($integration_user, $integration_pass);

          // Send the request and get the response
          $response = $request->send();

          $response_object = json_decode( $response->getBody() );

          if ($response_object->status == 'ok') {
          $url = $response_object->url;
          }

          echo 'URL: '.$url;

      
    





The ISN API

Using the isnadmin.com API allows you to obtain the ISN API endpoint. Now that you have the URL for the REST API you can read more about it at this location: http://api.inspectionsupport.net/ At this URL you can even make sample calls and test the endpoints to ensure you understand the return values and required parameters.

ISN Concept: Footprints

Footprints in the ISN are essentially small information "hooks" which point to "upcoming" inspections / orders which the inspector whom logged in (or whose access information was used to make the REST calls) has "upcoming". If an inspector has two upcoming inspections is it most likely the user has two footprints available in ISN under their username/password.

ISN Concept: Determining upcoming Jobs

First, determine the URL for the REST endpoint per ISNADMIN.COM’s REST API (see above). Next, you must get all of the footprints available for that user. To do this, use the GET method on orders/footprints (http://api.inspectionsupport.net/#!/orders/footprints_get_0). This will return a list of footprints (order/inspection stubs). From there you can request more information for each inspection, agent and client(s). Each client / agent / order has an ID (this is a true UUID) which is used to link back to the order/client/agent and also query via the REST API.

After you have secured the information you MUST delete the footprint (http://api.inspectionsupport.net/#!/orders/footprint_delete_1). Footprints stay in the system until 3rd party apps request deletion -OR- after X period of time the ISN will automatically purge them. The time X is determined by the customer’s settings.






Example Usage - Known Company Key (Typically an ISN User)

If you already know your company key (typically you are a user of ISN and you are just wanting to connect with YOUR ISN and not other ISNs) this walk through is for you!

The ISN system has two APIs one for accessing all of the ISNs and one for access a single ISN after you know the company key. Because you already know the company key you will NOT have to use the Admin API. You can access the API on your ISN directly. Typical usage would be as follows:

  1. First, determine your REST URL (what you are going to call as the ISN API) - it will be your URL plus your company key plus 'rest' (e.g. https://4isn.com/yourcompany/rest, where 4isn.com is your domain and yourcompany is your company key).
  2. Next, determine what you want to do, typically we see users want to pull footprints for upcoming jobs... make sure you visit the ISN api documentation for the different actions the REST API can do.
  3. Using the idea of grabbing footprints for our 'yourcompany' at 4isn.com we would make this GET call to /orders/footprints (read more)
  4. Using the results of that GET call I could make GET calls to /order/{id}, a call to /client/{id} and a call to /agent/{id} to get the order, agent and client information.






Example Usage - Unknown Company Key (Typically a 3rd Party Vendor)

So... you don't know the user's company key or their domain. You have two options:

  1. You can just ask the user for their ISN company key and their ISN domain (we have found this causes more support issues)
  2. You can use the ISN Admin API to get their domain by just asking for their company key - typically users will know their company key but NOT their domain.

The ISN Admin API is another API with a single action and single endpoint to ask what domain the ISN is at. Essentially you are going to ask the ISN Admin API where this ISN lives. You can read more about the Admin API by clicking Admin API above on the menu.

  1. First, ask the user for their company key.
  2. Use the Admin API to determine the URL and REST endpoint for their ISN. The REST endpoing URL is their domain (from the Admin API) plus the company key plus 'rest' (e.g. https://4isn.com/yourcompany/rest, where 4isn.com is your domain and yourcompany is your company key).
  3. Next, determine what you want to do, typically we see users want to pull footprints for upcoming jobs... make sure you visit the ISN api documentation for the different actions the REST API can do.
  4. Using the idea of grabbing footprints for our 'yourcompany' at 4isn.com we would make this GET call to /orders/footprints (read more)
  5. Using the results of that GET call I could make GET calls to /order/{id}, a call to /client/{id} and a call to /agent/{id} to get the order, agent and client information.






Contact

For more information about our development API or working with the ISN please contact us via email, live chat or via phone at (800) 700-8112.