Users


GET users

Description

Get the details for all users visible by the requester, sorted ascending by first name.

Resource URL

https://api.optionscity.com/users
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object User
Response Type Standard

Parameters

NameDescriptionRequired?Type
page 1-indexed page to retrieve. Default is 1. No Number
per_page Number of entries returned per page. Default is 20. No Number
email Get the user registered with this email address. No String
is_active If true, gets only active users; if false, gets only inactive users. No Boolean
user_type Gets only users of the indicated type(Customer, OrgAdmin, SuperUser) No String
query Search for users matching this query by name or email address. No String

Example Request

GET https://api.optionscity.com/users

Example Response

[ {
  "email" : "first.last@example.com",
  "first_name" : "Doug",
  "last_name" : "Kurth",
  "user_type" : "Customer",
  "trading_capacity" : 1,
  "liquidity_provision" : 1,
  "commodity_deriv_indicator" : 0,
  "investment_decision" : 2345,
  "execution_decision" : 6789,
  "trader_id" : "5678",
  "is_professional" : false,
  "id" : 12345,
  "is_active" : false
} ]

GET users/:id

Description

Get the details for the specified user.

Resource URL

https://api.optionscity.com/users/:id
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object User
Response Type Standard

Parameters

NameDescriptionRequired?Type
id The user's City API assigned ID. Yes String

Example Request

GET https://api.optionscity.com/users/12345

Example Response

{
  "email" : "first.last@example.com",
  "first_name" : "Doug",
  "last_name" : "Kurth",
  "user_type" : "Customer",
  "trading_capacity" : 1,
  "liquidity_provision" : 1,
  "commodity_deriv_indicator" : 0,
  "investment_decision" : 2345,
  "execution_decision" : 6789,
  "trader_id" : "5678",
  "is_professional" : false,
  "id" : 12345,
  "is_active" : false
}

GET users/me

Description

Get the details for the user making the request.

Resource URL

https://api.optionscity.com/users/me
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object User
Response Type Standard

Example Request

GET https://api.optionscity.com/users/me

Example Response

{
  "email" : "first.last@example.com",
  "first_name" : "Doug",
  "last_name" : "Kurth",
  "user_type" : "Customer",
  "trading_capacity" : 1,
  "liquidity_provision" : 1,
  "commodity_deriv_indicator" : 0,
  "investment_decision" : 2345,
  "execution_decision" : 6789,
  "trader_id" : "5678",
  "is_professional" : false,
  "id" : 12345,
  "is_active" : false
}

DELETE users/:id

Description

Delete a user.

Resource URL

https://api.optionscity.com/users/:id
Authentication Required
HTTP Methods DELETE
Media Types --
Response Object None
Response Type Standard

Parameters

NameDescriptionRequired?Type
id The user ID for the user to delete. Yes Number

Example Request

DELETE https://api.optionscity.com/users/1

GET users/:id/resetpasswordlink

Description

Get the details for the specified user.

Resource URL

https://api.optionscity.com/users/:id/resetpasswordlink
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object ResetPasswordLink
Response Type Standard

Parameters

NameDescriptionRequired?Type
id The user's City API assigned ID. Yes String

Example Request

GET https://api.optionscity.com/users/12345/resetpasswordlink

Example Response

{
  "link" : "https://api.optionscity.com/setpassword?code=6044f6b1-665a-49fb-a44c-33cbd6f6be69"
}

GET users/me/permissions

Description

Get the permissions for the user making the request.

Resource URL

https://api.optionscity.com/users/me
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object RolePermissions
Response Type Standard

Example Request

GET https://api.optionscity.com/users/me/permissions

Example Response

[ {
  "resource" : "OrganizationResource",
  "access" : "NoAccess",
  "description" : "All organization settings (e.g. name, customer redirect URL)."
}, {
  "resource" : "AccountResource",
  "access" : "ReadAccess",
  "description" : "Basic account information for all accounts in scope (belonging to an organization or shared with another organization via a trading group). This includes the account name, GMI #'s, etc.  Notably, it does not include risk limits."
} ]

GET users/:id/accounts

Description

Get all accounts accessible to the specified user.

Resource URL

https://api.optionscity.com/users/:id/accounts
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object Account
Response Type Standard

Parameters

NameDescriptionRequired?Type
id The user's City API assigned ID. Yes String

Example Request

GET https://api.optionscity.com/users/:id/accounts

Example Response

