Getting Started

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

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

All API requests require a valid FSI Developer Portal subscription and API Key. The Primary and Secondary access Keys are visible from the Profile page for approved Developer accounts.

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 Integrations 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": []
}