Order Management API
Place, amend, delete and retrieve orders, retrieve trades, and read the accounts and portfolios behind them.
At a glance
| Scope | oms-api |
| Test | https://test-oms-api.openmarkets.com.au/ |
| Production | https://oms-api.openmarkets.com.au/ |
| Version | 1.0.0 |
The streaming hub is a separate service on its own base URL and its own scope. See OMS streaming.
Base URLs are per API. The OMS host does not serve the Market Data, News or back office APIs, and a token issued for one scope will not authorise another. If you have been given a dedicated sandbox, the correct URL is provided to you as part of onboarding.
What's in it
| Area | Purpose |
|---|---|
| Orders | Retrieve, create, amend and delete orders. |
| Trades | Retrieve trades, including fills against your orders. |
| Accounts | Retrieve accounts and their portfolio links. |
| Portfolios | Retrieve portfolios. |
| Sessions | Session management, including resetting application access. |
| Tasks | Retrieve the status of daily tasks, such as the cash update. |
Getting started
Request a token with the oms-api scope, then list the accounts you can trade on:
curl 'https://test-oms-api.openmarkets.com.au/accounts/v1' \
-H 'Authorization: Bearer {access_token}'
Pass includeInactive=true to return inactive accounts alongside active ones.
Tokens come from the identity service, which is shared by every Openmarkets API:
| Environment | Token endpoint |
|---|---|
| Test | https://stage-identity.openmarkets.com.au/connect/token |
| Production | https://identity.openmarkets.com.au/connect/token |
See Authentication for the full flow.
Order creation is subject to vetting rules. A successful response does not guarantee the order reached the market, so check orderState and stateDescription. See OMS errors.
Conventions
All API access is sent and received as JSON, and must be requested over HTTPS. Every endpoint requires a bearer token.
Blank and null fields are omitted from requests. JSON request and response bodies use camelCase, except authorisation and authentication requests, which use snake_case to follow the OAuth2 and OpenID Connect specifications.
Parameters
| Method | Where parameters go |
|---|---|
GET, DELETE | Parameters are part of the URL path or query string parameters. Each endpoint's reference states which parameters are required. |
GET (large parameter sets) | Endpoints that retrieve resources but take many optional parameters accept a POST instead, to avoid URL length limits. |
POST, PUT | Parameters that are not part of the URL are JSON encoded in the request body. |
Dates and times
Date-time values in responses have no UTC offset. Each field's description states whether it is exchange time or GMT:
{
"dateTimeFieldName": "2016-12-19T16:30:00"
}
Where a time component is not relevant, the value is returned at midnight:
{
"dateFieldName": "2016-12-19T00:00:00"
}
Plain dates should be used literally, without any timezone conversion. Converting them can shift the date by a day.
Update subscriptions
Endpoints with an /updates/ form are polled with an X-Request-ID header that identifies your subscription. Call the matching endpoint with the Updates header set to true first, then poll the updates form with the same X-Request-ID. The codes returned when that header is wrong are listed under Request tracking errors.
Rather than polling, you can subscribe to order, trade, portfolio position and cash detail updates over SignalR.
Rate limits and availability
Requests are rate limited per client and per endpoint. Throttled requests return HTTP 429 with one of ApiCallsFrequencyExceeded, ActiveApiCallsExceeded or MaxUpdatesQueuedExceeded. See Errors.
Cache your access token for its full expires_in lifetime. Requesting a token per API call is the most common cause of unexpected throttling. Implement a circuit breaker with increasing delay between retries rather than retrying immediately.
This API is briefly unavailable on a regular maintenance schedule. See Known issues.
Trading reference
Exchange session behaviour affects when orders are accepted and how they are priced.
