Overview
A focused rebalance generates trades for only part of a sleeved portfolio. Holdings outside the focus are left as they are.
This is the same URL as a standard sleeve rebalance. The run is treated as focused when you send rebalanceType: “Focused Rebalance” and tradeInstanceSubType: 4 and exactly one focus identifier.
Do not mix this recipe with the standard sleeve recipe (tradeInstanceSubType: 14) — subtype 14 runs a full-portfolio sleeve rebalance, not a focused one.
1. Endpoint
Headers
| Header | Value |
|---|---|
| Authorization | Session <access_token> |
| Content-Type | application/json |
2. Quick Start
To kick off a focused sleeve rebalance, you need three things:
- A valid session token
- The portfolioId of the parent sleeved portfolio
- A POST request with the body below, using the focus identifier that matches what you want to rebalance
Choose one focus identifier
Send exactly one of these — never more than one per call.
| If you want to rebalance… | Send | Type | Scope |
|---|---|---|---|
| Every sleeve that shares a sleeve strategy | sleeveStrategyIds | string array, e.g. [“11”] | Those sleeves only. Others are skipped. |
| Every sleeve that uses a sleeve model | sleeveModelIds | integer array, e.g. [1414] | Those sleeves only. Others are skipped. |
| Specific nodes inside one sleeve’s model | modelTypeIds | integer array, e.g. [16905] | Those nodes in that one sleeve. All other holdings in the sleeve, and all other sleeves, are left alone. |
JSON typing matters. sleeveStrategyIds values must be strings. sleeveModelIds and modelTypeIds values must be integers. Sending the wrong type may silently fail to resolve the focus.
Quick Start template
Copy this template exactly, replace portfolioIds and the focus identifier, and send it. The fields you may want to customize are covered in §3.2 — all others should be sent as shown.
{
"portfolioIds": [3555],
"sleeveStrategyIds": ["11"],
"tradeInstanceType": 6,
"tradeInstanceSubType": 4,
"tradeToolSelection": 10,
"rebalanceType": "Focused Rebalance",
"useDefaultPreference": true,
"isViewOnly": true,
"reason": null,
"isExcelImport": false,
"minimumTradeAmount": { "type": "$", "amount": null },
"maxGainAmount": null,
"allowWashSale": null,
"allowShortTermGain": null,
"priorityRanking": null,
"rounding": null
}For a sleeve model, replace “sleeveStrategyIds”: [“11”] with “sleeveModelIds”: [1414]. For a security-set run, replace it with “modelTypeIds”: [16905].
3. Request Body
3.1 Required identifiers & metadata
| Field | Type | Value | Notes |
|---|---|---|---|
| portfolioIds | int[] | e.g. [3555] | Parent sleeved portfolio. One-element array for a single portfolio. |
| One of sleeveStrategyIds / sleeveModelIds / modelTypeIds | see §2 | see §2 | Exactly one. Never send two focus identifiers on one call. |
| tradeInstanceType | int | 6 | Portfolio rebalance. |
| tradeInstanceSubType | int | 4 | Focused rebalance. 14 is a full sleeve rebalance — a different operation. |
| tradeToolSelection | int | 10 | From the rebalance tool. |
| rebalanceType | string | “Focused Rebalance” | Triggers the focused flow. |
You do not send tradeInstanceId. The backend creates the trade instance and returns its id in the response.
Extra rule for modelTypeIds: all values must belong to the same sleeve model and the same level of that model tree. The sleeve is inferred from the nodes.
3.2 Fields you may want to customize
| Field | Type | Recommended | Notes |
|---|---|---|---|
| useDefaultPreference | bool | true | Use the firm’s saved rebalance preferences. Strongly recommended. When true, allowWashSale, allowShortTermGain, and maxGainAmount are ignored and the firm’s saved values are used instead. |
| isViewOnly | bool | null | true for the first call | true = preview only (will not flow to execution). null or false = committable trades. |
| reason | string | null | null | Optional free-text reason logged on the trade instance. |
| minimumTradeAmount | { type, amount } | { “type”: “$”, “amount”: null } | Minimum trade amount. amount: null uses the firm’s default. If type: “%”, amount must be ≤ 100. |
| maxGainAmount | decimal | null | null | Cap on the total realized gain produced by this run. null = no override (uses firm default). Only honored when useDefaultPreference: false. |
| allowWashSale | bool | null | null | Override the firm’s wash-sale rule. null = use the firm’s saved value. Only honored when useDefaultPreference: false. |
| allowShortTermGain | string | null | null | Override the firm’s short-term-gain rule. null = use the firm’s saved value. Accepted values: “Allow”, “Full Position Disallow”, “TaxLot Disallow”. Only honored when useDefaultPreference: false. |
All other fields in the Quick Start template should be sent exactly as shown.
4. Response
A successful call returns 200 OK.
4.1 Sample response
An empty trades: [] array is success, not failure. It means either the focused sleeves/nodes were already in tolerance, or (on a security-set run) the targeted sleeve is not eligible for this operation. See §4.4.
4.2 Top-level fields
| Field | Type | Description |
|---|---|---|
| tradeInstanceId | long | Server-generated id for this run. Save it — it’s how you’ll find or reconcile the trades downstream. |
| instanceId | long | Same value as tradeInstanceId. Both are returned for backward compatibility. |
| isViewOnly | bool | Echoes the resolved value. Confirms whether trades were saved as preview or committable. |
| shouldUseV2PostTradeProcess | bool | true when the run used the current post-trade pipeline. |
| trades | Trade[] | Every trade saved against this instance. May include JOURNAL IN / JOURNAL OUT rows on strategy/model runs — see §4.3 and §4.4. |
4.3 Trade object fields (response only)
Each entry in the trades[] array is generated by the rebalancer — none of these fields are set by the caller. The list below covers the fields most external consumers use.
Identity
| Field | Type | Description |
|---|---|---|
| tradeId | int | Unique id of this trade row. |
| tradeInstanceId | long | Parent trade instance id. |
| portfolioId | int | Portfolio this trade belongs to. |
| accountId | int | Account (sleeve) this trade belongs to. |
| securityId | int | Internal security id. |
| symbol | string | Security symbol (e.g. IBM). “CUSTODIAL_CASH” for journal rows. |
| securityName | string | Human-readable security name. |
| securityType | string | Equity, Mutual Fund, Bond, Other. |
Action
| Field | Type | Description |
|---|---|---|
| action | string | BUY, SELL, JOURNAL IN, or JOURNAL OUT. Journals appear only on strategy/model runs. |
| approvalStatus | string | Current approval state (e.g. Approved). |
| rebalanceLevel | string | “Sleeved Portfolio” for strategy/model runs. “Sleeve” for security-set runs. |
| rebalanceLevelId | int | 3 for strategy/model runs. 4 for security-set runs. Key off this if you need to detect the focus type from the response. |
| isCustodialCash | int (0/1) | 1 on journal rows, 0 otherwise. |
| tradeCreatedDate | ISO datetime | When the trade was created. |
Quantity & price
| Field | Type | Description |
|---|---|---|
| tradeShares | decimal | Shares traded (rounded to final precision). |
| price | decimal | Per-share price used. 1 for journal rows. |
| tradeAmount | decimal | Total dollar value (tradeShares × price). |
| priceDate | ISO datetime | As-of date of the price. |
Cost basis & gain/loss (sells only)
| Field | Type | Description |
|---|---|---|
| costAmount | decimal | Total cost basis. |
| costPerShare | decimal | Per-share cost basis. |
| tradeGainLoss | decimal | Total realized gain or loss. |
| tradeSTGainLoss / tradeLTGainLoss | decimal | Short-term / long-term split. |
Custodian & fees
| Field | Type | Description |
|---|---|---|
| custodianId | int | Internal custodian id. |
| custodian | string | Custodian display name. |
| transactionFee | decimal | Transaction fee on this trade. |
| redemptionFee | decimal | Redemption fee on this trade. |
Account & tax context
| Field | Type | Description |
|---|---|---|
| taxableType | string | TAXABLE, TAXDEF, TAXEXMPT. |
| billingAccount | int (0/1) | 1 if this is a billing account. |
4.4 How to tell which focus produced the trades
| Strategy / model run | Security-set run | |
|---|---|---|
| rebalanceLevel | “Sleeved Portfolio” | “Sleeve” |
| rebalanceLevelId | 3 | 4 |
| accountId across rows | May differ (multiple focused sleeves) | Same sleeve on every row |
| JOURNAL IN / JOURNAL OUT rows | Possible when cash moves between focused sleeves | Never |
A journal row is identifiable by action of JOURNAL IN or JOURNAL OUT, isCustodialCash: 1, symbol: “CUSTODIAL_CASH”, and price: 1.
5. Errors
5.1 Error body
The message field (prefixed with [REBAL] : ) is the canonical signal for what went wrong. Surface it in your logs — don’t rely on the HTTP status alone.
5.2 Status codes
| Code | Meaning |
|---|---|
| 200 OK | Run completed. Includes trades: [] (focused sleeves/nodes were in tolerance, or a security-set sleeve is ineligible — see §6). |
| 400 Bad Request | Request validation failed (missing portfolioIds, missing focus identifier, or missing required trade-instance metadata). |
| 401 / 403 | Missing, invalid, or unauthorized token. |
| 500 Internal Server Error | Portfolio, sleeve, model, or preference check failed. Read the [REBAL] : message. |
5.3 Common failure messages
- [REBAL] : Invalid Portfolio/Account type sent in request parameters. — the portfolio is not sleeved. Use the non-sleeved focused rebalance guide instead.
- [REBAL] : Total of Sleeve Targets of Sleeve Type-‘NORMAL’ must be equal to 100%. — strategy/model runs validate the whole portfolio, even outside the focus.
- [REBAL] : Invalid Model Detail Id — a modelTypeIds value doesn’t belong to that sleeve’s model.
- [REBAL] : Model Detail Ids are not at same level . — mixed levels in modelTypeIds.
- [REBAL] : The selected portfolio/sleeve has a substitute on the model. Please select the substituted model for tactical rebalance. — substitute models are not supported.
- [REBAL] : Invalid Account Id. — the resolved sleeve is not valid for this portfolio.
- [REBAL] : Portfolio analytics are still running. — wait for post-import analysis to complete and retry.
6. Important Reminders
- Send the focused recipe completely. rebalanceType: “Focused Rebalance” + tradeInstanceSubType: 4 + exactly one focus id array. Subtype 14 is a full sleeve rebalance, not this flow.
- Strategy ids are strings; model and security-set ids are integers. Sending the wrong JSON type may silently fail to resolve the focus.
- Never send two focus identifiers on one call.
- Empty trades: [] is success. On a security-set run, also confirm the targeted sleeve is NORMAL and not SMA- or Astro-enabled — an ineligible sleeve returns 200 with an empty array, not an error.
- Save tradeInstanceId from the response. It’s how you’ll look up or reconcile the generated trades. You cannot supply it in the request — the backend always creates a new one.
- This endpoint does not execute trades. It only generates and saves them. Execution to a custodian or broker is a separate downstream system.
- You own idempotency, concurrency, and rate limiting. Every call creates a new trade instance and a new set of trades — the endpoint does not de-duplicate retries or block concurrent runs against the same portfolio.