[ {
  "name" : "Doug's Account",
  "tag_1" : "12380",
  "clearing_acct_no" : "12380",
  "gmi_office_num" : "123",
  "gmi_acct_num" : "80",
  "org_name" : "Some Organization",
  "clearing_src_id" : 3,
  "clearing_src_name" : "Some Trading Group",
  "id" : 1,
  "trading_enabled" : true,
  "tally_positions" : true,
  "buying_power_margin_percent" : 100,
  "last_sync_date" : "2018-05-24",
  "net_liq" : 12345,
  "net_position_limit" : 100,
  "cti_code" : "4",
  "cash_balance" : 10000,
  "enforce_margin" : false,
  "margin_req" : 2500,
  "margin_status" : "Success",
  "profit_and_loss" : 750,
  "customer_or_firm" : 1,
  "long_us_treasuries" : 25000
} ]

POST users/new (will eventually be changed to 'POST users')

Description

Create a new user. ID, password and computed/read-only fields should be left blank (e.g. 'created_at'). Users can optionally have a link emailed to them to set their password. See the user object documentation for full details.

Resource URL

https://api.optionscity.com/users/:id
Authentication Required
HTTP Methods POST
Media Types application/json
Response Object User
Response Type Standard
Request Object User

Parameters

NameDescriptionRequired?Type
invite Whether an invitation email should be sent to the user requesting that they set their password. Default is 'false'. No Boolean

Example Request

POST https://api.optionscity.com/users
{
  "email" : "first.last@example.com",
  "first_name" : "Doug",
  "last_name" : "Kurth",
  "address" : {
    "line_1" : "200 W Adams",
    "line_2" : "Suite 1015",
    "city" : "Chicago",
    "state" : "IL",
    "zip" : "60601",
    "country" : "US"
  },
  "user_type" : "Customer",
  "org_id" : 1,
  "deactivate_on" : "2016-11-15T00:00:00.000Z",
  "client_id_code" : 1234,
  "trading_capacity" : 2,
  "liquidity_provision" : 0,
  "commodity_deriv_indicator" : 0,
  "investment_decision" : 333485,
  "is_professional" : false
}

Example Response

{
  "email" : "first.last@example.com",
  "first_name" : "Doug",
  "last_name" : "Kurth",
  "address" : {
    "line_1" : "200 W Adams",
    "line_2" : "Suite 1015",
    "city" : "Chicago",
    "state" : "IL",
    "zip" : "60601",
    "country" : "US"
  },
  "user_type" : "Customer",
  "org_id" : 1,
  "deactivate_on" : "2016-11-15T00:00:00.000Z",
  "client_id_code" : 1234,
  "trading_capacity" : 2,
  "liquidity_provision" : 0,
  "commodity_deriv_indicator" : 0,
  "investment_decision" : 333485,
  "is_professional" : false
}

PUT users/:id

Description

Update a user's data. Cannot be used to set a user's password and computed/read-only fields should be left blank (e.g. 'created_at'). See the user object documentation for full details.

Resource URL

https://api.optionscity.com/users/:id
Authentication Required
HTTP Methods PUT
Media Types application/json
Response Object User
Response Type Standard
Request Object User

Example Request

PUT https://api.optionscity.com/users/12345
{
  "email" : "first.last@example.com",
  "first_name" : "Doug",
  "last_name" : "Kurth",
  "address" : {
    "line_1" : "200 W Adams",
    "line_2" : "Suite 1015",
    "city" : "Chicago",
    "state" : "IL",
    "zip" : "60601",
    "country" : "US"
  },
  "user_type" : "Customer",
  "org_id" : 1,
  "deactivate_on" : "2016-11-15T00:00:00.000Z",
  "client_id_code" : 1234,
  "trading_capacity" : 2,
  "liquidity_provision" : 0,
  "commodity_deriv_indicator" : 0,
  "investment_decision" : 333485,
  "is_professional" : false
}

Example Response

{
  "email" : "first.last@example.com",
  "first_name" : "Doug",
  "last_name" : "Kurth",
  "address" : {
    "line_1" : "200 W Adams",
    "line_2" : "Suite 1015",
    "city" : "Chicago",
    "state" : "IL",
    "zip" : "60601",
    "country" : "US"
  },
  "user_type" : "Customer",
  "org_id" : 1,
  "deactivate_on" : "2016-11-15T00:00:00.000Z",
  "client_id_code" : 1234,
  "trading_capacity" : 2,
  "liquidity_provision" : 0,
  "commodity_deriv_indicator" : 0,
  "investment_decision" : 333485,
  "is_professional" : false
}

POST users/signup

Description

Add a new customer with login credentials to your organization. Note that HTTP basic authentication with your OAuth client ID and secret should be used for this request.

Resource URL

https://api.optionscity.com/users/signup
Authentication Required
HTTP Methods POST
Media Types application/json
Response Object Token
Response Type Standard
Request Object New User

