Skip to navigation

Request Trading Permission

View as Markdown

Send a request to grant trading permission for your account to another party.

Available to: Traders (own account); organization administrators (any account in their organization)

Environments: Demo, Live

Rate Limit: 20 requests per hour, 2-second back-off, counts failed requests only

On Live, some organizations restrict administrators from accessing other members’ accounts unless they hold an approved trading permission for that account.

Note: On Demo, partner organizations can grant a trading permission directly with createTradingPermission.

Ask for another user to be given trading permission on an account. Pass the accountId, the other user’s ctaEmail, and their ctaContact. ctaContact must be the user’s first and last name separated by a space, exactly as in their contact information. When the request succeeds, the response returns the new tradingPermission.

When the other user is in your organization, has given you consent to grant them trading permissions, or is set to accept trading permissions automatically, the permission is accepted right away (Approved on Demo, Accepted on Live). Otherwise it starts as Requested.

Only an Approved permission gives the other user access to the account. A Requested or Accepted permission still needs to be reviewed and approved first.

Common Failure Scenarios

  • The ctaEmail and ctaContact don’t identify a trader who can accept this permission. This returns HTTP 200 with "Incorrect contact information" in errorText. If you belong to an organization, the server first looks for the one user in your organization with that email. If there isn’t exactly one, it looks for exactly one user anywhere whose email matches, and that user must have consented to trading permissions from you. Either way, the user must be a trader whose first and last name, separated by a space, exactly match ctaContact, including capitalization. On Demo, the server retries the lookup for about 11 seconds before returning this error.
  • The other user already has a trading permission for this account that hasn’t been declined or revoked. This returns HTTP 200 with "Duplicate request" in errorText, along with the existing permission.
  • The other user has reached their limit of permissioned accounts, or the grant would exceed a subaccount limit. These return HTTP 200 with the limit message in errorText.
  • The caller doesn’t own the account and isn’t an organization administrator. This returns HTTP 401 with "mustBeOrganizationAdmin".
  • No account matches accountId, or the caller can’t access it. Both return HTTP 404 with an empty body.
  • accountId isn’t greater than 0, ctaContact or ctaEmail is empty or longer than 64 characters, or ctaEmail isn’t a valid email address. These return HTTP 400.
  • The caller’s user type, or the API key’s permissions, don’t include full access to the Users resource. This returns HTTP 401 with "Access is denied".

This endpoint returns HTTP 200 for both successful and rejected requests, so check the errorText field to confirm the result. Other failures, such as denied access or an invalid request, return their own HTTP status.

Error Messages

MessageResponseTrigger
"Account Id should be greater than 0"400accountId isn’t greater than 0.
"Cta Contact should be specified"400ctaContact is empty or null.
"Cta Contact should be no longer than 64"400ctaContact is longer than 64 characters.
"Cta Email should be specified"400ctaEmail is empty or null.
"Cta Email should be no longer than 64"400ctaEmail is longer than 64 characters.
"Email is invalid"400ctaEmail isn’t a valid email address.
"Access is denied"401The caller’s user type, or the API key’s permissions, don’t include full access to the Users resource.
"mustBeOrganizationAdmin"401The caller doesn’t own the account and isn’t an organization administrator.
(no message text)404No account matches accountId, or the caller can’t see it.
"Incorrect contact information"200 (in errorText)ctaEmail and ctaContact don’t identify a trader who can accept this permission (see Common Failure Scenarios for the matching rules).
"Duplicate request"200 (in errorText)The other user already has a trading permission for this account that hasn’t been declined or revoked.
"User has hit max limit of {limit} permissioned accounts."200 (in errorText)The other user has reached their maximum number of permissioned accounts. Applies only when the other user has no organization or is in the NTB organization. {limit} is that user’s limit (42 by default); archived and revoked permissions don’t count.
"POA has reached the maximum number of subaccounts allowed."200 (in errorText)Granting the permission would exceed your organization’s subaccount limit for the other user (5 by default; your organization can set its own). Applies only when you belong to an organization and the other user belongs to an organization other than NTB.
"Internal Error. Error ID: {id}"200 (in errorText)Looking up the other user failed unexpectedly. The error ID is generated per request.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
accountIdlongRequired
ctaContactstringRequired<=64 characters
ctaEmailstringRequired<=64 characters

Response

TradingPermissionResponse
errorTextstringOptional<=8192 characters

Non-empty if the request failed

tradingPermissionobjectOptional