The OMX API accepts queries using a two-phase approach: the authentication handshake and then the actual query itself. In either scenario, the system is queried with a version number, an endpoint (which defines the type of information requested) and a payload containing input parameters (sent by POST), and then returns a resultset.
The URL structure for querying the OMX API is as follows:
https://theomx.com/api/1.0/authenticate
"1.0" represents the version number, and "authenticate" represents the endpoint. All versions and endpoints will be documented here.
- /v3.0/endpoints * Latest
- /v2.0/endpoints * Retired
- /v1.0/endpoints * Retired
The OMX API is queried with a key:
{
"api_key": "ABC123"
}
The returned data provides the input parameters which were queried, plus a resultset (in this case a session token), plus any warnings and/or errors:
{
"datetime": "2022-05-04T17:14:37.399-04:00",
"format": "json",
"result": {
"expires_on": "2022-05-04T18:14:37.379-04:00",
"token": "DEF456"
},
"errors": [
{
"code": "0001",
"message": "Incorrect or Unauthorized key"
},
{
"code": "0007",
"message": "Expired API Key; please contact OMX team"
}
],
"warnings": [
{
"code": "0006",
"message": "Found unknown input parameters in the request: foo"
},
{
"code": "0004",
"message": "No page number specified, so defaulted to 1"
}
]
}
Note that this result set is solely illustrative; a token would never be provided if there were errors, only warnings.
Tokens should expire within one hour of issue.
The token provided in the authentication phase is used as an input parameter to authenticate phase two: the actual data query. The result set will look something like this:
{
"datetime": "2022-05-05T12:48:55.683-04:00",
"format": "json",
"token": "DEF456",
"token_expires_on": "2022-05-04T18:14:37.379-04:00",
"page_requested": 1,
"total_pages": 14,
"page_size": 100,
"result": [
]
"errors": [
]
"warnings":[
]
}
Again, this simple result set is solely illustrative; there is no need for empty key-value pairs.
Note that if the user has selected CSV as the desired output format, nested fields will simply be concatenated.
Access to the API is determined by your organization's plan. Some plans will receive truncated resultsets and some robust resultsets. All resultsets will be rate limited to prevent abuse. It is strongly recommended that systems which connect with the OMX API do not do so in user real-time. A safer architecture is to download data from OMX asynchronously and store locally for better real-time performance and no redundant data retrieval.
| Code | Message | Endpoints |
| 0001 | Incorrect key | authenticate |
| 0002 | Incorrect token | organizations |
| 0003 | Expired token; please reauthenticate using your API key | authenticate, organizations |
| 0004 | The version of the API is now retired; please update your queries to resume accessing the API. | authenticate, organizations |
| 0005 | Daily query cap exceeded; please review documentation on connecting asynchronously to avoid exceeding limits. | authenticate, organizations |
| Code | Message | Endpoints |
| 0001 | API version deprecated and approaching retirement; please upgrade to the latest version | authenticate, organizations |
| 0002 | Daily query cap imminent; please review documentation on connecting asynchronously to avoid exceeding limits. | authenticate, organizations |
| 0003 | No output format specified, so defaulted to JSON | authenticate, organizations |
| 0004 | No page number specified, so defaulted to 1 | organizations |
| 0005 | This is a truncated resultset, so not all data has been provided for all fields. Please upgrade your account to receive the full resultset. | organizations |
| 0006 | Invalid input parameter received | authenticate, organizations |
Although every effort has been made to ensure that this documentation accurately reflects the operation of the API, please advise us if you discover any discrepancies.