Skip to navigation

Get Eligible Entitlements

View as Markdown

Retrieve the entitlements a user is eligible for.

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

Environments: Live

Rate Limit: No endpoint-specific limit

Return the entitlement IDs a user is eligible for under a given entitlement name. Pass the entitlementName. To query another user, an organization administrator also passes that user’s userId; omit userId to query yourself. The response returns the matching IDs in the entitlementIds array.

An entitlement counts as eligible only if the user meets the requirements it sets, which can include:

  • An active Live account
  • A minimum total net liquidation value across the user’s active accounts
  • A current subscription plan (one of the entitlement’s plan categories, if it lists any)
  • The entitlement’s use conditions
  • A non-professional certification: the user must be non-professional and have signed it, unless you set nonProSigned to true
  • Rules specific to the NinjaTrader Sim+ entitlements, which depend on whether the user has an active Live account and on their subscription plan (simulationPlan), on whether they have an active Live account (simulationPlanBeta), or on whether they’ve submitted an application or hold an active paid subscription (simulationPlanPromo)

An entitlement with a use limit, a minimum number of days between uses, or a free-first-use offer can also have a next eligible date. It counts as eligible only on or after that date.

Common Failure Scenarios

  • No entitlement the caller can access has the given entitlementName, or the user doesn’t meet the requirements of any that do. Both return HTTP 200 with an empty entitlementIds array and no errorText. When the user is eligible for only some of them, the response lists only those.
  • The request includes userId and the caller isn’t an organization administrator. This returns HTTP 401 even when userId is the caller’s own ID, so omit userId to query yourself.
  • No user matches userId, or you can’t access that user. Both return HTTP 404 with an empty body. Most organization administrators can’t access users outside their organization.
  • 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".
  • entitlementName is empty or longer than 64 characters, or userId isn’t greater than 0. These return HTTP 400.
  • The request is sent to Demo. This endpoint runs on Live only, so Demo returns HTTP 501.

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
"Entitlement Name should be specified"400entitlementName is empty or null.
"Entitlement Name should be no longer than 64"400entitlementName is longer than 64 characters.
"User Id should be greater than 0"400userId is included and isn’t greater than 0.
"mustBeOrganizationAdmin"401The request includes userId and the caller isn’t an organization administrator.
"Access is denied"401The caller’s user type, or the API key’s permissions, don’t include full access to the Users resource.
(no message text)404No user matches userId, or you can’t access that user (most organization administrators can’t access users outside their organization).
"This endpoint should be called on live.tradovateapi.com"501Called on the Demo environment.
"Internal Error. Error ID: {id}"200 (in errorText)The eligibility check failed unexpectedly. The error ID is generated per request.
"Request timeout. Error ID: {id}"200 (in errorText)The eligibility check didn’t respond in time. 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.
entitlementNamestringRequired<=64 characters
nonProSignedbooleanOptional
userIdlongOptional

Response

GetEligibleEntitlementsResponse
entitlementIdslist of longs
errorTextstringOptional<=8192 characters

Non-empty if the request failed