DataConnect - Partner - Common (1.3.1.42)

The endpoints listed here are provided to be used by the iQmetrix Partners.

DataConnect is a web based connector service you can use to extract data from iQmetrix by making simple web data requests. It provides endpoints for common data requirements, various auth mechanisms and other utility endpoints.

Introduction

Usage Information

See Usage section.

Security Protocols

We recommend that users use TLS 1.2 when connecting to DataConnect.

Documentation Errata

We appreciate your patience as we work to improve the documentation for DataConnect. If you have noticed a mistake or have a qustion, please let us know at apisupport [at] iqmetrix [dot] com, subject "Documentation Issue".

Authentication

bearerAuth

Bearer token. See Obtaining an Access Token.

Once authenticated, DataConnect will pass back a session cookie. This cookie should be provided on each subsequent data request to make use of your existing session for performance purposes.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

Usage

Parameters

All DataConnect endpoints have a series of shared URL/Query Parameters that define specific actions based on the data being passed, such as:

  • Response file type
  • Mode of data delivery
  • Preferred language
  • Response encoding options, etc.

See the Universal Query Parameters and Sample Usage section for examples.

HTTP Method

All DataConnect endpoints support the GET and POST method. There is no functionality change for either method, other than using POST allows you to put the parameters in a request body instead. If the same parameter appears in both the request body and in the URL, preference is given to the URL parameter.

See the Universal Request Payload Parameters and Sample Usage section for examples.

Error Responses

Error Code Description
400 Bad Request - An error indicating the request cannot be understood due to missing parameters.
401 Unauthorized - An error indicating failure to provide a valid token.
403 Forbidden - An error indicating insufficient user access privileges.
404 Not Found - An error indicating that the requested resource was not found.
413 Payload Too Large - DataConnect estimates the number of records that will be returned on a request. If greater than 1,048,576 records (Matches row limit for Microsoft Excel) would be returned, the request is blocked.
429 Too Many Requests (Rate limiting has been applied) - This error occurs for two possible reasons: (1) the number of active concurrent requests on a single resource is dynamically calculated to exceed available capacity or (2) a request has a high risk of impacting business critical systems. For more information, see Rate Limiting.
500 Internal Server Error - This error may indicate issues with the API. Please reach out to us with the details of the issue at apisupport [at] iqmetrix [dot] com, subject "Error Report".

Universal Query Parameters and Sample Usage

This endpoint documentation showcases the universal parameters and error responses shared by all DataConnect endpoints. This endpoint exists for documentation purposes only and is therefore non-functional.

query Parameters
Help
boolean
Default: false
Example: Help=true

When Help=True, the endpoint will return only the technical definition of all the query parameters for the requested endpoint. The response also includes details on how the provided parameters are mapped/converted for execution.

RQ
boolean
Default: false
Example: RQ=true

When RQ=True and the endpoint has an equivalent report in RQ, the fields in the returned response will be renamed to the corresponding columns found in the equivalent RQ report.

Encoding
string
Example: Encoding=utf-8

Providing URL parameter Encoding=utf-8 will encode the response in the utf-8 format.

Response
string
Default: "JSON"
Enum: "JSON" "XML" "CSV" "XMLDataTable" "JSONDataTable" "*.Email" "*.FTP" "*.SFTP" "*.FTPS"
Example: Response=JSONDataTable

This parameter dictates the type of returned response and the mode of delivery.

Response Description
JSON Returns the results in JSON format.
XML Returns the results in XML format.
CSV Returns the results in CSV format.
JSONDataTable Returns the results as well as business descriptions of each field in JSON format.
XMLDataTable Returns the results as well as business descriptions of each field in XML format.
*.Email Where * = [Excel, CSV, XML], returns the result in the chosen file type as an email attachment. This email will be sent from the iQmetrix DataConnect Delivery Service (noreply@iqmetrix.net).

Note: The Email.To parameter becomes required.
*.[FTP, SFTP, FTPS] Where * = [Excel, CSV, XML], returns the result in the chosen file type through an FTP/SFTP/FTPS server.

Note: The following parameters becomes required: $.Host, $.Port, $.Username, $.Password, $.Path where $ = [FTP, SFTP, FTPS]
CSV.Delimiter
string
Default: ","
Example: CSV.Delimiter=|

Used if Response=[CSV|CSV.Email]. If the response contains a string that also contains the chosen delimiter, the entire string is escaped in quotes.

CSV.FileExtension
string
Default: "csv"
Example: CSV.FileExtension=csv

Used if Response=[CSV|CSV.Email]. File extension of the returned CSV file.

CSV.Headers
boolean
Default: true
Example: CSV.Headers=true

Used if Response=[CSV|CSV.Email]. A flag to indicate if CSV headers should be included

Email.To
string
Example: Email.To=recipient2@domain.com

Semicolon-delimited list of email recipients

Email.Cc
string
Example: Email.Cc=recipient2@domain.com

Used if Response=[CSV,Excel,XML].Email. Semicolon-delimited list of emails to include as CC

Email.Subject
string
Example: Email.Subject=Test Data

Used if Response=[CSV,Excel,XML].Email. The subject of the email. Defaults to the resource being requested with the current date.

Email.Compress
boolean
Default: false
Example: Email.Compress=false

Used if Response=[CSV,Excel,XML].Email. A flag to indicate if the requested document should be compressed into a zip file (true) or not (false)

Filename
string
Example: Filename=MyReport

Used if Response=[CSV,Excel,XML].Email. Defaults to the resource being requested with today's date

FTP.Host
string
Example: FTP.Host=ftp.domain.com

Required if Response=[Excel,CSV,XML].FTP

FTP.Port
integer
Default: 21
Example: FTP.Port=21

Required if Response=[Excel,CSV,XML].FTP

FTP.Username
string
Example: FTP.Username=Username

Required if Response=[Excel,CSV,XML].FTP.

FTP.Password
string
Example: FTP.Password=Password

Required if Response=[Excel,CSV,XML].FTP.

FTP.Path
string
Default: "/"
Example: FTP.Path=/upload/

Required if Response=[Excel,CSV,XML].FTP.

SFTP.Host
string
Example: SFTP.Host=sftp.domain.com

Required if Response=[Excel,CSV,XML].SFTP.

SFTP.Port
integer
Default: 22
Example: SFTP.Port=22

Required if Response=[Excel,CSV,XML].SFTP

SFTP.Username
string
Example: SFTP.Username=Username

Required if Response=[Excel,CSV,XML].SFTP.

SFTP.Password
string
Example: SFTP.Password=Password

Required if Response=[Excel,CSV,XML].SFTP.

SFTP.Path
string
Default: "/"
Example: SFTP.Path=/upload/

Required if Response=[Excel,CSV,XML].SFTP.

FTPS.Host
string
Example: FTPS.Host=ftps.domain.com

Required if Response=[Excel,CSV,XML].FTPS

FTPS.Port
integer
Example: FTPS.Port=990

Required if Response=[Excel,CSV,XML].FTPS

FTPS.Username
string
Example: FTPS.Username=Username

Required if Response=[Excel,CSV,XML].FTPS

FTPS.Password
string
Example: FTPS.Password=Password

Required if Response=[Excel,CSV,XML].FTPS

FTPS.Path
string
Default: "/"
Example: FTPS.Path=/upload/

Required if Response=[Excel,CSV,XML].FTPS

header Parameters
Accept-Encoding
string
Enum: "gzip" "deflate"
Example: gzip

Compression algorithms are supported for gzip and deflate in the Accept-Encoding header.

Responses

Response samples

Content type
application/json
{