### Create a subaccount request for a user.
**Available to:** Organization administrators
**Environments:** Production
**Rate Limit:** 10 requests per hour with 30-second back-off penalty
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.
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
Unique identifier for the subaccount request. Store this for subsequent operations.
statusenum
Current status of the subaccount request.
errorTextstring
Error message if the request failed (access control errors).
Create a subaccount request for a user.
Available to: Organization administrators
Environments: Production
Rate Limit: 10 requests per hour with 30-second back-off penalty
Use this endpoint to submit a new subaccount request for a user in your organization.
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.
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.
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.
