{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"83efc840-5077-47b3-9f02-3f07280f70aa","name":"QTS API Guide","description":"This package is licensed under the BSD 3-Clause License  \nCopyright (c) 2021, Quality Technology Services (QTS), LLC  \nAll rights reserved.\n\nIn addition, QTS has published its RESTful API definitions as Open Source under the same BSD3 License. You can find it at this link: [https://developers.qtsdatacenters.com](https://developers.qtsdatacenters.com).\n\n# Overview\n\nQTS exposes its SDP (Service Delivery Platform) functionality via RESTful APIs.\n\nThis documentation is for developers wishing to automate the provisioning and management of their QTS resources, including User Management (Roster), Physical Security, Power, Asset Manager, and Online Ordering. It provides an overall picture of the REST API interface along with details to develop application integration code.\n\nTo work with SDP RESTful APIs, you can use any browser or client application that supports HTTP and HTTPS protocols. This documentation and API collections are in Postman. Each API method includes a description of the functionality as well as an example output.\n\n# Creating an API User\n\nTo create an API user, you must have the admin role. If you do not have the admin role, please contact your SDP Admin to assign that role to you.\n\n1. Log on to SDP ([https://sdp.qtsdatacenters.com/](https://sdp.qtsdatacenters.com/)) using the user name and password provided to you by the QTS Implementation Team\n    \n2. In the Hamburger menu (upper righthand corner), click “User Management”\n    \n3. Click the USERS tab\n    \n4. Click \"Create New User\" (red box in upper right under the banner)\n    \n5. Enter User Name for your API user\n    \n6. In USER TYPE drop down, select \"API System User\"\n    \n7. Enter PASSWORD for API user. The password must have at least 8 characters, at least one number, at least one special character, and at least one lower and upper case alpha character.\n    \n8. Enter same PASSWORD again in the CONFIRM PASSWORD field\n    \n9. Select appropriate role(s) for API user (Note: each section heading of this API documentation tells what role is needed to make the API calls in that section)\n    \n10. Click \"Service Desk Access\" if and only if your API user should be permitted to make Service Desk requests\n    \n11. Click on Save (red button in upper right)  \n    A popup appears confirming that your API user has been created, and allowing you to View API key pair or Download API key pair.  \n    IMPORTANT: You MUST do one of those actions; either view the key pair and copy them or download them. The key pair will contain values for API Access Key and API Secret Key  \n    If you miss this step or misplace your key pair, you can regenerate a new key pair.\n    \n12. Save the API key pair per your company's security policies\n    \n\nYou now have the four parameter values needed to make the API POST method Get Access Token call /sdp/api/token/access. In the body of the Get Access Token call, you will provide the following for the API user you just created:\n\n1. username\n    \n2. password\n    \n3. api_access_key\n    \n4. api_secret_key\n    \n\nThe documentation on the Get Access Token call is in the API Authentication folder.\n\n# API Support\n\nFor questions or support on QTS APIs, please contact QTS Support via the following email address:\n\n[support@qtsdatacenters.com](https://mailto:support@qtsdatacenters.com)\n\n# API Requests and Version Control\n\nQTS API URLs use the following naming convention which includes the version: [https://api.qtsdatacenters.com/sdp/api/{modulename}/v1/{resourcePath}](https://api.qtsdatacenters.com/sdp/api/%7Bmodulename%7D/v1/%7BresourcePath%7D)\n\nFor example, in order to list user's environments, use the following URL: [https://api.qtsdatacenters.com/sdp/api/roster/v1/user/envusers](https://api.qtsdatacenters.com/sdp/api/roster/v1/user/envusers)\n\nThe version of the RESTful API is noted in the URL. Version 2 (v2) of User Management APIs released on July 2, 2019.\n\nQTS will up-version API based on major changes including:\n\n- introduction of new functionality within SDP\n    \n- a change in the format of the response\n    \n- a change in the response/data type\n    \n- removing any part of the API\n    \n\n# Common API Responses\n\nAPIs use standard HTTP status codes to indicate the general result of a request. Every response from the API will have one of the following status codes in the header:\n\n| HTTP Code | Reason | Description |\n| --- | --- | --- |\n| 200 OK |  | Success. Indicates that the request was valid and the transaction executed normally. |\n| 201 Created |  | Indicates that a new resource was created. 201 Created is not used when a resource is updated. |\n| 400 Bad Request | INVALID_INPUT_DATA | Indicates that the JSON posted with the request contained bad syntax or was missing required fields. |\n| 401 Unauthorized | AUTHORIZATION_FAILURE | Indicates invalid credentials were provided for authentication. |\n| 403 Forbidden | FORBIDDEN | Indicates that the credentials provided for authentication were valid but the user is not permitted to access the resource. |\n| 404 Not Found | RESOURCE_NOT_FOUND | Indicates that there is no resource at the URI specified in the request. |\n| 405 Method Not Allowed |  | Indicates the URL is valid but operation is not supported or not allowed for the resource. |\n| 408 Request timeout |  | Indicates the request response was not received during expected amount of time. |\n| 500 Internal Server Error | UNEXPECTED_ERROR | Indicates that a general error has occurred with the request that is not described by another status code. |\n| 503 Service Unavailable |  | System is down for scheduled maintenance.This response remains in place for the duration of the scheduled maintenance window. |\n| 400 Bad Request | INVALID_INPUT_DATA | Indicates input data does not correspond to validation rules or mandatory fields were missed. |\n\n# Paging, Filtering and Sorting\n\nPaging is the act of splitting a large list of results into consumable chunks as a means of improving performance and general manageability.\n\n- Paging operators are separated with & symbol\n    \n- Paging operators are case sensitive\n    \n\nThe following operators are supported:\n\n- pageNumber - specify number of pages\n    \n- pageSize - number of records per page\n    \n\n**Example:** /sdp/ticketing/v1/api/temporary_visitor_reservations?pageNumber=1&pageSize=20\n\n## Optional Paging Parameters\n\n| Parameter | Usage | Example |\n| --- | --- | --- |\n| pageSize | Optional. May only be specified once. Must be a positive integer between 1 and a maximum value documented for each API function. | pageSize=50 Return 50 records per page |\n| pageNumber | Optional. May only be specified once. Must be a positive integer. If the value supplied exceeds the number of pages for the request, the last page will be returned. | pageNumber=3 Returns the 3rd page. If pageSize is 50, then return records 101-through-150. |\n\nJSON response elements when using paging parameters:\n\n| Attribute Name | Attribute Details | Description |\n| --- | --- | --- |\n| pageCount | Non-negative Integer | The number of result records in this page. |\n| pageNumber | Non-negative Integer | The page number requested by the user or the default page (1) if none supplied. |\n| pageSize | Non-negative Integer | The page size used; either specified in the request or the default for the API function being requested, max value 10000. |\n| totalCount | Non-negative Integer | The total number of result records matching request criteria |\n\n**Example result:**  \n{  \n\"pageInfo\": {  \n\"pageSize\": 20,  \n\"totalCount\": 115,  \n\"totalPages\": 6,  \n\"pageNumber\": 1  \n},\n\n## Filtering and Sorting\n\nUse _sorting_ to present results in a specified order.\n\n- Sort keyword specifies the parameter results should be sorted.\n    \n- Name of request parameter must be specified to identify how results should be sorted\n    \n- Sorting operators:\n    \n    - ASC\n        \n    - DESC\n        \n- Sorting operator and keywords are case sensitive\n    \n\n**Example:** /sdp/ticketing/v1/api/temporary_visitor_reservations?sort=location.ASC\n\nUse _filtering_ to reduce size of list by applying request criteria to narrow the matched set of results.\n\nThe following general rules apply across all APIs developed with the paging and filtering approach:\n\n- Every GET method has its own set of filter parameters documented\n    \n- Parameter names and some parameter values are based on keywords and field names, which will be published in the API documentation\n    \n- Field names are case sensitive\n    \n- The set of field names and filters for a given API function can be enhanced over time with the publication of new values\n    \n- Multiple filtering operators are separated with & symbol\n    \n- Dates are defined in XSD format but can be passed in full (including time) or short (date  \n    only) format. For example; \"20180901T00:00:00Z\" and \"2018-09-01\" equate to the same  \n    value and time zone.\n    \n- Both EQUALS (single value) and IN (multiple value) queries are supported\n    \n- The filter component has the following format: `?_s=field==value` where the filter criteria are specified as _field=value_ pairs.\n    \n\n| Logical Operators | Syntax | Description |\n| --- | --- | --- |\n| AND | ;(Semicolon) | All conditions in the filter parameter must be true. Example:`?_s=firstName==john;lastName==lee` Returns Roster Users with first name as \"john\" AND last name as \"lee\" |\n| OR | ,(Comma) | Any of the conditions specified in the filter parameter must be true. Example: `?_s=firstName==john,lastName==lee` Returns Roster Users with first name as ‘john’ OR last name as ‘lee’ |\n\n| Comparison Operators | Syntax | Description |\n| --- | --- | --- |\n| EQUAL | \\== | The result must be equal to the value specified in the _field=value_ pair. Example: `?_s=username==john.test` Returns only Roster Users that have ‘john.test’ as username |\n| NOT EQUAL | != | The result must not be equal to the value specified in the _field=value_ pair. Example: `?_s=username!=john.test` Returns only Roster Users that do not have ‘john.test’ as username |\n| GREATER THAN | gt | The result must be greater than the value specified in the _field=value_ pair.`?_s=dateCreation=gt=2018-09-01` Returns only records created after 1st of September 1, 2018 |\n| LESS THAN | lt | The result must be less than the value specified in the _field=value_ pair.`?_s=dateCreation=lt=2018-09-01` Returns only records created before 1st of September 1, 2018 |\n\n| Additional Operators | Syntax | Description |\n| --- | --- | --- |\n| Wildcard | \\* | The “\\*” wildcard character (asterisks) can be used to match zero or more characters. Each API supporting wildcard states that it supports wildcard within its own definition. |\n| STARTS WITH | \\== | Example: `?_s=username==john` Returns only Roster Users that has username starts with \"john\" |\n| ENDS WITH | \\==\\* | Example: `?_s=username==\\\\\\\\\\*john` Returns only Roster Users where username ends with \"john\" |\n| CONTAINS | \\==\\*value\\* | Example: `?_s=username==\\\\\\\\\\*john\\\\\\\\\\*` Returns only Roster Users that has \"john\" in username |\n| ORDER BY | orderBy=value | `?orderBy=username` Results would be sorted by username, ascending order by default |\n| PAGING PARAMETERS | pageNumber=value;pageSize=value | `?pageNumber=2;pageSize=10` Returns only second page, 10 results per page |\n\n## Sample Formatting Requests\n\n| Request | Response |\n| --- | --- |\n| /sdp/api/roster/v1/users | Lists 100 Users that are available for the current requester, sorted by username |\n| /sdp/api/power/v1/raw_data?site=DFW1&format=json& _s=period==monthly;date==10-01-2018 | Generates JSON raw power data report for monthly period October 2018. Report contains all circuits and poles of DFW1 site including kW readings for poles of specified location circuits |\n| /sdp/api/power/v1/power_demand?site=DFW1&_s=date==12-01-2018;period==weekly;site=DFW1 | Generates .xlsx report for week starting December 1, 2018 for DFW1 site |\n| /sdp/api/roster/v1/users?pageNumber=2;pageSize=100;orderBy=date | Indicates a page size of 100 and requests the second page of results being page 101 to 200 inclusive, ordered by date of deployment ascending (default) |\n\n## Paging and Filtering Common API Responses\n\n| HTTP Code | Reason | Description |\n| --- | --- | --- |\n| 400 (Error) | INCORRECT_PAGING_PARAMETER | A supplied value for any paging parameter is outside of accepted value set. A negative or non-numeric pageSize or pageNumber, pageSize too large, an invalid orderBy value or more than one value was supplied for a given paging parameter. |\n| 400 (Error) | INVALID_FILTER_VALUE | A filter was specified with an invalid value. Returned if an invalid comparative operator is used with a filter field. For example, MIN and MAX will typically not be allowed with String fields. |\n| 400 (Error) | UNSUPPORTED_PARAMETER | Invalid comparative operator |\n| 400 (Error) | INVALID_INPUT_DATA | Not a comparison expression. Returned in case any filtering or sorting parameter was missed or extra symbols added to the filter line. |\n| 400 (Error) | TOO_MANY_FILTER_PARAMETERS | Exceeded maximum supported number of filter operators. Maximum number of filter operators is 10. Returned if more than 10 values for a filter line were supplied. |","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"15946512","collectionId":"83efc840-5077-47b3-9f02-3f07280f70aa","publishedId":"2s93JzKfZa","public":true,"publicUrl":"https://docs.qtsdatacenters.com","privateUrl":"https://go.postman.co/documentation/15946512-83efc840-5077-47b3-9f02-3f07280f70aa","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.1","publishDate":"2023-03-17T20:07:22.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":"https://qtsdatacenters.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://docs.qtsdatacenters.com/view/metadata/2s93JzKfZa"}