Example Request

POST https://api.optionscity.com/users/signup
{
  "email" : "first.last@example.com",
  "first_name" : "Doug",
  "last_name" : "Kurth",
  "address" : {
    "line_1" : "200 W Adams",
    "line_2" : "Suite 1015",
    "city" : "Chicago",
    "state" : "IL",
    "zip" : "60601",
    "country" : "US"
  },
  "user_type" : "Customer",
  "org_id" : 1,
  "client_id_code" : 12345,
  "trading_capacity" : 1,
  "liquidity_provision" : 1,
  "investment_decision" : 2345,
  "execution_decision" : 4567,
  "trader_id" : "667788",
  "is_professional" : false,
  "password" : "password"
}

Example Response

{
  "access_token" : "2YotnFZFEjr1zCsicMWpAA",
  "token_type" : "bearer",
  "expires_in" : 1209600,
  "refresh_token" : "tGzv3JOkF0XG5Qx2TlKWIA"
}

GET usermdaccess

Description

Gets current market data access specifications for one or more users.

Resource URL

https://api.optionscity.com/users/mdaccess
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object See example
Response Type Standard

Parameters

NameDescriptionRequired?Type
user_id The specific user ID to retrieve records for. If not used, will retrieve records for all users the requester has access to. No Number
page 1-indexed page to retrieve. Default is 1. No Number
per_page Number of entries returned per page. Default is 100. No Number

Example Request

GET https://api.optionscity.com/usermdaccess?user_id=34

Example Response

[ {
  "id" : 173,
  "user_id" : 34,
  "group_name" : "CME",
  "real_time" : true,
  "depth_access" : true
}, {
  "id" : 174,
  "user_id" : 34,
  "group_name" : "ICE",
  "real_time" : false,
  "depth_access" : true
} ]

GET usermdaccess/:id

Description

Gets a particular market data access specification.

Resource URL

https://api.optionscity.com/mdaccess/:id
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object See example
Response Type Standard

Example Request

GET https://api.optionscity.com/usermdaccess/174

Example Response

[ {
  "id" : 174,
  "user_id" : 34,
  "group_name" : "ICE",
  "real_time" : false,
  "depth_access" : true
} ]

POST usermdaccess

Description

Adds a new market data access specification. If you try to POST a user_id and group_name that already have an existing market data access specification, an error will be returned. In that case, you should do a PUT to update the existing specification.

Resource URL

https://api.optionscity.com/usermdaccess
Authentication Required
HTTP Methods POST
Media Types application/json
Response Object See example
Response Type Standard
Request Object See example

Example Request

POST https://api.optionscity.com/usermdaccess
[ {
  "user_id" : 34,
  "group_name" : "NYMEX",
  "real_time" : true,
  "depth_access" : true
} ]

Example Response

[ {
  "id" : 175,
  "user_id" : 34,
  "group_name" : "NYMEX",
  "real_time" : true,
  "depth_access" : true
} ]

PUT usermdaccess/:id

Description

Updates a particular market data access specification.

Resource URL

https://api.optionscity.com/usermdaccess/:id
Authentication Required
HTTP Methods PUT
Media Types application/json
Response Object See example
Response Type Standard
Request Object See example

Example Request

PUT https://api.optionscity.com/usermdaccess/175
[ {
  "id" : 175,
  "user_id" : 34,
  "group_name" : "NYMEX",
  "real_time" : false,
  "depth_access" : true
} ]

Example Response

[ {
  "id" : 175,
  "user_id" : 34,
  "group_name" : "NYMEX",
  "real_time" : false,
  "depth_access" : true
} ]

DELETE usermdaccess/:id

Description

Removes a particular market data access specification.

Resource URL

https://api.optionscity.com/usermdaccess/:id
Authentication Required
HTTP Methods DELETE
Media Types --
Response Object None
Response Type Standard

Example Request

DELETE https://api.optionscity.com/usermdaccess/175

POST users/resetpassword

Description

Reset the password for the specified user and email them instructions. Organizations can choose to send their own reset password email, or have City API send one on their behalf. This is controlled via the 'Set Password Webhook URL' under your organization settings. If this URL is set, a code and email address are posted to the URL as JSON in the following form: { "code": , "email":

}.Once a password is collected from the user, the code and password can be posted back to City API at https://api.optionscity.com/password. If no URL is provided for the organization, the user will receive an email directly from City API and City API will handle securely resetting the password. Note that HTTP basic authentication with your OAuth client ID and secret should be used for this request.

Resource URL

https://api.optionscity.com/users/resetpassword
Authentication Optional
HTTP Methods POST
Media Types application/json
Response Object None
Response Type Standard
Request Object Email Address

