Create a subaccount request for a user.

Available to: Organization administrators

Environments: Production

Rate Limit: 250 requests per hour, 30-second back-off, counts all requests

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>

<Info>Requests with firstName and lastName fields exceeding a combined 60 characters are rejected, despite each field individually allowing up to 64 characters.</Info>

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.

Optional: Specify an Auto-Liquidation Profile

Include autoLiqProfileId to assign a specific auto-liquidation profile to the new account. If you omit this field, the system uses your organization's default auto-liquidation profile.

The system validates that the profile exists and belongs to your organization before accepting the request. If validation fails, the response includes an errorText:

• "Auto-liq profile not found": the profile ID does not exist
• "Auto-liq profile does not belong to this organization": the profile belongs to a different organization

Contact Evaluation Support for your organization's available profile IDs.

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
• autoLiqProfileId references a non-existent profile
• autoLiqProfileId belongs to a different organization

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.