REST API EndpointsUsers

Create Partner Subaccount Request

### Create a subaccount request for a user. **Available to:** Organization administrators **Environments:** Production **Rate Limit:** 10 requests per 30 seconds with time penalty for exceeding the limit Use this endpoint to submit a new subaccount request for a user in your organization. <Warning>**Warning:** This endpoint returns **HTTP 200** for successes **and** business errors. Always check the `errorText` field in the response body to determine whether the request succeeded or failed.</Warning> **US vs Non-US Requirements** - **US citizens**: Require a valid `taxIdentifier` (Social Security Number, exactly 9 digits). The `nationalId` field is optional. - **Non-US citizens**: Require a valid `nationalId` (2-64 alphanumeric characters). The `taxIdentifier` field is optional. **`requestId` for Uploading Documents** A successful request returns a unique `requestId`. Use this value: - As the `subAccountRequestId` when uploading the user's required documents with `submitpartnersubaccountdocument` - As the `subAccountRequestId` when tracking the progress of a subaccount request with `getpartnersubaccountrequeststatus` **Optional: Attach Previously Uploaded Documents** If you have already uploaded the user's required documents via the `submitcustomerapplicationdocument` endpoint, you can link them to the subaccount request by providing all three `documentId` fields (partial sets are rejected): - `pOAFormDocId` - `governmentDocId` - `addressDocId` If you provide all three document IDs, the documents are linked directly and you do not need to call `submitpartnersubaccountdocument` afterward. **Common Failure Scenarios** - Invalid or non-existent `ctaUserId` - `ctaUserId` belongs to a different organization - Missing required fields (firstName, lastName, citizenship, etc.) - Invalid Social Security Number (SSN) format for US citizenship (must be exactly 9 digits) - Missing `nationalId` for non-US citizenship - Invalid country or citizenship code (must be 2-character ISO code) - Invalid name characters (letters, spaces, hyphens, apostrophes, periods only) - Combined first and last name exceeds 60 characters - Non-admin user attempting to call the endpoint - Country or state is restricted - No master account found for the organization admin - No customer application found for the master account - Insufficient funds in master account to cover the `transferAmount` - Max sub-account limit exceeded for the given trader - When providing document IDs, must provide all three or none (partial is rejected) - Provided document IDs do not exist in the database **Next Steps** - If you have not uploaded the user's required documents, use the `submitpartnersubaccountdocument` endpoint to upload them. - If you already uploaded the user's required documents and provided the document IDs, use the `getpartnersubaccountrequeststatus` endpoint to check the status of the subaccount request.

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.
ctaUserIdlongRequired
The existing Tradovate userId for the trader. Must be greater than 0 and belong to your organization.
riskCategoryIdlongRequired
Risk category ID for the subaccount. Must be greater than 0.
firstNamestringRequiredformat: "^[A-Za-zÀ-ſ]+(\s?[\-.'À-ſA-Za-z]+)*$"1-64 characters

Trader’s first name. Letters, single spaces, hyphens, apostrophes, and periods allowed. 1-64 characters.

lastNamestringRequiredformat: "^[A-Za-zÀ-ſ]+(\s?[\-.'À-ſA-Za-z]+)*$"1-64 characters

Trader’s last name. Letters, single spaces, hyphens, apostrophes, and periods allowed. 1-64 characters.

birthDatestringRequiredformat: "date"

Trader’s date of birth in YYYY-MM-DD format.

citizenshipstringRequired=2 characters

Two-character ISO country code for citizenship.

countrystringRequired=2 characters

Two-character ISO country code.

statestringRequired2-29 characters

State or province. For US addresses, must be exactly 2 characters (state code). For non-US addresses, can be 2-29 characters.

streetAddress1stringRequired3-61 characters

Primary street address (3-61 characters).

citystringRequired2-35 characters

City name (2-35 characters).

zipCodestringRequired4-11 characters

Postal/ZIP code (4-11 characters).

phonestringRequired7-21 characters

Phone number (7-21 characters). Supports international prefixes.

marginTypeenumRequired
Trading margin type classification.
Allowed values:
transferAmountdoubleRequired>=0
Transfer amount.
authorizedIndividualbooleanRequired
Whether the trader is an authorized individual.
taxIdentifierstringOptional

Social Security Number for US citizens (exactly 9 digits, no dashes). Required for US citizenship.

nationalIdstringOptional2-64 characters

National ID for non-US citizens (2-64 alphanumeric characters). Required for non-US citizenship.

streetAddress2stringOptional<=61 characters

Secondary address line (optional, max 61 characters).

traderReasonstringOptional<=8192 characters

Reason for trading or evaluation purpose (optional, max 8192 characters).

pOAFormDocIdlongOptional
Optional. Document ID for a previously uploaded POA Form. Must provide all three document IDs or none.
governmentDocIdlongOptional
Optional. Document ID for a previously uploaded Government ID. Must provide all three document IDs or none.
addressDocIdlongOptional
Optional. Document ID for a previously uploaded Proof of Address. Must provide all three document IDs or none.

Response

CreatePartnerSubaccountRequestResponse
requestIdlong or null
Unique identifier for the subaccount request. Store this for subsequent operations.
statusenum or null
Current status of the subaccount request.
errorTextstring or null

Error message if the request failed (access control errors).