Parameters

NameDescriptionRequired?Type
email The email address of the user who would like their password reset. Yes String

Example Request

POST https://api.optionscity.com/users/resetpassword
{
  "email" : "first.last@example.com"
}

POST users/password

Description

Sets the password for the user associated with the specified temporary code. This API can be used by organizations to control their own customer sign-up and reset password workflows. If a customer is added, or their password reset (via the 'POST users/resetpassword' or 'POST users' end-points, for example), and the 'set password' webhook is set under organization settings, a temporary code will be posted to the URL. That code and the user's chosen password may then be posted back to this end-point to set the password. It is the organization's responsibility to securely obtain the password and post it back to City API. Note that HTTP basic authentication with your OAuth client ID and secret should be used for this request.

Resource URL

https://api.optionscity.com/users/password
Authentication Optional
HTTP Methods POST
Media Types application/json
Response Object None
Response Type Standard
Request Object Password Info

Parameters

NameDescriptionRequired?Type
code The temporary code provided by City API via the 'set password' webhook. Yes String
password The user's chosen password. Yes String

Example Request

POST https://api.optionscity.com/users/password
{
  "code" : "d1b4b94e-91c7-417b-96e5-48f5567c363c",
  "password" : "a_password"
}

User Object

Description

A direct user of the system. Could be an organization employee or customer.

Fields

Field Type Optional Subtypes Description
id Number No All Identifier assigned by City API. Not required/used in POST and PUT requests.
email String No All User's email address (e.g. first.last@example.com).
first_name String No All User's first name.
last_name String No All User's last name.
address String Yes All User's primary mailing address. Required for market data access. Country code must be two characters.
eurex_username String Yes All User's EUREX username, if any.
eurex_password String Yes All User's EUREX password, if any.
nordic_username String Yes All User's NORDIC username, if any.
nordic_password String Yes All User's NORDIC password, if any.
client_id_code Number Yes All User's client id code, as needed by MiFID II regulations
trading_capacity Number Yes All User's trading capacity, as needed by MiFID II regulations. Allowed values are 0 = DEAL (own account) 1 = MTCH (matched principal) 2 = AOTC (any other capacity)
liquidity_provision Number Yes All User's liquidity provision, as needed by MiFID II regulations
commodity_deriv_indicator Number Yes All User's commodity derivative indicator, as needed by MiFID II regulations
investment_decision Number Yes All User's default investment decision, as needed by MiFID II regulations
execution_decision Number Yes All User's execution decision, as needed by MiFID II regulations
mifid_id Number Yes All User's Mifid Id for ICEEU/LIFFE products that takes precedence over non-short code MiFID fields
trader_id String Yes All User's Trader Id, as needed by MiFID II regulations for Nordic products
org_id Number No All The organization to which the customer is assigned. A customer may only have a single organization in City API.
organization Object Yes All Associated organization details for the user, if any, and if embedded. Not required/used in POST and PUT requests.
is_active String No All Whether the user is currently active. Not required/used in POST and PUT requests.
last_accessed DateTime* Yes All The last time the user accessed City API, if ever. Not required/used in POST and PUT requests.
last_deactivated DateTime* Yes All The last time the user was deactivated, if ever. Not required/used in POST and PUT requests.
is_owner Boolean No OrgAdmin Whether the organization member is an owner. Owners have automatic access to all organization resources.
default_tag_50 String Yes OrgAdmin The default tag 50 to use across accounts, if any. Only available for organization admins.
notify_when_acct_added Boolean No OrgAdmin Whether the user will be notified when new accounts are added to their organization.
notify_when_cust_added Boolean No OrgAdmin Whether the user will be notified when new customers are added to their organization.
notify_when_cust_order_rejected Boolean No OrgAdmin Whether the user will be notified when customer orders are rejected.

JSON Sample

{
  "email" : "first.last@example.com",
  "first_name" : "Doug",
  "last_name" : "Kurth",
  "user_type" : "Customer",
  "trading_capacity" : 1,
  "liquidity_provision" : 1,
  "commodity_deriv_indicator" : 0,
  "investment_decision" : 2345,
  "execution_decision" : 6789,
  "trader_id" : "5678",
  "is_professional" : false,
  "id" : 12345,
  "is_active" : false
}

Reset Password Link Object

Description

An object containing a link for resetting a user's password.

Fields

Field Type Optional Subtypes Description
link String No All A link for resetting a user's password.

JSON Sample

{
  "link" : "https://api.optionscity.com/setpassword?code=6044f6b1-665a-49fb-a44c-33cbd6f6be69"
}

* Date and time elements are ISO-8601 string representations