Getting Started

This guide will provide the steps to begin using the FSI Integrations API.

Creating a Developer Account

Follow these steps to create a Developer account and request a Subscription.

  1. If you do not have a registered Developer account yet, please Sign Up as a Developer.

  2. After logging in as a registered Developer, visit the Products page to see our product offering for Standard API Access.

  3. Click on the FSI Standard API Access product link to see its details.

  4. In the Your Subscriptions section, enter a new subscription name and click the Subscribe button to submit a Subscription request for approval.

  5. FSI will be notified of your subscription request, and will promptly review it to confirm your FSI account has Public API Access enabled.

  6. When your Subscription request is approved, you can visit the Profile page to generate and view your access keys.

If you have any difficulties registering or requesting a subscription, please check out the FSI Neighborhood or contact our Customer Support team.

Authentication

A valid access token is required for all requests to the API. To request a token, make a request to the Token API as follows:

Method: POST

Headers:

  • Content-Type: "application/x-www-form-urlencoded"

  • Ocp-Apim-Subscription-Key: <your subscription key>

  • Site: <your customer site code>

Body:

The token request body will contain the username and password for the CMS user you wish to use. Customers often create a specific user for API-only purposes.

The body should be UrlEncoded and formatted as shown below:

grant_type=password&username=jdoe&password=abc123

Response:

If the authentication is successful, a JSON response will be returned containing the Access Token. The token expiration is 7 days.

{
    "access_token": <access-token-in-JWT-format>,
    "expires_in": 604800,
    "token_type": "Bearer",
    "scope": "CMS"
}

Save or capture the Access Token for use on API calls, as described below.

Calling API Endpoints

The FSI Public API follows industry standard REST-style definitions for retrieving or submitting data. Refer to the individual API documentation for details on the operations that each API make available.

All requests, regardless of HTTP Method, must have an Authentication header containing the Access Token value, as well as a Segment ID from CMS.

Here's an example for retrieving an asset record by its AssetID.

Method: GET

Headers:

  • Ocp-Apim-Subscription-Key: <your subscription key>

  • CmsSegmentID: <a valid segment ID>

  • Authorization: Bearer "<access_token>"

Request URL:

  • https://<base-url>/asset/v1/<asset-id>

Response:

{
    "id": "e1145d89-a8d8-4681-85d1-f60b4d48e152",
    "idCustomer": 13,
    "idCustomerSegment": 36,
    "segmentName": "Pittsburgh Facilities",
    "number": "12788",
    "description": "AH1",
    "manufacturerReadOnly": "NA",
    "modelNumberReadOnly": "NA",
    "serialNumber": "NA",
    "idCostCenter": 2121,
    "costCenter": "Z-FACILITIES - ADMIN BUILDING",
    "costCenterHierarchy": ".2121.",
    "costCenterHasChildren": 0,
    "idTrade": 387,
    "trade": "Bettis Zone - Floors 2 - 3",
    "tradeHierarchy": ".387.",
    "tradeHasChildren": 0,
    "idPriority": 59,
    "priority": "MEDIUM",
    "idCmsStatus": 6,
    "idStatus": 234,
    "status": "Active - Warranty",
    "statusHierarchy": ".189.234.",
    "statusHasChildren": 0,
    "idCategory": 38992,
    "category": "D30.50.50 - HVAC - Air Handling - Air Handling Unit - Indoor Unit",
    "categoryHierarchy": ".38456.38728.38992.",
    "categoryHasChildren": 0,
    "idLocation": 4634,
    "location": "Medical Center Off Sites - 1730 Rosemont - 01st Floor",
    "locationHierarchy": ".4319.4349.4634.",
    "locationHasChildren": 0,
    "locationOther": "",
    "notes": "",
    "idUserCreated": "ea744c3a-f08e-4dd3-9464-52bee81515ca",
    "userCreated": "Jacqueline Curtis",
    "dateCreated": "2011-08-04T08:41:28",
    "idUserUpdated": "3531f055-fcc2-4b37-a66b-5a103b2f3f6a",
    "userUpdated": "Mike Miller",
    "dateUpdated": "2021-12-09T18:18:40.42",
    "manufacturerOther": "NA",
    "idCompany": "00000000-0000-0000-0000-000000000000",
    "modelNumber": "NA",
    "idMfgModel": "00000000-0000-0000-0000-000000000000",
    "idClassification": "37",
    "isTool": false,
    "classifications": [
        {
            "id": 55731,
            "idAsset": "e1145d89-a8d8-4681-85d1-f60b4d48e152",
            "idClassification": 37,
            "classification": "HIGH RISK - HVAC",
            "active": true
        }
    ],
    "contacts": []
}