An integration guide for DTCC Digital Assets APIs organized around four core implementation journeys: account management, wallet management, conversion order processing, and corporate action handling. Each section presents the workflow sequence, key endpoints, request and response patterns, business rules, and operational considerations required to implement and operate integrations with the platform.
Last published: October 14, 2026. See the Change Log tab for update details.
This reference organizes DTCC Digital Assets APIs by implementation journey rather than by internal service boundary. The guide covers four core journeys: account management, wallet management, conversion order processing, and corporate action handling. Each tab presents a compact workflow summary, a searchable endpoint reference, representative payloads, business rules, status handling, and retry guidance.
| Environment | Identity (Authentication) | Services |
|---|---|---|
| PSE (Pre-Production) | https://api.pse.lds.dtcc-da.com/identity | https://api.pse.lds.dtcc-da.com/services |
| Production | https://api.dtcc-da.com/identity | https://api.dtcc-da.com/tokenization/services |
/connect/token with grant_type=urn:dtcc:params:oauth:grant-type:service-account-credentials, type=conveyance, entity={entityId}, acr_values=tenant:{tenantName}, username={username}, and password={password}. Downstream API calls use Authorization: Bearer {access_token}. Finding your entity ID: the value for entity={entityId} is shown on the participant's My Company page in the Tokenization App UI, where the participant can view the entity ID assigned to them.Each tab starts with a compact flow showing call ordering, parallel-load opportunities, branch behavior, and service dependencies before endpoint-level detail.
Workflows begin with a service account token request using the conveyance model and tenant/entity context. The resulting access token is passed as a bearer token to each API.
Each journey includes business rules, retry guidance, permission considerations, idempotency, async state tracking, and graceful degradation for reference-data failures.
| Journey | Primary APIs | Purpose |
|---|---|---|
| Account Management | /connect/token, /v1/accounts/roots, /v1/accounts/{accountId}, /v1/accounts/{accountId}/hierarchy, /v1/accounts/{accountId}/wallets, /v1/conversion/accounts/{accountId}/activities, /v1/conversion/accounts/{accountId}/balances | Resolve an account via root hierarchy, then retrieve account detail, sub-account hierarchy, linked wallets, on-chain activity, and security-level balances. |
| Wallet Management | /connect/token, /v1/conversion/wallets | Load wallet inventory for administration and status tracking. |
| Conversion Orders | /connect/token, /v1/conversion/securities, /v1/conversion/securities/issue-types, /v1/conversion/securities/issue-subtypes, /v1/conversion/securities, /v1/conversion/wallets, /v1/conversion/orders, /v1/conversion/async-operations/query, /v1/conversion/orders/{orderId} | Discover eligible securities, retrieve order inputs, submit conversion orders, resolve the order identifier from the async operation, and retrieve order detail. |
| Corporate Actions | /connect/token, /v2/corporate-actions, /v2/corporate-actions/event-types, /v1/conversion/securities, /v2/corporate-actions/{id} | Discover, filter, and inspect corporate action events and lifecycle context. |
This framework defines the Workflow Certification Program for Tokenization Service integrations. The intent of these certifications is not to validate individual API endpoints. Endpoint behavior, request formats, and response structures are already covered by API specifications and implementation guides. Instead, this framework validates that a customer or integration partner can correctly execute the complete business workflows required for production operation.
Complete the ordered sequence of steps that compose each production workflow.
Apply the platform business rules that govern eligibility, direction, and validation.
Handle invalid credentials, expired credentials, access denials, and service failures.
Demonstrate production supportability across the certified workflows.
Sustain and monitor operations after go-live without introducing risk.
Produce request logs, response payloads, and execution output as audit evidence.
Each workflow document follows the same seven-step structure. The objective is to verify that customers can correctly implement the platform's intended workflow patterns rather than simply execute API calls successfully.
Establish a valid session.
Load inputs for the workflow.
Enforce platform constraints.
Perform the operation.
Confirm expected results.
Manage error conditions.
Capture supporting audit artifacts.
The following workflow certifications are currently included within the Tokenization Service certification framework.
All workflow certifications require demonstration of the following.
| Requirement | Detail |
|---|---|
| Authentication | Valid service account authentication. |
| Error Handling | Invalid credentials, expired credentials, access denied, invalid requests, not found conditions, and service failures. |
| Workflow Completion | All required steps executed successfully. |
| Auditability | Request logs, response payloads, execution output, workflow results, and negative-test results. |
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Malformed request, invalid parameter, or invalid credentials | Correct the request. Do not retry as-is. |
| 401 | JWT access credential missing, expired, or invalid | Request a new JWT access credential, then retry once. |
| 403 | Service account lacks the required permission, or the account is locked | Surface access denied. Do not retry. |
| 404 | Resource not found | Surface not found. Do not retry. |
| 500, 503 | Service failure | Retry with exponential backoff, maximum three attempts. |
Conversion order submission adds two codes: 409 for a duplicate X-Idempotency-Key, and 422 for a business rule violation such as invalid conversion direction, quantity of zero, or submission outside operational hours.
These workflow certifications serve as the formal production-readiness gate for Tokenization Service integrations.
Participant onboarding establishes the DTCC entity, account hierarchy, wallet structure, administrative access, and service-account readiness required before a participant can begin using Tokenization Services.
Capture participant name, DTC account information, technical contact, entity administrator, and go-live inputs.
The Integration team uses the Operations Portal to initiate participant onboarding, validate onboarding inputs, and launch the provisioning workflow.
Create the participant entity, DTCC standard account structure, provision wallets, assign controller permissions, create the participant administrator, send onboarding notifications, and activate the participant.
Account Management provides service-account based workflows for retrieving account detail, viewing sub-accounts and linked wallets, interpreting access control metadata, and querying on-chain account activities. Accounts give participants the ability to organize their wallets, and each account is made up of a group of subaccounts or wallets. Two accounts are configured by default: Internal, for wallets a participant uses for its own proprietary purposes, and Clients, for wallets registered on behalf of a participant's clients. Balance, on-chain activity, and the list of wallets mapped to an account are available to view for each account. Account Entity and Activity data are served by the DTCC APIs.
/connect/token with grant_type=urn:dtcc:params:oauth:grant-type:service-account-credentials, type=conveyance, entity={entityId}, acr_values=tenant:{tenantName}, username={username}, and password={password}. Downstream API calls use Authorization: Bearer {access_token}. Finding your entity ID: the value for entity={entityId} is shown on the participant's My Company page in the Tokenization App UI, where the participant can view the entity ID assigned to them.A condensed view of the API call sequence, dependencies, and branch rules.
POST /connect/token
Obtain a service-account bearer token.
GET /v1/accounts/roots
Discover root accounts (descendants nested 2 levels) and resolve the target accountId; skip when already known.
GET /v1/accounts/{accountId}
Retrieve the account entity and optional OBAC.
GET /v1/accounts/{accountId}/hierarchy
Retrieve child accounts as a tree.
GET /v1/accounts/{accountId}/wallets
Retrieve linked wallets with ownership stake.
GET /v1/conversion/accounts/{accountId}/activities and GET /v1/conversion/accounts/{accountId}/balances
No interdependency; issue in parallel.
accountId and have no data dependency on each other; issue them in parallel after the account detail is confirmed.Returns root accounts (no parent linkage within the tenant), each with descendants nested up to two levels. Used to discover or resolve the target accountId before opening the detail view; skip when the accountId is already known. The roots response omits ownershipStake, isOwned, and isOperated (those are hierarchy-only); it provides only account identity and nesting.
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| rootAccountName | query | string | Optional | Filter root accounts by name |
| offset | query | integer | Optional | Zero-based pagination offset (min 0; default 0) |
| count | query | integer | Optional | Page size (min 1; default 50) |
| includeObac | query | boolean | Optional | When true, append OBAC metadata to each account in the tree |
const params = new URLSearchParams();
if (rootAccountName) params.set('rootAccountName', rootAccountName); // optional: filter by name
params.set('offset', '0'); // optional: pagination offset
params.set('count', '50'); // optional: page size
if (includeObac) params.set('includeObac', 'true'); // optional: include access control metadata
const rootsResponse = await fetch(
`${baseUrl}/v1/accounts/roots?${params.toString()}`,
{ headers: { 'Authorization': `Bearer ${access_token}` } }
);
if (!rootsResponse.ok) throw new Error(`Root accounts fetch failed: ${rootsResponse.status}`);
const roots = await rootsResponse.json();[
{
"accountId": "84b82357-efbb-4d6e-87a3-930bab6f4623",
"name": "First Bank Securities, Inc",
"children": [
{
"accountId": "d682a056-3c53-4aef-b222-c5e2a0aa25e7",
"name": "First Bank Internal",
"children": [
{ "accountId": "7b62eaa6-2021-4277-bb8d-0b450c580aed", "name": "First Bank Classic", "children": [], "obac": null }
],
"obac": null
}
],
"obac": null
}
]type ListRootAccountsResponse = RootAccountChildrenResponse[];
interface RootAccountChildrenResponse {
accountId: string;
name: string;
children: RootAccountChildrenResponse[]; // descendants, nested up to 2 levels
obac?: AccessControlInfoResponse; // present when includeObac=true
}
interface AccessControlInfoResponse {
isController: boolean;
isShared: boolean;
hasShareRequest: boolean;
}Handle 401 by requesting a new JWT access credential and retrying once; handle 403 as access denied; handle 404 as not found; validate query parameters client-side before submission. Server errors (500) may occur; apply retry with backoff.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Bad request or invalid query parameter | Correct the request. Do not retry as-is. |
| 401 | JWT access credential missing, expired, or invalid | Request a new JWT access credential, then retry once. |
| 403 | Service account lacks the required permission, or the account is locked | Surface access denied. Do not retry. |
| 404 | Not found — unable to find the resource specified | Surface not found. Do not retry. |
| 500 | Internal server error | Retry with exponential backoff and appropriate timeout handling. |
Read-only GET; safe to retry on 5xx or network timeout. Implement exponential backoff with appropriate timeout handling.
Retrieves account data and optional page-level access control permissions. This call confirms that the account exists and that the caller has access.
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| accountId | path | string | Yes | The account identifier |
| includeObac | query | boolean | Optional | When true, includes access-control information |
const accountResponse = await fetch(
`${baseUrl}/v1/accounts/${accountId}?includeObac=true`,
{ headers: { 'Authorization': `Bearer ${access_token}` } }
);
if (!accountResponse.ok) throw new Error(`Account fetch failed: ${accountResponse.status}`);
const account = await accountResponse.json();{
"accountId": "account-id",
"name": "Example Account",
"externalId": null,
"itemId": null,
"obac": { "isController": true, "isShared": false, "hasShareRequest": false }
}interface AccountsModel {
accountId: string;
name: string;
externalId?: string | null;
itemId?: string | null;
obac?: AccessControlInfoResponse | null;
}
interface AccessControlInfoResponse {
isController: boolean;
isShared: boolean;
hasShareRequest: boolean;
}Handle 401 by requesting a new JWT access credential and retrying once; handle 403 as account lockout or access denied; handle 404 as account not found; validate bad requests client-side before submission.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Malformed request or invalid query parameter | Correct the request. Do not retry as-is. |
| 401 | JWT access credential missing, expired, or invalid | Request a new JWT access credential, then retry once. |
| 403 | Service account lacks the required permission, or the account is locked | Surface access denied. Do not retry. |
| 404 | Resource not found | Surface not found. Do not retry. |
| 500, 503 | Service failure | Retry with exponential backoff, maximum three attempts. |
Read-only GET; safe to retry on 5xx or network timeout. Do not retry credential requests on 4xx.
Returns the account's child accounts as a recursively nested tree rooted at accountId. Use depth to limit traversal and includeObac to attach access-control metadata per node.
Each node's ownershipStake is the direct parent's fractional stake, expressed from 0 to 1. Effective indirect ownership multiplies the stakes along the path: if A owns 50% of B and B owns 80% of C, then A's effective stake in C is 0.40 (0.50 × 0.80).
The depth parameter bounds how far the tree is traversed. Pass depth=1 to fetch only an account's direct children, and process one root at a time when enumerating large graphs. Skip the hierarchy call for any node whose children array is already empty, and omit includeObac for read-only enumeration since it adds a per-node access-control lookup.
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| accountId | path | string (UUID) | Yes | The account identifier |
| depth | query | integer | Optional | Levels to traverse (min 0); omit or pass a large value (e.g. 9999) for the full tree |
| includeObac | query | boolean | Optional | When true, append per-node OBAC metadata |
const params = new URLSearchParams();
if (depth != null) params.set('depth', String(depth));
if (includeObac) params.set('includeObac', 'true');
const res = await fetch(
`${baseUrl}/v1/accounts/${accountId}/hierarchy?${params.toString()}`,
{ headers: { 'Authorization': `Bearer ${access_token}` } }
);
const hierarchy = await res.json();[
{
"accountId": "d682a056-3c53-4aef-b222-c5e2a0aa25e7",
"name": "First Bank Internal",
"ownershipStake": 1.0,
"isOwned": true,
"isOperated": false,
"children": [
{ "accountId": "7b62eaa6-2021-4277-bb8d-0b450c580aed", "name": "First Bank Classic", "ownershipStake": 0.5, "isOwned": true, "isOperated": false, "children": [], "obac": null }
],
"obac": null
}
]type AccountHierarchyResponse = AccountChildrenResponse[];
interface AccountChildrenResponse {
accountId: string;
name: string;
ownershipStake: number; // 0–1
isOwned: boolean;
isOperated: boolean;
children: AccountChildrenResponse[]; // nested descendants
obac?: AccessControlInfoResponse; // present when includeObac=true
}Handle 401 by requesting a new JWT access credential and retrying once; handle 403 as account lockout or access denied; handle 404 as account not found; validate bad requests client-side before submission.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Malformed request or invalid query parameter | Correct the request. Do not retry as-is. |
| 401 | JWT access credential missing, expired, or invalid | Request a new JWT access credential, then retry once. |
| 403 | Service account lacks the required permission, or the account is locked | Surface access denied. Do not retry. |
| 404 | Resource not found | Surface not found. Do not retry. |
| 500, 503 | Service failure | Retry with exponential backoff, maximum three attempts. |
Read-only GET; safe to retry on 5xx or network timeout. Do not retry credential requests on 4xx.
Returns the paginated list of wallets linked to the account, each with its computed ownership stake and operational flags. Use to show which wallets back a given account.
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| accountId | path | string (UUID) | Yes | The account identifier |
| offset | query | integer | Optional | Zero-based pagination offset (min 0) |
| count | query | integer | Optional | Page size (min 1) |
| depth | query | integer | Optional | Depth of hierarchy traversed when gathering linked wallets |
| includeObac | query | boolean | Optional | When true, append per-wallet OBAC metadata |
const params = new URLSearchParams();
if (offset != null) params.set('offset', String(offset));
if (count != null) params.set('count', String(count));
if (depth != null) params.set('depth', String(depth));
if (includeObac) params.set('includeObac', 'true');
const res = await fetch(
`${baseUrl}/v1/accounts/${accountId}/wallets?${params.toString()}`,
{ headers: { 'Authorization': `Bearer ${access_token}` } }
);
const wallets = await res.json();[
{
"obac": null,
"accountId": "account_id",
"id": "wallet_internal_id",
"walletId": "wallet_public_id",
"network": "Stellar",
"externalId": "walletExternalId",
"name": "wallet_name",
"isOperated": true,
"ownershipStake": 0.99,
"isOwned": true,
"isEscrow": false
}
]type AccountWalletsResponse = AccountWalletWithObacResponse[];
interface AccountWalletWithObacResponse {
accountId: string;
id: string; // internal wallet id
walletId: string; // public wallet address
network: string; // e.g. "Stellar", "Ethereum"
externalId?: string;
name?: string;
isOperated: boolean;
ownershipStake: number; // 0-1
isOwned: boolean;
isEscrow: boolean;
obac?: AccessControlInfoResponse; // present when includeObac=true
}On 401 request a new JWT access credential and retry once; on 403 surface access denied; on 404 surface account not found; on 400 correct the request; on 5xx retry with backoff.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Malformed request or invalid query parameter | Correct the request. Do not retry as-is. |
| 401 | JWT access credential missing, expired, or invalid | Request a new JWT access credential, then retry once. |
| 403 | Service account lacks the required permission, or the account is locked | Surface access denied. Do not retry. |
| 404 | Resource not found | Surface not found. Do not retry. |
| 500, 503 | Service failure | Retry with exponential backoff, maximum three attempts. |
Read-only GET; safe to retry on 5xx or network timeout.
Retrieves the account's on-chain activity history from the Conversion Service. Each item describes a single transfer or fee with its security, ledger, and counterparty-wallet detail. The response is a flat array with no envelope. Supports application/json and text/csv.
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| accountId | path | string (UUID) | Yes | The account identifier |
| startDate | query | string (date-time) | Optional | Inclusive start date and time of the requested interval. If specified, endDate must also be provided. |
| endDate | query | string (date-time) | Optional | Inclusive end date and time of the requested interval. If specified, startDate must also be provided. A date-only value represents the start of that day at 00:00:00 and therefore does not include records occurring later that day. To include the complete intended end date, specify the following date as endDate. |
| networks | query | string[] | Optional | Filter activities by one or more networks |
| activityTypes | query | string[] | Optional | Filter activities by one or more types |
| fromWalletId | query | string | Optional | The source account or wallet that tokens are debited from. For Classic accounts, the format is {participantId}-10 (Free NA) or {participantId}-11 (Free MA), for example 00002667-10. For digital wallets, this is the registered blockchain wallet address. |
| toWalletId | query | string | Optional | The destination account or wallet that tokens are credited into. For Classic accounts, the format is {participantId}-10 (Free NA) or {participantId}-11 (Free MA), for example 00002667-10. For digital wallets, this is the registered blockchain wallet address. |
| searchFor | query | string | Optional | Search filter; matches by CUSIP and Security |
| offset | query | integer | Optional | Pagination offset |
| count | query | integer | Optional | Page size |
const params = new URLSearchParams();
if (startDate) params.set('startDate', startDate.toISOString());
if (endDate) params.set('endDate', endDate.toISOString());
if (activityTypes) activityTypes.forEach(t => params.append('activityTypes', t));
if (networks) networks.forEach(n => params.append('networks', n));
if (fromWalletId) params.set('fromWalletId', fromWalletId);
if (toWalletId) params.set('toWalletId', toWalletId);
if (searchFor) params.set('searchFor', searchFor);
const activitiesResponse = await fetch(
`${baseUrl}/v1/conversion/accounts/${accountId}/activities?${params.toString()}`,
{ headers: { 'Authorization': `Bearer ${access_token}` } }
);
const activities = await activitiesResponse.json();[
{
"transactionId": "",
"activityType": "Fee",
"status": "Confirmed",
"createdAt": "2026-10-02T14:24:53.998+00:00",
"cusip": "037833100",
"security": "Apple Inc. Common Stock",
"issueSubType": { "id": "1", "code": "CS", "description": "Common Stock" },
"ledger": { "name": "Ethereum", "network": "Ethereum" },
"fromWallet": { "name": "First Bank EVM Wallet", "walletAddress": "0xf684...df", "type": "Internal", "participant": { "name": "First Bank", "id": "0e9dd6ed-87e5-417d-978d-9de36c53d0ee" } },
"toWallet": { "name": "American Bank Besu Wallet", "walletAddress": "0x742d...44e", "type": "Client", "participant": { "name": "American Bank", "id": "1e6dd6th-335-936d-678d-9de36c53d0aa" } },
"quantity": 5
}
]The response is a flat array with no envelope — the top-level value is the activities array itself, not an items/metadata wrapper.
type AccountActivitiesResponse = AccountActivityResponse[]; // flat array — no envelope
interface AccountActivityResponse {
transactionId: string;
activityType: string; // e.g. "Fee"
status: string; // e.g. "Confirmed"
createdAt: string; // date-time
cusip?: string;
security?: string;
issueSubType?: IssueClassificationResponse;
ledger: LedgerRefResponse;
fromWallet: ActivityWalletResponse;
toWallet?: ActivityWalletResponse;
quantity?: number;
}
interface IssueClassificationResponse { id: string; code: string; description: string; }
interface LedgerRefResponse { name: string; network: string; }
interface ActivityWalletResponse {
name?: string;
walletAddress: string;
type?: "Internal" | "Client";
participant?: { name: string; id: string };
}Handle invalid filters as 400; expired credentials as 401; access restrictions as 403; service failures as error states with retry. Activity retrieval fails independently of account retrieval, so account detail remains displayable when activity retrieval fails.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Malformed request or invalid query parameter | Correct the request. Do not retry as-is. |
| 401 | JWT access credential missing, expired, or invalid | Request a new JWT access credential, then retry once. |
| 403 | Service account lacks the required permission, or the account is locked | Surface access denied. Do not retry. |
| 404 | Resource not found | Surface not found. Do not retry. |
| 500, 503 | Service failure | Retry with exponential backoff, maximum three attempts. Continue to display account detail without activities. |
Read-only GET; safe to retry on 5xx or network timeout. If the activity service is unavailable, show account details without activities rather than failing the whole view.
Retrieves per-security balances with per-wallet holder detail from the Conversion Service. The response is wrapped in a MetadataResponse envelope carrying items (the balances) and metadata.asOfDate (the timestamp of the last on-chain data sync). Balances are grouped by security; each item's holders array breaks down quantity per wallet, with wallet detail nested under wallet and network under ledger. This contrasts with the activities endpoint, whose response is a flat array with no envelope.
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| accountId | path | string (UUID) | Yes | The account identifier; the same identifier used by /v1/accounts/{accountId}, and it must be accessible under the calling service account's permissions. |
| balancesDate | query | string (date-time) | Optional | Return balances as of this date and time. If omitted, the latest available balances are returned. |
| networks | query | string[] | Optional | Filter by one or more networks. |
| walletId | query | string | Optional | An optional wallet to filter by. |
| searchFor | query | string | Optional | Search key filter; matches by CUSIP and Security. |
| orderBy | query | string | Optional | Field to sort by. Accepts the AccountBalanceFields value Security (default Security). |
| sortOrder | query | string | Optional | Ascending or Descending (default Ascending). |
| offset | query | integer (int32) | Optional | Zero-based pagination offset (min 0). |
| count | query | integer (int32) | Optional | Page size (min 1). |
GET /v1/conversion/accounts/{accountId}/balances
| Direction | Parameter / Field | Enum Name | Values |
|---|---|---|---|
| Input (query) | orderBy | AccountBalanceFields | Security |
| Input (query) | sortOrder | SortOrder | Ascending, Descending |
const balancesResponse = await fetch(
`${baseUrl}/v1/conversion/accounts/${accountId}/balances`,
{ headers: { 'Authorization': `Bearer ${access_token}` } }
);
if (!balancesResponse.ok) throw new Error(`Balance retrieval failed: ${balancesResponse.status}`);
const balances = await balancesResponse.json();{
"items": [
{
"cusip": "037833100",
"security": "Apple Inc. Common Stock",
"issueSubType": { "id": "1", "code": "CS", "description": "Common Stock" },
"totalQuantity": 1000,
"walletsCount": 2,
"ledgersCount": 1,
"holders": [
{ "quantity": 600, "wallet": { "name": "First Bank EVM Wallet", "walletAddress": "0x742d...44e", "type": "Internal" }, "ledger": { "name": "Ethereum", "network": "Ethereum" } },
{ "quantity": 400, "wallet": { "name": "First Bank Besu Wallet", "walletAddress": "0x4bDb...27c0", "type": "Internal" }, "ledger": { "name": "Besu private", "network": "Besu" } }
]
}
],
"metadata": { "asOfDate": "2026-10-02T00:00:00Z" }
}interface MetadataResponse<T, M> { items: T[]; metadata: M; }
interface AccountSecurityBalancesResponse {
cusip?: string;
security?: string;
issueSubType: IssueClassificationResponse;
totalQuantity: number;
walletsCount: number;
ledgersCount: number;
holders: AccountSecurityHolderBalanceResponse[];
}
interface AccountSecurityHolderBalanceResponse {
quantity: number;
wallet: AccountSecurityHolderWalletResponse;
ledger: LedgerRefResponse;
}
interface AccountSecurityHolderWalletResponse {
name?: string;
walletAddress: string;
type?: "Internal" | "Client";
}
interface LedgerRefResponse { name: string; network: string; }
interface IssueClassificationResponse { id: string; code: string; description: string; }
interface AccountBalancesMetadataResponse {
asOfDate: string; // ISO 8601 — timestamp of last on-chain data sync
}The balances response uses the MetadataResponse envelope: items holds the per-security balances and metadata.asOfDate is the ISO 8601 timestamp of the last on-chain data sync, indicating the point-in-time represented by the balance data. Unlike the activities response, which is a flat array with no envelope, every balances response carries this metadata.asOfDate. The sortOrder query parameter accepts Ascending or Descending (default Ascending).
Handle 401 by requesting a new JWT access credential and retrying once; handle 403 as either an insufficient permission scope or an account the service account is not authorized for; handle 404 as an unknown or inaccessible account identifier and correct the value rather than retrying.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Malformed request or invalid query parameter | Correct the request. Do not retry as-is. |
| 401 | JWT access credential missing, expired, or invalid | Request a new JWT access credential, then retry once. |
| 403 | Service account lacks the required permission, or the account is locked | Surface access denied. Do not retry. |
| 404 | Resource not found | Surface not found. Do not retry. |
| 500, 503 | Service failure | Retry with exponential backoff, maximum three attempts. |
Read-only GET; safe to retry on 5xx or network timeout using exponential backoff with a bounded retry limit. Because this call is expected to run frequently as part of pre-conversion checks and scheduled reconciliation, refresh the JWT access credential proactively ahead of its expiry rather than re-authenticating reactively after a 401.
This endpoint uses the Service Account Credentials grant, consistent with the rest of this guide. Request the credential from /connect/token with grant_type=urn:dtcc:params:oauth:grant-type:service-account-credentials, type=conveyance, entity={entityId}, acr_values=tenant:{tenantName}, username={username}, and password={password} before calling this endpoint. The value for entity={entityId} is shown on the participant's My Company page in the Tokenization App UI.
Demonstrate that a customer integration can authenticate using a service account, resolve the target account by discovering root accounts, retrieve the account entity, retrieve the sub-account hierarchy tree, retrieve the account's linked wallets, retrieve on-chain activities, retrieve and reconcile security-level balances, and correctly handle expected errors and service failures. The purpose of this test is to certify that the integration correctly implements the Account Management workflow before production access is granted.
Seven stages. Stages two through six depend on the JWT access credential issued in stage one using the Service Account Credentials grant. The activities and balances calls in stage six share only the accountId and may be issued in parallel.
Obtain a JWT access credential using SA-AccountBot.
GET /v1/accounts/roots
Discover root accounts and resolve the target accountId.
GET /v1/accounts/{accountId}
Confirm accountId and name.
GET /v1/accounts/{accountId}/hierarchy
Retrieve the child-account tree.
GET /v1/accounts/{accountId}/wallets
Retrieve linked wallets with ownership stake.
GET /v1/conversion/accounts/{accountId}/activities and GET /v1/conversion/accounts/{accountId}/balances
Retrieve on-chain activities and reconcile balances.
accountId and have no data dependency on each other; issue them in parallel after the account detail is confirmed. If activity retrieval fails, account data remains available and the integration must fail gracefully with a clear error message.Provisioned service account, service account password, tenant ID, and base URL. Service accounts and permissions are provisioned by DTCC. The service account must be granted the permissions required to access the roots, hierarchy, wallets, activities, and balances endpoints used in steps two through six. A known accountId is optional because step two resolves the target accountId from the root accounts.
const tenantName = "<tenant-name>"; // recommended, e.g. "DTCC-DA"
const accountId = "<account-id>";
const baseUrl = "<base-url>";
const username = "SA-AccountBot";
const password = process.env.SERVICE_ACCOUNT_PASSWORD!;This step validates that the integration can obtain a JWT access credential from the Identity Server using service account credentials. The JWT access credential proves the caller's identity and must be supplied as a bearer credential on every subsequent API call in this workflow.
async function authenticate() {
const response = await fetch(`${baseUrl}/connect/token`, {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "urn:dtcc:params:oauth:grant-type:service-account-credentials",
type: "conveyance",
entity: ENTITY_ID_OF_WHICH_SA_IS_MEMBER_OF,
acr_values: `tenant:${tenantName}`,
username,
password
})
});
if (!response.ok) {
throw new Error(`Authentication failed: ${response.status}`);
}
const data = await response.json();
return data.access_token;
}HTTP 200; JWT access credential returned; credential accepted by downstream APIs.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Invalid credentials; invalid_client | Surface authentication rejected. Do not retry with the same credentials. |
| 500, 503 | Identity Server failure | Retry with exponential backoff, maximum three attempts. |
Verify the integration can discover root accounts within the tenant and resolve the target accountId used by the subsequent steps. Root accounts have no parent linkage within the tenant and carry descendants nested up to two levels.
async function getRootAccounts(accessToken: string) {
const response = await fetch(
`${baseUrl}/v1/accounts/roots?includeObac=true`,
{ headers: { Authorization: `Bearer ${accessToken}` } }
);
if (!response.ok) {
throw new Error(`Roots retrieval failed: ${response.status}`);
}
return response.json();
}// Flat array of root accounts; each carries descendants nested up to 2 levels.
[
{
accountId: string,
name: string,
children: RootAccountChildrenResponse[]
}
]The roots endpoint returns the root accounts accessible to the authenticated service account within its tenant. Resolve the target accountId from this response before subsequent steps; skip this call when the accountId is already known.
HTTP 200; root accounts returned; at least one accountId resolved; response successfully parsed.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Invalid query parameter | Correct the request. Do not retry as-is. |
| 401 | Expired or invalid JWT access credential | Re-authenticate, then retry once. |
| 403 | Insufficient permissions | Surface access denied. Do not retry. |
Verify the integration can retrieve account information and interpret the account entity correctly.
async function getAccount(accessToken: string, accountId: string) {
const response = await fetch(
`${baseUrl}/v1/accounts/${accountId}?includeObac=true`,
{ headers: { Authorization: `Bearer ${accessToken}` } }
);
if (!response.ok) {
throw new Error(`Account retrieval failed: ${response.status}`);
}
return response.json();
}{
accountId: string,
name: string,
externalId: string | null
}Confirm the response carries accountId and name.
HTTP 200; account returned; accountId matches the resolved request; name interpreted; response successfully parsed. The workflow requires account resolution before subsequent operations.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 401 | Expired or invalid JWT access credential | Re-authenticate, then retry once. |
| 403 | Insufficient permissions | Surface access denied. Do not retry. |
| 404 | Account not found | Surface account not found. Do not retry. |
Verify the integration can retrieve the account's child-account hierarchy as a recursively nested tree.
async function getHierarchy(accessToken: string, accountId: string) {
const response = await fetch(
`${baseUrl}/v1/accounts/${accountId}/hierarchy?includeObac=true`,
{ headers: { Authorization: `Bearer ${accessToken}` } }
);
if (!response.ok) {
throw new Error(`Hierarchy retrieval failed: ${response.status}`);
}
return response.json();
}// Tree of AccountChildrenResponse rooted at accountId.
[
{
accountId: string,
name: string,
ownershipStake: number, // 0–1
isOwned: boolean,
isOperated: boolean,
children: AccountChildrenResponse[]
}
]The hierarchy endpoint returns the child accounts beneath accountId as a recursively nested tree of AccountChildrenResponse items, each carrying ownershipStake, isOwned, isOperated, and nested children.
HTTP 200; hierarchy tree returned; child entities visible; ownershipStake present on each node; no parsing errors.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 401 | Expired or invalid JWT access credential | Re-authenticate, then retry once. |
| 403 | Insufficient permissions | Surface access denied. Do not retry. |
| 500, 503 | Service failure | Display account detail without hierarchy and offer retry. |
Verify the integration can retrieve the wallets linked to the account, each with its computed ownership stake and operational flags.
async function getWallets(accessToken: string, accountId: string) {
const response = await fetch(
`${baseUrl}/v1/accounts/${accountId}/wallets?includeObac=true`,
{ headers: { Authorization: `Bearer ${accessToken}` } }
);
if (!response.ok) {
throw new Error(`Wallet retrieval failed: ${response.status}`);
}
return response.json();
}// Flat array of wallets linked to the account.
[
{
walletId: string,
network: string,
ownershipStake: number, // 0–1
isOwned: boolean,
isOperated: boolean,
isEscrow: boolean
}
]The wallets endpoint returns the wallets backing the account. Confirm each wallet carries a walletId, network, and an ownershipStake in the range 0–1.
HTTP 200; linked wallets returned; ownershipStake present on each wallet; data successfully parsed.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Invalid query parameter | Correct the request. Do not retry as-is. |
| 401 | Expired or invalid JWT access credential | Re-authenticate, then retry once. |
| 403 | Insufficient permissions | Surface access denied. Do not retry. |
| 500, 503 | Service failure | Display account detail without wallet detail and offer retry. |
Verify the integration can retrieve on-chain activities as a flat array and security-level balances wrapped in a MetadataResponse envelope, interpret both payloads, reconcile aggregate balance totals against holder allocations, and process the response metadata. The activities and balances calls share only the accountId and have no data dependency on each other, so they may be issued in parallel.
Both endpoints use the same Service Account Credentials grant as the rest of the workflow, so they reuse the JWT access credential issued in Step 1 rather than obtaining a separate credential. Because there is no interdependency, issue both requests in parallel after the account detail is confirmed.
typescriptasync function getActivities(accessToken: string, accountId: string) {
const response = await fetch(
`${baseUrl}/v1/conversion/accounts/${accountId}/activities`,
{ headers: { Authorization: `Bearer ${accessToken}` } }
);
if (!response.ok) throw new Error(`Activity retrieval failed: ${response.status}`);
return response.json();
}
async function getBalances(accessToken: string, accountId: string) {
const response = await fetch(
`${baseUrl}/v1/conversion/accounts/${accountId}/balances`,
{ headers: { Authorization: `Bearer ${accessToken}` } }
);
if (!response.ok) throw new Error(`Balance request failed: ${response.status}`);
return response.json();
}
// No data dependency between the two calls — issue them in parallel.
const [activities, balances] = await Promise.all([
getActivities(accessToken, accountId),
getBalances(accessToken, accountId)
]);// Top-level array of activity records; no envelope.
[
{
transactionId: string,
activityType: string,
status: string,
createdAt: string,
ledger: { name: string, network: string },
fromWallet: { name?: string, walletAddress: string, type?: "Internal" | "Client" },
toWallet?: { name?: string, walletAddress: string, type?: "Internal" | "Client" },
quantity?: number
}
]The activities response is a flat JSON array of activity records with no envelope. Pagination is carried in the X-Paging-Offset, X-Paging-Count, and X-Paging-TotalCount response headers, not in a body envelope.
Confirm the balances response is wrapped in a MetadataResponse envelope carrying items (the per-security balances) and metadata.asOfDate (the ISO 8601 timestamp of the last on-chain sync). This contrasts with the activities response, which is a flat array with no envelope.
{
items: [
{
cusip: string,
security: string,
issueSubType: { id: string, code: string, description: string },
totalQuantity: number,
walletsCount: number,
ledgersCount: number,
holders: [
{
quantity: number,
wallet: { name?: string, walletAddress: string, type?: "Internal" | "Client" },
ledger: { name: string, network: string }
}
]
}
],
metadata: { asOfDate: string } // ISO 8601
}Every balance record must carry a CUSIP, security name, issue sub-type, total quantity, wallet count, ledger count, and holder records. Total quantity, wallet count, and ledger count must each be zero or greater, and holder records must be present wherever balances exist.
typescriptfor (const item of balances.items) {
const holderTotal = item.holders.reduce(
(sum, holder) => sum + holder.quantity,
0
);
if (holderTotal !== item.totalQuantity) {
throw new Error("Balance reconciliation failed");
}
}Aggregate balances must reconcile with holder-level allocations, so the sum of each holder's quantity equals totalQuantity. Using the sample response, holders of 600 and 400 reconcile to a total of 1000.
HTTP 200 on both calls; activities returned as a flat array with pagination headers; balance items interpreted; aggregate totals reconcile with holder allocations; metadata.asOfDate available as the balance snapshot date.
This endpoint returns distinct error envelope shapes depending on which layer rejects the request.
| HTTP | Condition | Response body | Expected integration behavior |
|---|---|---|---|
| 400 | Malformed authentication request | errorCode, message, requestId, tracingUrl | Correct the request encoding and verify all required fields are present. Do not retry as-is. |
| 401 | Invalid service account credentials | errorCode, message, requestId, tracingUrl | Authentication rejected. Verify credentials before retrying. |
| 401 | Expired or missing access token; GATEWAY__UNAUTHENTICATED | ErrorCode, ErrorMessage | Re-authenticate, then retry once. |
| 403 | Service account lacks the required permission for this account | errorCode, message, requestId, tracingUrl | Confirm the service account was granted the balances permission. Do not retry. |
| 403 | Token does not grant access to this account; GATEWAY__ACCESSDENIED | ErrorCode, ErrorMessage | Surface access denied. Do not retry. |
| 403 | User locked out; AUTHORIZATION_ENGINE__USER_LOCKED_OUT_EXCEPTION | ErrorCode, ErrorMessage | Surface the lockout. Do not retry until the lockout is cleared. |
| 404 | Account identifier does not exist or is not accessible | errorCode, message, requestId, tracingUrl | Validate the account identifier before calling. Do not retry without correcting it. |
| 500, 503 | Service failure | errorCode, errorMessage | Retry with exponential backoff and a bounded retry count. Surface the failure once retries are exhausted and terminate the workflow safely. |
Access tokens are time-limited. Cache the credential, refresh it proactively ahead of expiry rather than reacting to a 401, and never reuse an expired token.
Execute the complete workflow in a single transaction, resolving the account via roots and issuing the activities and balances calls in parallel.
async function runWorkflow() {
const token = await authenticate();
const roots = await getRootAccounts(token);
const accountId = roots[0].accountId; // resolved from Step 2
const account = await getAccount(token, accountId);
const hierarchy = await getHierarchy(token, accountId);
const wallets = await getWallets(token, accountId);
// Activities and balances have no interdependency — issue in parallel.
const [activities, balances] = await Promise.all([
getActivities(token, accountId),
getBalances(token, accountId)
]);
return { roots, account, hierarchy, wallets, activities, balances };
}Authenticate PASS
Resolve via Roots PASS
Retrieve Account PASS
Retrieve Hierarchy PASS
Retrieve Wallets PASS
Query Activities PASS
Query Balances PASS
Workflow Complete PASSEach constituent call returns its expected success code.
| ID | Scenario | HTTP | Expected result |
|---|---|---|---|
| NT-1 | Invalid Credentials | 400 | Authentication rejected with invalid_client. Invalid service account credentials are an expected authentication failure scenario. |
| NT-2 | Expired Credential | 401 | Re-authentication required. |
| NT-3 | Invalid Account | 404 | Account Not Found. |
| NT-4 | Access Denied | 403 | Access Denied for insufficient permissions. |
| NT-5 | Activity Service Failure | 500, 503 | Account data remains available, activity retrieval fails gracefully, and the user receives a clear error message. |
| NT-6 | Invalid Service Account Credentials (Step 6) | 401 | Authentication rejected. Verify credentials before retrying. |
| NT-7 | Insufficient Permission (Step 6) | 403 | Access denied. Confirm the service account was granted the balances permission. |
| NT-8 | Expired Balance Token (Step 6) | 401 | Re-authentication required; GATEWAY__UNAUTHENTICATED. |
| NT-9 | Unauthorized Account Access (Step 6) | 403 | Access denied; GATEWAY__ACCESSDENIED. |
| NT-10 | Locked Out User (Step 6) | 403 | Lockout detected; AUTHORIZATION_ENGINE__USER_LOCKED_OUT_EXCEPTION. |
| NT-11 | Malformed Authentication Request (Step 6) | 400 | Bad request. Correct the request encoding and confirm all required fields are present. |
| NT-12 | Balance Service Failure (Step 6) | 500, 503 | Retry logic executed, failure reported, and the workflow terminated safely. |
A customer is certified only on successful authentication, root-account resolution via /v1/accounts/roots, account retrieval, hierarchy retrieval, wallet retrieval, and parallel activities and balances retrieval with payload validation, reconciliation, and metadata (asOfDate) processing, plus token lifecycle management and a bounded retry strategy, plus proper error handling for invalid credentials, expired credentials, invalid account, insufficient permission, access denied, user lockout, malformed authentication requests, and service failures, plus evidence collection showing each stage completed successfully.
Wallet Management covers wallet inventory used to support wallet administration and status tracking. This guide version focuses on wallet discovery and status-tracking APIs.
/connect/token with grant_type=urn:dtcc:params:oauth:grant-type:service-account-credentials, type=conveyance, entity={entityId}, acr_values=tenant:{tenantName}, username={username}, and password={password}. Downstream API calls use Authorization: Bearer {access_token}. Finding your entity ID: the value for entity={entityId} is shown on the participant's My Company page in the Tokenization App UI, where the participant can view the entity ID assigned to them.A condensed view of the API call sequence, dependencies, and branch rules.
POST /connect/token
Obtain service-account token.
GET /v1/conversion/wallets
Display current wallet inventory.
Use wallet inventory views to monitor wallet state and status changes.
Loads existing wallets for inventory display and status review.
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| searchFor | query | string | Optional | Search for term. Maximum length 256 characters. |
| walletAddress | query | string | Optional | The wallet address. Maximum length 256 characters. |
| type | query | string | Optional | The wallet type: Internal or Client |
| networks | query | string[] | Optional | A list of networks |
| ids | query | string[] | Optional | A list of wallet identifiers |
| includeObac | query | boolean | Optional | When true, the response includes access control metadata |
| eligiblyOnly | query | boolean | Optional | Filter by conversion eligibility |
| name | query | string | Optional | The wallet name |
| orderBy / sortOrder | query | string | Optional | Sorting controls |
| offset / count | query | integer | Optional | Pagination controls |
GET /v1/conversion/wallets
| Direction | Parameter / Field | Enum Name | Values |
|---|---|---|---|
| Input (query) | orderBy | WalletFields | Name, Network, CreatedAt |
| Input (query) | sortOrder | SortOrder | Ascending, Descending |
| Output (response) | type | WalletTypes | Internal, Client |
| Output (response) | state | ProcessingStates | Idle, Registering, Deleting, FailedCompliance, Failed |
const walletsResponse = await fetch(`${baseUrl}/v1/conversion/wallets`, {
headers: { 'Authorization': `Bearer ${access_token}` }
});
const wallets = await walletsResponse.json();[
{ "id": "wallet-1", "name": "Example Wallet", "type": "Client", "network": "Ethereum", "walletAddress": "0x...", "state": "Idle", "trackingWalletId": "tracking-wallet-id", "account": { "name": "Client X", "externalId": "external-id" }, "conversionEligible": false, "failureReason": null }
]interface WalletSummary {
id: string;
name: string;
type: string;
network: string;
walletAddress: string;
state: string;
trackingWalletId: string;
account: AccountDetails;
conversionEligible: boolean;
failureReason: string | null;
}Handle 401 by requesting a new JWT access credential and retrying once; handle 5xx with retry and a visible error state. Wallet registration is not available through this API, so no create or update failure paths apply.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Malformed request or invalid query parameter | Correct the request. Do not retry as-is. |
| 401 | JWT access credential missing, expired, or invalid | Request a new JWT access credential, then retry once. |
| 403 | Service account lacks the required permission, or the account is locked | Surface access denied. Do not retry. |
| 404 | Resource not found | Surface not found. Do not retry. |
| 500, 503 | Service failure | Retry with exponential backoff, maximum three attempts. Terminate the inventory view safely if the failure persists. |
Read-only GET; safe to retry on 5xx or network timeout.
Demonstrate that a customer integration can authenticate with a service account, load wallet inventory, review wallet inventory, and track wallet status. This certification verifies that the customer can correctly consume wallet-related APIs and construct an operational view of wallet inventory and status. The workflow is read-only and intended to support wallet administration and operational monitoring.
Authenticate once, load wallet inventory, then review inventory and track status.
Obtain a JWT access credential using SA-WalletReader.
GET /v1/conversion/wallets
Review the wallet inventory records.
Extract and review wallet status values.
Tenant ID, service account, service account password, base URL, and known wallet data. Required access: /connect/token, /v1/conversion/wallets.
const tenantName = "<tenant-name>"; // recommended, e.g. "DTCC-DA"
const baseUrl = "<base-url>";
const username = "SA-WalletReader";
const password = process.env.SERVICE_ACCOUNT_PASSWORD!;async function authenticate() {
const response = await fetch(`${baseUrl}/connect/token`, {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "urn:dtcc:params:oauth:grant-type:service-account-credentials",
type: "conveyance",
entity: ENTITY_ID_OF_WHICH_SA_IS_MEMBER_OF,
acr_values: `tenant:${tenantName}`,
username,
password
})
});
if (!response.ok) throw new Error(`Authentication failed: ${response.status}`);
const data = await response.json();
return data.access_token;
}
async function getWallets(accessToken: string) {
const response = await fetch(`${baseUrl}/v1/conversion/wallets`, {
headers: { Authorization: `Bearer ${accessToken}` }
});
if (!response.ok) throw new Error(`Wallet retrieval failed: ${response.status}`);
return response.json();
}This step validates that the integration can obtain a JWT access credential from the Identity Server using service account credentials. The JWT access credential proves the caller's identity and must be supplied as a bearer credential on every subsequent API call in this workflow.
const accessToken = await authenticate();HTTP 200; JWT access credential returned; credential accepted by downstream APIs. Evidence: authentication successful, credential received.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Invalid credentials; invalid client | Surface authentication rejected. Do not retry with the same credentials. |
| 500, 503 | Identity Server failure | Retry with exponential backoff, maximum three attempts. |
Verify wallet inventory can be retrieved.
const wallets = await getWallets(accessToken);Wallet data returned; response is non-empty; wallet identifiers present.
HTTP 200; wallet inventory successfully loaded. Evidence: wallet inventory response, wallet count.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Invalid query parameters such as an invalid sort field or malformed filter | Correct the request. Do not retry as-is. |
| 401 | Expired or invalid JWT access credential | Re-authenticate, then retry once. |
| 403 | Missing permission | Surface access denied. Do not retry. |
| 500, 503 | Wallet endpoint failure | Inventory unavailable; surface the failure and terminate the workflow safely. |
Verify wallet inventory can be reviewed.
const inventoryView = wallets.map(wallet => ({
wallet,
account: wallet.account
}));Wallets visible; wallets associated with account data; inventory records complete.
Inventory review completed. Evidence: sample wallet records.
This step performs no additional API calls. Review the wallet inventory returned in Step 2.
Verify wallet status data is visible and reviewable.
const walletStatuses = wallets.map(wallet => ({
walletId: wallet.id,
state: wallet.state
}));state field available; state values populated; states can be reported.
Wallet state visible; wallet state review completed. Evidence: state report, sample wallet states.
This step performs no additional API calls. If the state field is absent from the wallet inventory response, treat the step as failed rather than defaulting to an assumed state.
Execute the complete wallet management workflow in a single run to confirm every stage succeeds in sequence.
async function executeWalletWorkflow() {
const token = await authenticate();
const wallets = await getWallets(token);
return { wallets };
}Authenticate PASS
Load Wallets PASS
Review Inventory PASS
Track Status PASS
Workflow Complete PASSEach constituent call returns its expected success code.
| ID | Scenario | HTTP | Expected result |
|---|---|---|---|
| NT-1 | Invalid Credentials | 400 | Authentication rejected; invalid client. |
| NT-2 | Expired Credential | 401 | Re-authentication required. |
| NT-3 | Missing Permission | 403 | Access denied. |
| NT-4 | Invalid Query Parameters | 400 | Validation error, for example an invalid sort field or malformed filter. |
| NT-5 | Wallet Endpoint Failure | 500, 503 | Inventory unavailable; failure surfaced; workflow terminated safely. |
A customer is certified only on successful authentication, wallet inventory retrieval, inventory review, and wallet-status review, plus proper handling of all negative tests.
Conversion Operations covers discovery of registered securities, filter reference data, active securities for order entry, eligible idle wallets, and conversion order submission. Conversions are the mechanism for clients to convert securities between electronic book entry and digital tokenized forms. When submitting a conversion order, the participant selects the source wallet and the destination wallet. The process for converting securities from electronic to digital and back to electronic is identical; the only difference is what is assigned as the source and destination of the securities. Submission is asynchronous and returns no response body, so the integration polls the async operation with its idempotency key to obtain the order identifier before retrieving the order. Submitted orders are processed straight through, moving from Processing to Completed.
/connect/token with grant_type=urn:dtcc:params:oauth:grant-type:service-account-credentials, type=conveyance, entity={entityId}, acr_values=tenant:{tenantName}, username={username}, and password={password}. Downstream API calls use Authorization: Bearer {access_token}. Finding your entity ID: the value for entity={entityId} is shown on the participant's My Company page in the Tokenization App UI, where the participant can view the entity ID assigned to them.A condensed view of the API call sequence, dependencies, and branch rules.
POST /connect/token
Obtain service-account token.
GET /v1/conversion/securitiesGET /v1/conversion/securities/issue-typesGET /v1/conversion/securities/issue-subtypes in parallel.
GET /v1/conversion/securities?status=ActiveGET /v1/conversion/wallets in parallel.
Use Active securities and wallets that are Idle and conversion eligible.
POST /v1/conversion/orders
Returns 202 Accepted with no body. Retain the idempotency key.
POST /v1/conversion/async-operations/query
Poll with the idempotency key until resourceId is populated.
GET /v1/conversion/orders/{orderId}
Use resourceId as the order identifier.
Orders are processed straight through from Processing to Completed. Failed is terminal.
resourceId.Fetches a paginated securities list alongside issue type and issue sub-type reference data.
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| Offset / Count | query | integer | Optional | Controls which slice of the securities list is returned, where offset sets the starting position and count sets the number of records per page. |
| searchFor | query | string | Optional | Free-text term matched against issuer name, security name, or CUSIP to narrow the securities list. |
| networks | query | string[] | Optional | Restricts results to securities tokenized on one or more ledger networks, specified by network name. When the DTC Classic ledger is specified, the endpoint returns all securities associated with the DTC Classic ledger. |
| issueTypeIds | query | integer[] (int32) | Optional | Restricts results to one or more high-level security classifications such as equity or debt, referenced by identifiers from the issue types endpoint. Replaces the deprecated singular issueTypeId parameter. |
| issueSubTypeIds | query | integer[] (int32) | Optional | Restricts results to one or more finer classifications nested beneath the high-level type, such as common stock, referenced by identifiers from the issue sub-types endpoint. Replaces the deprecated singular issueSubTypeId parameter. |
| status | query | string | Optional | Restricts results to securities in a single lifecycle status. Accepts one FinancialSecurityStatus value: Onboarding, Active, Pause, or Failed. |
| orderBy / sortOrder | query | string | Optional | Determines which field the securities list is ordered on and whether that order runs ascending or descending. |
GET /v1/conversion/securities
| Direction | Parameter / Field | Enum Name | Values |
|---|---|---|---|
| Input (query) | orderBy | FinancialSecurityFields | CUSIP, Description, Issuer |
| Input (query) | sortOrder | SortOrder | Ascending, Descending |
| Input (query) | status | FinancialSecurityStatus | Onboarding, Active, Pause, Failed |
| Output (response) | status | FinancialSecurityStatus | Onboarding, Active, Pause, Failed |
GET /v1/conversion/securities/issue-types and GET /v1/conversion/securities/issue-subtypes accept no query parameters and publish no input enumerations; each returns the full reference list.
const [securitiesResponse, issueTypesResponse, issueSubTypesResponse] = await Promise.all([
fetch(`${baseUrl}/v1/conversion/securities?offset=0&count=25`, { headers: { 'Authorization': `Bearer ${access_token}` } }),
fetch(`${baseUrl}/v1/conversion/securities/issue-types`, { headers: { 'Authorization': `Bearer ${access_token}` } }),
fetch(`${baseUrl}/v1/conversion/securities/issue-subtypes`, { headers: { 'Authorization': `Bearer ${access_token}` } })
]);
const securities = await securitiesResponse.json();[
{
"id": "security-id",
"cusip": "123456789",
"issuerName": "Example Issuer",
"security": "Example Security",
"securitySymbol": "EX",
"status": "Active",
"tokens": [{ "ledgerId": "ledger-id", "name": "Token", "ledger": { "name": "Ethereum", "network": "Ethereum" } }],
"restrictions": {
"doChill": { "enabled": false, "updatedAt": null },
"complianceLock": { "enabled": false, "updatedAt": null },
"globalLock": { "enabled": false, "updatedAt": null },
"transferLock": { "enabled": false, "updatedAt": null }
}
}
]interface EligibleSecurityApiModel {
id: string;
cusip: string;
issuerName: string;
security: string;
securitySymbol: string;
issueType: IssueType;
issueSubType: IssueType;
tokens: EligibleSecurityToken[];
status: string;
trackingTrancheId: string;
restrictions: SecurityRestrictions;
}
interface IssueType { id: string; code: string; description: string; }
interface SecurityRestrictions {
doChill: RestrictionState;
globalLock: RestrictionState;
complianceLock: RestrictionState;
transferLock: RestrictionState;
}
interface RestrictionState { enabled: boolean; updatedAt: string | null; }The securities response includes embedded token and ledger network associations, reducing the need for per-security lookup calls. Issue type, issue sub-type, and network are independent filter dimensions.
All eligible securities carry an Active status, but a security can be Active and still have a chill or lock in place. A chill or lock is a transfer restriction: while it is in effect, transfers of the security's tokens are blocked across the entire security (all of its tokens), not just a single account or wallet. When the restriction is lifted, transfers are allowed again. Confirming that status is Active is not enough to know a security is usable right now; you must also read the restrictions object on the same response.
The restrictions object is always present and always reports all four restriction types. Each type is an object with an enabled flag (true when the restriction is currently in effect) and an updatedAt timestamp (UTC) recording when it last changed, or null if it has never applied. Because every type is always present, always test the enabled flag rather than checking whether a field exists.
| Field | Restriction | What it means |
|---|---|---|
doChill | Delivery Order (DO) Chill | A temporary restriction on transfers, typically while a settlement or verification is pending. |
globalLock | Global Lock | A block on all transfers of the token, typically during a corporate action or a regulatory investigation. |
complianceLock | Compliance Lock | A block on transfers imposed for regulatory or compliance reasons, for example a sanctions concern. |
transferLock | Transfer Lock | A block on transfers of the token imposed at the security level, independent of the chill, global lock, and compliance lock signals. |
restrictions object and check each type for "enabled": true. If any of the four is enabled, the security's token transfers are currently restricted even when status is Active. Use the updatedAt value on the enabled restriction to see when that chill or lock was last applied. Restriction state can change at any time as upstream events are processed, so poll the endpoint and re-read restrictions when you need a current view."status": "Active",
"restrictions": {
"doChill": { "enabled": false, "updatedAt": null },
"complianceLock": { "enabled": false, "updatedAt": null },
"globalLock": { "enabled": true, "updatedAt": "2026-09-25T14:03:00Z" },
"transferLock": { "enabled": false, "updatedAt": null }
}typescript · checking for a restrictionfunction isRestricted(security) {
const r = security.restrictions;
return r.doChill.enabled || r.globalLock.enabled || r.complianceLock.enabled || r.transferLock.enabled;
}
// Active status alone is not sufficient; also confirm no restriction is enabled.
const usable = security.status === 'Active' && !isRestricted(security);If securities fail to load, show an error state. If issue type, issue sub-type, or ledger reference data fails, disable the corresponding filter while still rendering the securities list.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Malformed request or invalid query parameter | Correct the request. Do not retry as-is. |
| 401 | JWT access credential missing, expired, or invalid | Request a new JWT access credential, then retry once. |
| 403 | Service account lacks the required permission, or the account is locked | Surface access denied. Do not retry. |
| 404 | Resource not found | Surface not found. Do not retry. |
| 500, 503 | Service failure | Retry with exponential backoff, maximum three attempts. Disable only the affected filter rather than the whole view. |
All four endpoints are read-only GETs and safe to retry on 5xx or network timeout.
Loads order-entry inputs in parallel and filters wallets to Idle state.
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| status | query | string | Optional | Active |
| Offset / Count | query | integer | Optional | Pagination controls |
GET /v1/conversion/securities
| Direction | Parameter / Field | Enum Name | Values |
|---|---|---|---|
| Input (query) | orderBy | FinancialSecurityFields | CUSIP, Description, Issuer |
| Input (query) | sortOrder | SortOrder | Ascending, Descending |
| Output (response) | status | FinancialSecurityStatus | Onboarding, Active, Pause, Failed |
GET /v1/conversion/wallets
| Direction | Parameter / Field | Enum Name | Values |
|---|---|---|---|
| Input (query) | orderBy | WalletFields | Name, Network, CreatedAt |
| Input (query) | sortOrder | SortOrder | Ascending, Descending |
| Output (response) | type | WalletTypes | Internal, Client |
| Output (response) | state | ProcessingStates | Idle, Registering, Deleting, FailedCompliance, Failed |
const [securitiesResponse, walletsResponse] = await Promise.all([
fetch(`${baseUrl}/v1/conversion/securities?status=Active`, { headers: { 'Authorization': `Bearer ${access_token}` } }),
fetch(`${baseUrl}/v1/conversion/wallets`, { headers: { 'Authorization': `Bearer ${access_token}` } })
]);
const securities = await securitiesResponse.json();
const wallets = await walletsResponse.json();
const eligibleWallets = wallets.filter(w => w.state === 'Idle');{
"securities": [
{ "id": "security-id", "cusip": "123456789", "issuerName": "Example Issuer", "security": "Example Security", "status": "Active" }
],
"wallets": [
{ "id": "wallet-id", "name": "Example Wallet", "type": "Internal", "network": "DTC_Classic", "walletAddress": "0x...", "state": "Idle", "trackingWalletId": "tracking-wallet-id", "account": { "name": "Client X", "externalId": "external-id" }, "conversionEligible": true, "failureReason": null }
]
}interface Security {
id: string;
cusip: string;
issuerName: string;
security: string;
securitySymbol?: string;
issueType: IssueType;
issueSubType: IssueType;
status: string;
trackingTrancheId: string;
}
interface WalletSummary {
id: string;
name: string;
type: string;
network: string;
walletAddress: string;
state: string;
trackingWalletId: string;
account: AccountDetails;
conversionEligible: boolean;
failureReason: string | null;
}Only Active securities are eligible for orders. A wallet is eligible as a source or destination candidate only when its processing state is Idle and conversionEligible is true. Both conditions must hold; an Idle wallet that is not conversion eligible must be excluded.
An Active status is necessary but not sufficient. A security can be Active and still carry a chill or lock, which blocks transfers of its tokens while the restriction is in effect. Before treating an Active security as usable, read its restrictions object and confirm that doChill, globalLock, complianceLock, and transferLock all report "enabled": false. See the List Registered Securities and Filter Data card for the full restriction model.
Handle 401 by requesting a new JWT access credential and retrying once; handle 5xx with retry and an error state. If no Active security or no Idle wallet is returned, block order submission rather than submitting an ineligible order.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Malformed request or invalid query parameter | Correct the request. Do not retry as-is. |
| 401 | JWT access credential missing, expired, or invalid | Request a new JWT access credential, then retry once. |
| 403 | Service account lacks the required permission, or the account is locked | Surface access denied. Do not retry. |
| 404 | Resource not found | Surface not found. Do not retry. |
| 500, 503 | Service failure | Retry with exponential backoff, maximum three attempts. Block order submission until inputs load successfully. |
Both calls are read-only GETs and safe to retry on 5xx or network timeout.
Prior to submitting a conversion order, we recommend to retrieve and check the wallet and securities from the appropriate endpoints.
Submission is asynchronous. POST /v1/conversion/orders returns 202 Accepted with no response body, so the order identifier is not available on the submission response. Retain the X-Idempotency-Key supplied at submission, poll POST /v1/conversion/async-operations/query with that key until resourceId is populated, then retrieve the order from GET /v1/conversion/orders/{orderId}. Orders are processed straight through, entering Processing and settling at Completed.
GET /v1/conversion/orders
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| searchFor | query | string | Optional | Free-text search key filter |
| fromWallet | query | string | Optional | Source wallet identifier filter |
| toWallet | query | string | Optional | Destination wallet identifier filter |
| updateFrom / updateTo | query | string | Optional | Lower and upper bounds of the update date range |
| ids | query | array | Optional | Filter by specific order identifiers |
| financialSecurityIds | query | array | Optional | Filter by security identifiers |
| status | query | array | Optional | Filter by order status |
| origin | query | array | Optional | Filter by how the order was originated |
| includeObac | query | boolean | Optional | Include access control metadata when true |
| orderBy / sortOrder | query | string | Optional | Sorting controls |
| Offset / Count | query | integer | Optional | Pagination controls |
POST /v1/conversion/orders
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| X-Idempotency-Key | header | string | Yes | Max 255 characters; prevents duplicate submissions. Retain this value for the async operation query. |
| financialSecurityId | body | string | Yes | Security being converted |
| fromWalletId | body | string | Yes | The source account or wallet from which the position will be debited. For Classic accounts, the format is {participantId}-10 (Free NA) or {participantId}-11 (Free MA), for example 00002667-10. For digital wallets, this is the registered blockchain wallet address. |
| toWalletId | body | string | Yes | The destination account or wallet to which the converted position will be credited. For Classic accounts, the format is {participantId}-10 (Free NA) or {participantId}-11 (Free MA), for example 00002667-10. For digital wallets, this is the registered blockchain wallet address. |
| activityType | body | string | Yes | MemoSeg reduction reason code indicating how the conversion affects the participant's segregated position. Code 040 reduces (debits) the MemoSeg quantity; code 098 leaves the MemoSeg position unchanged. |
| quantity | body | integer (int32) | Yes | Amount to convert; must be greater than zero |
POST /v1/conversion/async-operations/query
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| idempotencyKeys | body | array | Yes | One or more idempotency keys retained from prior submissions. The field accepts an array and the server processes all keys supplied in a single query. As a best practice, submit no more than 100 keys per request. See the Batch Query Behavior section below. |
| Offset / Count | body | integer | Yes | Pagination controls; both are required on this request body. |
| orderBy | body | string (enum) | Yes | Field to sort by. Accepts the AsyncOperationOrderFields value CreatedAt. |
| sortOrder | body | string (enum) | Yes | Sort direction. See SortOrder allowed values: Ascending, Descending. |
GET /v1/conversion/orders/{orderId}
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| orderId | path | string | Yes | Order identifier, taken from resourceId on the async operation response |
The idempotencyKeys field on POST /v1/conversion/async-operations/query accepts an array, and the server processes all keys supplied in a single query. As a best practice, submit no more than 100 idempotency keys per request; submitting very large arrays in a single request may impact performance.
| Behavior | Detail |
|---|---|
| Unmatched keys | Submitting keys for operations that do not exist does not return an error; the response contains only the records that matched. For example, submitting 10 keys where only 5 have corresponding operations returns a list of 5 results, with no indication of which keys were unmatched. |
| Pagination | The response is paginated. Even for a large number of submitted keys, the number of records returned per page is controlled by the Count and Offset parameters. When the number of matching results exceeds the Count value, page through the results to retrieve them all. |
| Recommended batch size | Submit no more than 100 keys per request to avoid the performance impact of very large arrays. |
GET /v1/conversion/orders
| Direction | Parameter / Field | Enum Name | Values |
|---|---|---|---|
| Input (query) | orderBy | OrderFields | CreatedAt, UpdatedAt |
| Input (query) | sortOrder | SortOrder | Ascending, Descending |
| Input (query) | status | OrderStatus | Processing, Completed, Failed |
| Input (query) | origin | OrderOrigin | Participant, Admin, ForcedReconversion |
| Output (response) | status | OrderStatus | Processing, Completed, Failed |
| Output (response) | origin | OrderOrigin | Participant, Admin, ForcedReconversion |
POST /v1/conversion/async-operations/query
| Direction | Parameter / Field | Enum Name | Values |
|---|---|---|---|
| Input (body) | orderBy | AsyncOperationOrderFields | CreatedAt |
| Input (body) | sortOrder | SortOrder | Ascending, Descending |
| Output (response) | objectKind | ObjectKind | Undefined, Order, Wallet, FinancialSecurity |
| Output (response) | status | AsyncOperationStatus | New, Processing, Completed, Failed |
| Output (response) | operationName | OperationName | Undefined, Register, Submit, Import |
GET /v1/conversion/orders/{orderId}
| Direction | Parameter / Field | Enum Name | Values |
|---|---|---|---|
| Output (response) | status | OrderStatus | Processing, Completed, Failed |
| Output (response) | origin | OrderOrigin | Participant, Admin, ForcedReconversion |
The submission endpoint POST /v1/conversion/orders returns no response body, so it publishes no response enumerations. The tables above cover the three calls that read order state.
GET /v1/conversion/orders
const query = new URLSearchParams();
query.set('fromWallet', sourceWallet.id);
query.set('toWallet', destinationWallet.id);
// status and financialSecurityIds are array-typed filters; append each value separately
['Processing'].forEach(s => query.append('status', s));
[selectedSecurity.id].forEach(id => query.append('financialSecurityIds', id));
query.set('offset', '0');
query.set('count', '20');
const ordersResponse = await fetch(`${baseUrl}/v1/conversion/orders?${query}`, {
headers: { 'Authorization': `Bearer ${access_token}` }
});
const existingOrders: OrderResponse[] = await ordersResponse.json();POST /v1/conversion/orders
const idempotencyKey = generateIdempotencyKey();
const orderResponse = await fetch(`${baseUrl}/v1/conversion/orders`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${access_token}`,
'Content-Type': 'application/json',
'X-Idempotency-Key': idempotencyKey
},
body: JSON.stringify({
financialSecurityId: selectedSecurity.id,
fromWalletId: sourceWallet.id,
toWalletId: destinationWallet.id,
activityType: '040',
quantity: 500
})
});
// 202 Accepted with no response body. Retain idempotencyKey for the async query.
if (orderResponse.status !== 202) {
throw new Error('Conversion order was not accepted');
}POST /v1/conversion/async-operations/query
const asyncResponse = await fetch(`${baseUrl}/v1/conversion/async-operations/query`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${access_token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
idempotencyKeys: [idempotencyKey],
orderBy: 'CreatedAt',
sortOrder: 'Descending',
offset: 0,
count: 10
})
});
const operations: AsyncOperationResponse[] = await asyncResponse.json();
const orderId = operations[0]?.resourceId;GET /v1/conversion/orders/{orderId}
const detailResponse = await fetch(`${baseUrl}/v1/conversion/orders/${orderId}`, {
headers: { 'Authorization': `Bearer ${access_token}` }
});
const orderDetail: OrderDetailResponse = await detailResponse.json();
// orderDetail.status === 'Processing'GET /v1/conversion/orders
[
{
"id": "order-id",
"symbol": "EXMPL",
"cusip": "037833100",
"fromWallet": { "id": "source-wallet-id", "name": "Participant Classic Account", "walletAddress": "00002667-10", "network": "DTC_Classic" },
"toWallet": { "id": "destination-wallet-id", "name": "First Bank EVM Wallet", "walletAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "network": "Besu" },
"quantity": 500,
"status": "Processing",
"errorMessage": null,
"createdAt": "2026-01-01T00:00:00Z",
"obac": { "isController": true, "isShared": false, "hasShareRequest": false },
"activityType": "040",
"updatedAt": "2026-01-01T00:00:00Z",
"origin": "Participant"
}
]POST /v1/conversion/orders returns 202 Accepted with an empty body.
POST /v1/conversion/async-operations/query
[
{
"id": "async-operation-id",
"idempotencyKey": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
"objectKind": "Order",
"status": "Completed",
"operationName": "Submit",
"resourceId": "order-id",
"resourceUrl": "/v1/conversion/orders/order-id",
"errorCode": null,
"errorMessage": null,
"asOfDate": "2026-01-01T00:00:00Z"
}
]GET /v1/conversion/orders/{orderId}
{
"orderId": "order-id",
"participant": { "id": "participant-id", "name": "First Bank" },
"financialSecurityInfo": { "id": "security-id", "cusip": "037833100", "symbol": "EXMPL", "status": "Active" },
"fromWallet": { "id": "source-wallet-id", "name": "Participant Classic Account", "walletAddress": "00002667-10", "network": "DTC_Classic" },
"toWallet": { "id": "destination-wallet-id", "name": "First Bank EVM Wallet", "walletAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "network": "Besu" },
"quantity": 500,
"submittedBy": "SA-ConversionBot",
"submitterEmail": null,
"submitterComment": null,
"status": "Completed",
"errorMessage": null,
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:05:00Z",
"activityType": "040",
"fromTransactionId": "0x639dc5a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d",
"toTransactionId": "12200cc6f1e2d3c4b5a69788796a5b4c3d2e1f00998877665544332211aabbccdd",
"check": { "id": "check-id", "approvedBy": null, "approverEmail": null, "approverComment": null },
"origin": "Participant"
}While an order is in Processing, both fromTransactionId and toTransactionId are null. They are populated with the on-chain ledger transaction hashes once the order reaches Completed and the underlying ledger events settle. See the Transaction Identifiers section below for field-level semantics.
The order detail response (GET /v1/conversion/orders/{orderId}) is the only endpoint that exposes the on-chain transaction identifiers for a conversion. The orders list endpoint (GET /v1/conversion/orders) does not return these fields.
| Field | Contains |
|---|---|
fromTransactionId | The on-chain ledger transaction hash for the source (debit) leg of the conversion — for example, a Burn on Besu such as 0x639dc5.... |
toTransactionId | The on-chain ledger transaction hash for the destination (credit) leg of the conversion — for example, a Mint on Canton such as 12200cc6.... |
Both fields are null until the order settles, then carry the ledger-native transaction hash for their respective leg. The hash format follows the convention of the underlying network (for example, a 0x-prefixed 32-byte hex string on Besu/EVM networks). Because a conversion moves between a DTC Classic account and a digital wallet, only the digital-wallet leg corresponds to a blockchain transaction; the DTC Classic leg (identifiers in the {participantId}-10 / {participantId}-11 format) is not an on-chain event, so the transaction identifier that carries an on-chain hash depends on the conversion direction.
fromTransactionId or toTransactionId returned here, because both systems independently report the same underlying chain data. Providers that expose an internal reference rather than the raw on-chain hash will not match directly; compare against the on-chain hash surfaced by the provider.interface OrderResponse {
id: string;
symbol?: string;
cusip?: string;
fromWallet: WalletRefResponse;
toWallet: WalletRefResponse;
quantity: number;
status: string;
errorMessage?: string;
createdAt: string;
obac?: AccessControlInfoResponse;
activityType?: string;
updatedAt?: string;
origin?: string;
}
interface AsyncOperationResponse {
id: string;
idempotencyKey: string;
objectKind: string;
status: string;
operationName: string;
resourceId?: string;
resourceUrl?: string;
errorCode?: string;
errorMessage?: string;
asOfDate: string;
}
interface OrderDetailResponse {
orderId: string;
participant: ParticipantResponse;
financialSecurityInfo?: OrderFinancialSecurityInfo;
fromWallet: WalletRefResponse;
toWallet: WalletRefResponse;
quantity: number;
submittedBy?: string;
submitterEmail?: string;
submitterComment?: string;
status: string;
errorMessage?: string;
createdAt: string;
updatedAt?: string;
activityType?: string;
fromTransactionId?: string;
toTransactionId?: string;
check: CheckInfoResponse;
origin?: string;
}
interface CheckInfoResponse {
id: string;
approvedBy?: string;
approverEmail?: string;
approverComment?: string;
}
interface OrderFinancialSecurityInfo {
id: string;
cusip: string;
symbol?: string;
status: string;
}Conversion direction must move between DTC_Classic and non-Classic wallets. Orders can be submitted Monday-Friday, 02:00-18:00 ET, with operational-hours enforcement server-side. Query the orders list before submitting to detect whether a prior submission with the same intent already exists, filtering on fromWallet, toWallet, financialSecurityIds, or status.
Handle 400 validation errors, 403 permission or lockout failures, 409 duplicate idempotency key, 422 business rule violations, and 5xx server errors. Submission does not execute the conversion synchronously; a 202 Accepted response confirms only that the order was queued for processing. Treat an async operation status of Failed as a submission failure and surface errorCode and errorMessage.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Malformed request, missing X-Idempotency-Key, quantity of zero, or wallet identifier not found see Error Code Reference below | Correct the request. Do not retry as-is. |
| 401 | JWT access credential missing, expired, or invalid | Request a new JWT access credential, then retry once. |
| 403 | Service account lacks the required permission, or the account is locked | Surface access denied. Do not retry. |
| 404 | Security or order identifier not found see Error Code Reference below | Surface not found. Do not create a replacement order. |
| 409 | Duplicate X-Idempotency-Key, or a conflicting wallet already exists see Error Code Reference below | Treat the order as already submitted. Query the async operation with the same key to resolve the existing order identifier. |
| 422 | Business rule violation such as invalid conversion direction, ineligible security, ineligible wallet, or submission outside operational hours | Surface the specific rule violation. Do not retry until the input is corrected. |
| 500 | Unhandled or infrastructure failure see Error Code Reference below | Not retryable without platform investigation. Surface the failure and escalate. |
| 503 | Service failure | Retry with the same X-Idempotency-Key, maximum three attempts. |
Some error responses include a machine-readable errorCode that pinpoints the specific cause beyond the HTTP status. The tables below enumerate the codes returned for HTTP 400, 404, 409, and 500. Not every error response carries a specific code — responses without one are fully described by the summary table above.
Each entry lists the returned errorCode, the condition that triggers it, and the recommended correction.
| Error Code | Cause | Correction |
|---|---|---|
ConversionOperationsEngine__InvalidQuantity | quantity ≤ 0. | Submit with a positive quantity. |
ConversionOperationsEngine__SameOrderWallets | fromWalletId and toWalletId are identical. | Use two distinct wallet IDs. |
ConversionOperationsEngine__SameWalletLedgers | Both wallets are on the same network. | Use wallets on different networks. |
ConversionOperationsEngine__WalletIsNotConversionEligible | The wallet has conversionEligible = false. | Use a wallet that has completed registration and is marked eligible. |
ConversionOperationsEngine__OperationCannotBePerformed | The wallet's processingState is not Idle. | Wait for wallet registration to complete before submitting. |
ConversionOperationsEngine__OrderFinancialInstrumentRequired | financialSecurityId was not provided. | Include financialSecurityId in the request body. |
ConversionOperationsEngine__InactiveFinancialSecurityOrderCreatingException | The referenced security is not in Active status. | Use an active security. |
ConversionOperationsEngine__OutsideAllowedTimeWindow | Request submitted outside operational hours or on a holiday. | Resubmit during the operational window. |
ConversionOperationsEngine__InvalidOrderActivityType | activityType is not a supported value. | Use a supported activity type code. |
ConversionOperationsEngine__InvalidWalletAddress | The wallet address is not valid for the specified network. | Correct the address format. |
ConversionOperationsEngine__WalletNotFound | The wallet ID does not exist or is not accessible to your tenant. | Verify the wallet ID. |
| Error Code | Cause | Correction |
|---|---|---|
ConversionOperationsEngine__OrderNotFound | The order ID does not exist or is not accessible. | Verify the order ID. |
ConversionOperationsEngine__FinancialSecurityNotFound | The financialSecurityId does not exist. | Verify the financial security ID. |
| Error Code | Cause | Correction |
|---|---|---|
AsyncOperation__AsyncOperationAlreadyExists | The idempotency key was already used and the original request succeeded. | Query async operations with the key to retrieve the existing order ID. Do not resubmit. |
ConversionOperationsEngine__WalletAlreadyExists | A wallet with the same address and network already exists in your tenant. | Use the existing wallet or register with a different address. |
ConversionOperationsEngine__WalletWithSameNameAlreadyExist | A wallet with the same name already exists in your tenant. | Choose a different wallet name. |
Unhandled or infrastructure failures. The errorCode value is "500". Not retryable without platform investigation.
When a delivery order fails due to a NACK, the platform returns one of the error codes below, grouped into higher-level buckets by concern. The Field column identifies the specific element that triggered the rejection. Separately, when a delivery order is submitted to ATP it carries a status code indicating its processing outcome.
6 buckets · 90 codes. Click a bucket to expand, or type to filter.
| Error Code | Field | Explanation |
|---|---|---|
CAAL-9AAA | Receiving Participant | The receiving participant is invalid. |
CAAL-9AAL | Receiving Participant | Past cutoff refer to documentation |
CAAL-9AAN | Receiving Participant | Not eligible for processing |
CAAL-9AAU | Receiving Participant | Chilled for SDFS valued DO(s) |
CAAL-9AAW | Receiving Participant | Chilled for SDFS free DO(s) |
CAAL-9AAY | Receiving Participant | Not SDFS eligible |
CAAL-9ABB | Receiving Participant | Not Found |
CAAL-9ABD | Receiving Participant | Missing |
CAAL-9ACK | Receiving Participant | Global lock |
CAAL-9ACQ | Receiving Participant | Chilled for MMI securities |
CAAL-9ACS | Receiving Participant | Only eligible for MMI securities |
CAAL-9AFT | Receiving Participant | Receiving participant mismatch. Receiver is 881 for SFT Stock Loans |
CAAL-IAEM | Receiving Participant | Not OCC hedge eligible |
CAAM-9AAA | Delivering Participant | The delivering participant is invalid. |
CAAM-9AAE | Delivering Participant | Invalid data refer to documentation |
CAAM-9AAU | Delivering Participant | Chilled for SDFS valued DO(s) |
CAAM-9AAW | Delivering Participant | Chilled for SDFS free DO(s) |
CAAM-9AAY | Delivering Participant | Not SDFS eligible |
CAAM-9ABB | Delivering Participant | Not found on Master Tables |
CAAM-9ABD | Delivering Participant | Missing |
CAAM-9ACK | Delivering Participant | Global lock |
CAAM-9ACQ | Delivering Participant | Chilled for MMI securities |
CAAM-9ACS | Delivering Participant | Only eligible for MMI securities |
CAAM-IAEM | Delivering Participant | Not OCC hedge eligible |
CAAU-9AAA | ID Agent | Invalid |
CAAU-9ABB | ID Agent | ID Agent Not Found in IPO Database |
CABB-9AAA | Customer | Default Can Affect Future Do |
CABB-9ABE | Customer | Internal Customer Is Required |
CABB-9ABZ | Customer | Internal Customer Not in IPO Database |
CABE-9AAA | Internal Account Number | Invalid |
CABL-9AAA | Correspondent Account | Invalid |
CABL-9ABE | Correspondent Account | Required |
CAGX-9ABD | Deliverer Account ID | Missing |
CAGY-9ABD | Receiver Account ID | Missing |
CRCF-9AAA | Depository Third Party | Invalid |
| Error Code | Field | Explanation |
|---|---|---|
GAAA-9AAA | CUSIP | Invalid |
GAAA-9AAH | CUSIP | Data equal to zero |
GAAA-9AAI | CUSIP | Invalid format Bonds for CNS must be round lot |
GAAA-9AAL | CUSIP | Past cutoff-refer to documentation |
GAAA-9AAN | CUSIP | Not eligible for processing |
GAAA-9ABB | CUSIP | Not Found on DTC Master Table |
GAAA-9ABD | CUSIP | Missing |
GAAA-9ACK | CUSIP | Global lock |
GAAA-9ACN | CUSIP | Chilled |
GAAA-IAEM | CUSIP | Not OCC hedge eligible |
GAAA-IAEN | CUSIP | Not RAD eligible |
GAHT-9AAA | Obligation Warehouse Control Number | Invalid |
JAAM-IAEN | MMI Input Record | Not RAD eligible |
| Error Code | Field | Explanation |
|---|---|---|
DAAD-9AAA | IPO calculation | Invalid Price per Share or Net Amount |
DAAS-9AAA | Fractional Shares Quantity (IPO Verification) | Invalid |
DAAT-9AAH | Settlement Amount | For valued DOs, must be > zero. |
DAAT-9AAL | Settlement Amount | Past cutoff-refer to documentation |
DAAT-9ACG | Settlement Amount | Must equal 0 |
DAAT-IAEM | Settlement Amount | Not OCC hedge eligible |
DABB-9AAA | Shares Quantity | Invalid |
DABB-9AAF | Shares Quantity | Non-numeric data |
DABB-9AAH | Shares Quantity | Data equal to zero-(returned by IPO verification). Must be >zero. |
DABB-9AA2 | Shares Quantity | Greater than 50,000,000 for valued DO(s) |
DABB-9ACP | Shares Quantity | Insufficient position |
DABB-9ADH | Shares Quantity | Less than minimum denomination |
DABB-9AAI | Shares Quantity | Not multiple of 1000 (CNS bond deliveries) |
| Error Code | Field | Explanation |
|---|---|---|
BAAA-9AAA | Settlement Date | Invalid |
BAAA-9AAF | Settlement Date | not numeric |
BAAA-9AAJ | Settlement Date | not valid at cross border depository |
BAAA-9ABD | Settlement Date | Missing |
BAAA-9ABL | Settlement Date | Greater than Current Date |
BAAB-9ABE | Trade Date | Required |
BAAB-9AAF | Trade Date | not numeric |
| Error Code | Field | Explanation |
|---|---|---|
CAGN-9ABB | Transaction Number | Not found |
CAGN-IAEM | Transaction Number | Not OCC hedge eligible |
CAGN-MAAD | Transaction Number | Maturity date is less than current date |
CAHM-9ABD | Customer Reference Number | Missing |
CAHN-9AAA | Partner Reference Number | Invalid |
EAAP-9AAA | Money Indicator (IPO) | Invalid |
EABF-9AAA | Sell/Buy Ind | Invalid |
EABF-9AAE | Sell/Buy Ind | Invalid data-refer to documentation |
EABG-9AAE | CDO Indicator | Invalid data-refer to documentation |
GACA-9AAA | Activity Code | Invalid-must be 026 |
GACA-IAEL | Activity Code | IPO Activity Code Invalid (IPOVFYOC) |
GAHL-9AAA | Reason Code | Invalid |
GAHL-9AAE | Reason Code | Invalid data-refer to documentation |
GAHL-9AAF | Reason Code | Non-numeric data |
GAHL-9AFT | Reason Code | Reason Code Mismatch. |
GAHL-9AFF | Reason Code | Reason Code Invalid Data. |
| Error Code | Field | Explanation |
|---|---|---|
CABC-9AAA | IPO Verification | Invalid IDS Link Time |
EAAA-9AAA | Merrill to Merrill DO for IPO Issue | Invalid |
EAE3-9AAA | IDS Trade Ind (IPO) | Invalid |
GAHO-0004 | Other | Reference Key must be alphanumeric. |
GAHO-9AAI | Other | Reference Key Invalid Format–refer to documentation on Comments field position 502-721. |
GAHO-9AEL | Other | Reference Key Missing or Invalid. Comments are required in the first 17 characters of the field. |
| Status Code | Description | Status |
|---|---|---|
RJCI | Rejected in IMS | Failed |
RJCT | Rejected in ATP | Failed |
PDRP | Dropped in ATP, due to position validation | Failed |
XPER | Failed due to insufficient position | Failed |
CANA | Cancelled in ATP | Failed |
CANC | Cancelled in IMS | Failed |
CANS | Cancelled in staging area | Failed |
INEL | InEligible | Failed |
UNPR | Unprocessed | Failed |
PDRI | IMS Permanently Dropped | Failed |
RDPR | Dropped by ATP To Be Reintroduced | Failed |
RJCF | IMS Rejected to File | Failed |
DATP | PDC Reduction Dropped in ATP | Failed |
The submission POST is protected by X-Idempotency-Key. Retrying with the same key is safe and will not create duplicate orders. Do not generate a new key on retry, because the key is also the lookup value for the async operation query. The async operation query and the order detail retrieval are read-only and safe to retry.
Demonstrate that a customer integration can execute the complete conversion order lifecycle: authenticate with the Service Account Credentials grant, load order, security, and wallet reference data, validate security and wallet eligibility, submit a conversion order, enforce idempotency controls, track asynchronous processing, correlate the async operation to the resulting order, retrieve final order detail, monitor lifecycle progression, and reconstruct the transaction audit trail. Unlike Account Management and Wallet Management, this certification validates both retrieval operations and transactional business processes.
Authenticate, load reference data in parallel, validate eligibility, submit, then track the order asynchronously to a terminal state.
Service Account Credentials grant against /connect/token.
Orders, securities, and wallets in parallel, plus issue type, issue sub-type, and ledger filters.
Security status equals Active.
Wallet state equals Idle and conversionEligible is true.
POST /v1/conversion/orders returns 202 Accepted with no body.
Query by X-Idempotency-Key until a terminal status.
resourceId resolves the order identifier.
GET /v1/conversion/orders/{orderId}.
Processing to Completed, then reconstruct the audit trail.
| Rule | Requirement |
|---|---|
| Security Eligibility | Known security states are Onboarding, Active, Pause, and Failed. Only Active securities are eligible for conversion-order creation. |
| Wallet Eligibility | Known wallet states are Idle, Registering, Deleting, FailedCompliance, and Failed. Only wallets that are Idle and conversion eligible may be used. |
| Conversion Direction | Conversion must occur between DTC Classic and digital wallets. |
| Quantity Validation | Quantity must be greater than zero. |
| Idempotency | Every submission must include X-Idempotency-Key. The same key must remain traceable throughout asynchronous processing. |
| Asynchronous Processing | Order creation returns HTTP 202 Accepted. Completion is determined through async operation tracking, not from the submission response. |
| Operational Hours | Monday to Friday, 02:00 ET to 18:00 ET. Enforcement is server-side. |
const tenantName = "<tenant-name>"; // recommended, e.g. "DTCC-DA"
const baseUrl = "<base-url>";
const username = "SA-ConversionBot";
const password = process.env.SERVICE_ACCOUNT_PASSWORD!;async function authenticate() {
const response = await fetch(`${baseUrl}/connect/token`, {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "urn:dtcc:params:oauth:grant-type:service-account-credentials",
type: "conveyance",
entity: ENTITY_ID_OF_WHICH_SA_IS_MEMBER_OF,
acr_values: `tenant:${tenantName}`,
username,
password
})
});
if (!response.ok) {
throw new Error(`Authentication failed: ${response.status}`);
}
const data = await response.json();
return data.access_token;
}
async function loadReferenceData(accessToken: string) {
const [ordersResponse, securitiesResponse, walletsResponse] = await Promise.all([
fetch(`${baseUrl}/v1/conversion/orders`, { headers: { Authorization: `Bearer ${accessToken}` } }),
fetch(`${baseUrl}/v1/conversion/securities`, { headers: { Authorization: `Bearer ${accessToken}` } }),
fetch(`${baseUrl}/v1/conversion/wallets`, { headers: { Authorization: `Bearer ${accessToken}` } })
]);
return {
orders: await ordersResponse.json(),
securities: await securitiesResponse.json(),
wallets: await walletsResponse.json()
};
}
async function loadFilterData(accessToken: string) {
const [issueTypesResponse, issueSubTypesResponse] = await Promise.all([
fetch(`${baseUrl}/v1/conversion/securities/issue-types`, { headers: { Authorization: `Bearer ${accessToken}` } }),
fetch(`${baseUrl}/v1/conversion/securities/issue-subtypes`, { headers: { Authorization: `Bearer ${accessToken}` } })
]);
return {
issueTypes: await issueTypesResponse.json(),
issueSubTypes: await issueSubTypesResponse.json()
};
}
function generateIdempotencyKey() {
return crypto.randomUUID();
}
async function queryOperation(accessToken: string, idempotencyKey: string) {
const response = await fetch(`${baseUrl}/v1/conversion/async-operations/query`, {
method: "POST",
headers: {
Authorization: `Bearer ${accessToken}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ idempotencyKeys: [idempotencyKey], orderBy: "CreatedAt", sortOrder: "Descending", offset: 0, count: 10 })
});
const [operation] = await response.json();
return operation;
}
async function getOrder(accessToken: string, orderId: string) {
const response = await fetch(`${baseUrl}/v1/conversion/orders/${orderId}`, {
headers: { Authorization: `Bearer ${accessToken}` }
});
if (!response.ok) {
throw new Error(`Order retrieval failed with status ${response.status}`);
}
return response.json();
}Verify that the integration can obtain an access credential using the Service Account Credentials grant. The credential proves the caller's identity and must be supplied as a bearer credential on every subsequent call in this workflow.
const accessToken = await authenticate();The token response returns access_token, token_type, and expires_in; the helper returns the access_token value, which is usable on a subsequent API call.
HTTP 200; credential issued and usable.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Invalid service account credentials or malformed grant request | Correct the credentials. Do not retry with the same values. |
| 403 | Service account lacks the required permission | Surface the permission failure. Do not retry. |
| 500, 503 | Identity service failure | Retry with exponential backoff, maximum three attempts. |
Verify that all prerequisite data loads successfully. Order, security, and wallet inventories supply the order inputs; issue type, issue sub-type, and ledger reference data supply the filter context.
const { orders, securities, wallets } = await loadReferenceData(accessToken);
const { issueTypes, issueSubTypes } = await loadFilterData(accessToken);Order inventory returned. Security inventory returned. Wallet inventory returned. Issue type reference data returned. Issue sub-type reference data returned. Ledger network data returned.
HTTP 200 on each call; all six data sets available for downstream steps.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 401 | Expired or invalid access credential | Re-authenticate, then retry once. |
| 403 | Service account lacks the required permission | Surface access denied. Do not retry. |
| 500, 503 | Service failure | Retry with exponential backoff. Each call fails independently, so present a partial state rather than blocking the whole load. |
Verify that a valid conversion security can be identified from the security inventory loaded in Step 2.
const security = securities.find(security => security.status === "Active");The security exists and carries CUSIP, issuer, issue type, issue sub-type, restrictions, and token network information. Status equals Active. Securities in Onboarding, Pause, or Failed status are not eligible.
Eligible security identified.
This step performs no API calls. If no Active security is found, the integration must block order submission rather than proceeding with an ineligible security.
Verify that suitable source and destination wallets can be selected from the wallet inventory loaded in Step 2.
const eligibleWallets = wallets.filter(
wallet => wallet.state === "Idle" && wallet.conversionEligible === true
);The wallet exists, state equals Idle, conversionEligible equals true, network information is present, and no failure state is set. A wallet that satisfies only one of the two eligibility conditions is not a valid candidate. Wallets in Registering, FailedCompliance, or Failed state are not eligible.
Eligible wallets identified.
This step performs no API calls. If no wallet is both Idle and conversion eligible, the integration must block order submission rather than proceeding with an ineligible wallet.
Verify that a conversion order can be submitted with a valid idempotency key and accepted for asynchronous processing.
const idempotencyKey = generateIdempotencyKey();
const response = await fetch(`${baseUrl}/v1/conversion/orders`, {
method: "POST",
headers: {
Authorization: `Bearer ${accessToken}`,
"Content-Type": "application/json",
"X-Idempotency-Key": idempotencyKey
},
body: JSON.stringify({
financialSecurityId: security.id,
fromWalletId: sourceWallet.id,
toWalletId: destinationWallet.id,
quantity: 100,
activityType: "040"
})
});HTTP 202 returned. The request is accepted and no validation error is returned. No response body is expected, so the order identifier is not available at this point. Retain idempotencyKey for the async operation query.
HTTP 202 Accepted with no response body.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Malformed request, missing X-Idempotency-Key, or quantity of zero | Correct the request. Do not retry as-is. |
| 403 | Service account lacks the required permission, or the account is locked | Surface access denied. Do not retry. |
| 409 | Duplicate X-Idempotency-Key | Treat the order as already submitted. Query the async operation with the same key to resolve the existing order. |
| 422 | Business rule violation such as invalid direction, ineligible security, ineligible wallet, or submission outside operational hours | Surface the specific rule violation. Do not retry until the input is corrected. |
| 500, 503 | Service failure | Retry with the same X-Idempotency-Key, maximum three attempts. |
Verify that resubmitting an identical request with the same idempotency key does not create a duplicate order.
Submit the same order request twice using the same X-Idempotency-Key.
A duplicate order is not created, idempotency is maintained, and the operation remains traceable under the original key.
Duplicate processing prevented.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 409 | Duplicate X-Idempotency-Key | Treat as already submitted. Reconcile against the existing order rather than resubmitting. |
| 400 | X-Idempotency-Key omitted entirely | Submission rejected. Add the header before retrying. |
Verify that asynchronous operations can be monitored using the idempotency key retained at submission.
const operation = await queryOperation(accessToken, idempotencyKey);The operation returns id, idempotencyKey echoing the submitted key, objectKind, status, operationName, and asOfDate. Known status values are New, Processing, Completed, and Failed. resourceId populates once processing begins.
HTTP 200; async operation successfully tracked.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 401 | Expired or invalid access credential | Re-authenticate, then retry once. |
| 500, 503 | Service failure | Retry with exponential backoff. The query is read-only and safe to repeat. |
Verify that an async operation can be correlated to the order it produced.
const operation = await queryOperation(accessToken, idempotencyKey);
const order = await getOrder(accessToken, operation.resourceId);resourceId is populated, resourceUrl is populated, the referenced order exists, and the order is retrievable.
HTTP 200; async operation successfully correlated to an order.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 404 | resourceId references an order that cannot be retrieved | Surface not found. Do not create a replacement order. |
| 500, 503 | Service failure | Retry with exponential backoff, maximum three attempts. |
Verify that final order detail can be accessed once the order identifier is known.
const orderDetail = await getOrder(accessToken, operation.resourceId);The response carries order identifier, status, participant information, transaction information, and audit timestamps.
HTTP 200; order detail successfully retrieved.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 401 | Expired or invalid access credential | Re-authenticate, then retry once. |
| 404 | Order identifier not found | Surface not found. Do not create a replacement order. |
| 500, 503 | Service failure | Retry with exponential backoff, maximum three attempts. |
Verify that lifecycle transitions can be monitored through to a terminal state.
Valid states are Processing, Completed, and Failed. Status progression is visible, a terminal state is reached, and the final state is recorded. Failed is terminal and must be surfaced with errorMessage rather than resubmitted.
HTTP 200; current order status returned and reportable.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 401 | Expired or invalid access credential | Re-authenticate, then retry once. |
| 404 | Order identifier not found | Surface not found. Do not create a replacement order. |
| 500, 503 | Service failure | Retry with exponential backoff, maximum three attempts. |
Verify that the complete transaction history can be reconstructed from the artifacts produced across the workflow.
The order identifier is traceable, the idempotency key is traceable, the async operation is traceable, audit timestamps are available, and transaction identifiers are available.
End-to-end audit trace established.
This step performs no additional API calls. It relies on the artifacts captured in Steps 5 through 10. If any link in the chain cannot be reconstructed, the audit trace is incomplete and the workflow must be treated as unverified.
Execute the complete workflow from authentication through audit validation in a single uninterrupted run.
Authentication PASS
Reference Data PASS
Security Validation PASS
Wallet Validation PASS
Order Submission PASS
Idempotency PASS
Async Tracking PASS
Correlation PASS
Order Retrieval PASS
Lifecycle PASS
Audit PASSEach constituent call returns its expected success code.
Complete workflow executed and every stage verified.
| ID | Scenario | HTTP | Expected result |
|---|---|---|---|
| NT-1 | Invalid service account credentials | 400 | Authentication rejected. |
| NT-2 | Invalid security | 422 | Order rejected. |
| NT-3 | Ineligible wallet | 422 | Order rejected. |
| NT-4 | Missing idempotency key | 400 | Request rejected. |
| NT-5 | Expired access credential | 401 | Authorization failure; re-authentication required. |
| NT-6 | Async processing failure | — | Async operation returns Failed status with errorCode and errorMessage present. Not an HTTP error condition. |
| NT-7 | Invalid order retrieval | 404 | Order not found; error handled without creating a replacement order. |
| NT-8 | Service unavailable | 503 | Retry attempted, failure reported, workflow stops safely. |
The customer must demonstrate authentication, reference-data retrieval, active-security validation, wallet eligibility validation covering both idle state and the conversion-eligible flag, conversion-order submission, idempotency compliance, async-operation monitoring, async-to-order correlation, final-order retrieval, lifecycle monitoring, audit validation, required negative-test handling, and end-to-end workflow execution.
Corporate Actions workflows support discovery, filtering, and detail inspection of corporate action events. The initial load retrieves events, event type taxonomy, and securities filters in parallel. Event detail is retrieved from a single endpoint and includes classification, security, date, DTC mandatory, and support context.
The information provided by corporate action notification API endpoints leverages DTCC's ISO CANO messages. For a data dictionary on these data points, please refer to DTCC's ISO 20022 Messaging Specifications, located here.
/connect/token with grant_type=urn:dtcc:params:oauth:grant-type:service-account-credentials, type=conveyance, entity={entityId}, acr_values=tenant:{tenantName}, username={username}, and password={password}. Downstream API calls use Authorization: Bearer {access_token}. Finding your entity ID: the value for entity={entityId} is shown on the participant's My Company page in the Tokenization App UI, where the participant can view the entity ID assigned to them.A condensed view of the API call sequence, dependencies, and branch rules.
POST /connect/token
Obtain service-account token.
POST /v2/corporate-actions
Retrieve paginated events with a JSON body; offset and count are required, filters are optional.
GET /v2/corporate-actions/event-typesGET /v1/conversion/securities
Load in parallel.
GET /v2/corporate-actions/{id}
Retrieve full event detail.
Interpret status, category, DTC mandatory classification, support flag, and relevant core dates.
GET /v2/corporate-actions/{id}, including security data, event classification, core dates, DTC mandatory classification, support status, and payout-related metadata.Fetches the events list alongside event taxonomy and securities filter options. The events list is retrieved with POST /v2/corporate-actions, which carries the pagination and filter fields in a JSON body; offset and count are required and the filter fields are optional. The event taxonomy and securities calls remain GET requests.
GET /v1/corporate-actions (query-string parameters) to POST /v2/corporate-actions (JSON request body). GET /v1/corporate-actions is deprecated. The filter fields that were previously query parameters are now supplied in the request body, which must include the required offset and count fields.POST /v2/corporate-actions — all filter and pagination fields are supplied in the JSON request body (EventFilterRequest). The body is required and must include offset and count; the remaining filter fields are optional. A request with no body, or one that omits offset or count, is rejected with HTTP 400.
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| offset | body | integer (int32) | Yes | Zero-based index of the first record to return. Minimum 0. |
| count | body | integer (int32) | Yes | Maximum number of records to return per page. Minimum 1. |
| ids | body | string[] | Optional | Filter by internal event identifiers (GUID format). Up to 50 values. |
| eventIds | body | string[] | Optional | Filter by external (DTC) event identifiers. Up to 50 values. |
| eventTypes | body | EventTypeFilterItem[] | Optional | Filter by event types and subtypes. Each item is an object with a required type (EventTypeEnumeration) and an optional subType (SubEventTypeEnumeration). Up to 50 values. |
| securityIds | body | string[] | Optional | Filter by event security identifier. Up to 50 values. |
| securityCusips | body | string[] | Optional | Filter by security CUSIP. Up to 50 values. |
| status | body | EventStatusEnumeration[] | Optional | Filter by event status. Up to 5 values. |
| searchFor | body | string | Optional | Free-text search key filter. Maximum length 50 characters. |
| orderBy | body | EventFields enum | Optional | Field the results are sorted on. |
| sortOrder | body | SortOrder enum | Optional | Sort direction: Ascending or Descending. |
POST /v2/corporate-actions
| Direction | Parameter / Field | Enum Name | Reference |
|---|---|---|---|
| Input (body) | eventTypes[].type | EventTypeEnumeration | Event Type ▾ |
| Input (body) | eventTypes[].subType | SubEventTypeEnumeration | Sub-Event Type ▾ |
| Input (body) | status | EventStatusEnumeration | Event Status ▾ |
| Input (body) | orderBy | EventFields | Event Fields ▾ |
| Input (body) | sortOrder | SortOrder | Sort Order ▾ |
| Output (response) | subType | SubEventTypeEnumeration | Sub-Event Type ▾ |
| Output (response) | status | EventStatusEnumeration | Event Status ▾ |
The POST /v2/corporate-actions response (CorporateActionEventResponse) returns type, subType, and status; dtcMandatory and category are returned only by the event detail endpoint GET /v2/corporate-actions/{id}. Enumeration values are defined once in the Corporate Action Enumerations reference at the end of this section.
GET /v2/corporate-actions/event-types
| Direction | Parameter / Field | Enum Name | Reference |
|---|---|---|---|
| Output (response) | eventType | EventTypeEnumeration | Event Type ▾ |
| Output (response) | subEventType | SubEventTypeEnumeration | Sub-Event Type ▾ |
This endpoint returns the authoritative list of valid event type / sub-event type pairs, including the numeric codes used by the service. See the Event Type and Sub-Event Type references.
GET /v1/conversion/securities
| Direction | Parameter / Field | Enum Name | Values |
|---|---|---|---|
| Input (query) | orderBy | FinancialSecurityFields | CUSIP, Description, Issuer |
| Input (query) | sortOrder | SortOrder | Ascending, Descending |
| Output (response) | status | FinancialSecurityStatus | Onboarding, Active, Pause, Failed |
const [eventsResponse, eventTypesResponse, securitiesResponse] = await Promise.all([
fetch(`${baseUrl}/v2/corporate-actions`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${access_token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
// Required pagination fields
offset: 0, // zero-based index of the first record
count: 25, // page size (minimum 1)
// Optional filters (omit any you do not need)
eventTypes: [ // up to 50 type/subType items
{ type: 'CashDividend', subType: 'DRIPDTCOnly' }
],
status: ['Approved'], // up to 5 EventStatusEnumeration values
securityCusips: ['46090E103'], // up to 50 CUSIPs
searchFor: 'Invesco', // free-text, max 50 chars
// Optional sorting
orderBy: 'UpdatedAt', // EventFields value
sortOrder: 'Descending' // Ascending | Descending
})
}),
fetch(`${baseUrl}/v2/corporate-actions/event-types`, {
headers: { 'Authorization': `Bearer ${access_token}` }
}),
fetch(`${baseUrl}/v1/conversion/securities`, {
headers: { 'Authorization': `Bearer ${access_token}` }
})
]);
const events = await eventsResponse.json();POST /v2/corporate-actions
[
{
"id": "9149E44A-CAB4-4CB4-8656-A01BDA2B18EC",
"eventId": "0000006",
"typeDescription": "Cash Dividend",
"type": "CashDividend",
"subTypeDescription": "DRIP (DTC Only)",
"subType": "DRIPDTCOnly",
"status": "Approved",
"positionCaptureDate": "2025-03-12T00:00:00Z",
"declaredPayableDate": "2025-03-12T00:00:00Z",
"earliestDTCAnticipatedPaymentDate": null,
"earliestDTCInstructionExpirationDate": null,
"digitalAllocationDate": "2025-05-05T19:00:00Z",
"updatedAt": "2025-05-05T19:00:00Z",
"security": { "id": "E6789C8C-2CA4-446C-AE93-0A9AFFCC457A", "externalId": "E6789C8C-2CA4-446C-AE93-0A9AFFCC457A", "cusip": "46090E103", "name": "Invesco QQQ Trust", "onboardedDate": "2024-01-15T00:00:00Z" },
"dtcProcessingIndicator": true
}
]GET /v2/corporate-actions/event-types — returns the authoritative list of valid event type / sub-event type pairs, including the numeric codes used by the service.
[
{
"eventType": 12,
"eventTypeCode": "CashDividend",
"eventTypeDescription": "Cash Dividend",
"subEventType": 3,
"subEventTypeCode": "DRIPDTCOnly",
"subEventTypeDescription": "DRIP (DTC Only)"
}
]GET /v1/conversion/securities — securities reference data used to populate the security filter.
[
{
"id": "security-id",
"cusip": "46090E103",
"issuerName": "Example Issuer",
"security": "Invesco QQQ Trust",
"securitySymbol": "QQQ",
"status": "Active"
}
]interface CorporateActionEventResponse {
id: string;
eventId: string;
typeDescription: string;
type: string;
subTypeDescription: string;
subType: string;
status: string;
positionCaptureDate: string | null;
declaredPayableDate: string | null;
earliestDTCAnticipatedPaymentDate: string | null;
earliestDTCInstructionExpirationDate: string | null;
digitalAllocationDate: string | null;
updatedAt: string | null;
security: SecurityListResponse;
dtcProcessingIndicator: boolean;
}
interface SecurityListResponse {
id: string;
externalId: string;
cusip: string;
name: string;
onboardedDate: string;
}
interface EventTypePairResponse {
eventType: number;
eventTypeCode: string;
eventTypeDescription: string;
subEventType: number;
subEventTypeCode: string;
subEventTypeDescription: string;
}Approved, ConditionallyApproved, Incomplete, Cancelled, and Deleted.
Handle 401 by requesting a new JWT access credential and retrying once, 403 as lockout or missing permission, 400 as invalid filters, and 5xx with retry. If the event-type or securities call fails, disable the affected filter while keeping the events list usable.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Malformed request or invalid filter parameter | Correct the request. Do not retry as-is. |
| 401 | JWT access credential missing, expired, or invalid | Request a new JWT access credential, then retry once. |
| 403 | Service account lacks the required permission, or the account is locked | Surface access denied. Do not retry. |
| 404 | Resource not found | Surface not found. Do not retry. |
| 500, 503 | Service failure | Retry with exponential backoff, maximum three attempts. Keep the workflow stable and disable only the affected filter. |
All three calls are read-only queries and safe to retry on 5xx or network timeout. The events list is a POST /v2/corporate-actions that performs a read with no side effects, so retrying it is safe; the event-types and securities calls are GET requests.
Retrieves full detail for a specific corporate action event.
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Unique key of a single corporate action event, taken from the results of the event list call. |
GET /v2/corporate-actions/{id}
| Direction | Parameter / Field | Enum Name | Reference |
|---|---|---|---|
| Output (response) | type | EventTypeEnumeration | Event Type ▾ |
| Output (response) | subType | SubEventTypeEnumeration | Sub-Event Type ▾ |
| Output (response) | status | EventStatusEnumeration | Event Status ▾ |
| Output (response) | dtcMandatory | DtcMandatory | DTC Mandatory ▾ |
| Output (response) | category | EventCategory | Event Category ▾ |
Enumeration values are defined once in the Corporate Action Enumerations reference at the end of this section.
const eventDetailResponse = await fetch(
`${baseUrl}/v2/corporate-actions/${eventId}`,
{ headers: { 'Authorization': `Bearer ${access_token}` } }
);
if (!eventDetailResponse.ok) {
const error = await eventDetailResponse.json();
// This endpoint returns two different error-body shapes depending on the status code.
if (eventDetailResponse.status === 401 || eventDetailResponse.status === 403) {
// Gateway/authorization errors carry only errorCode and errorMessage.
throw new Error(`Event detail request failed: ${error.errorCode} - ${error.errorMessage}`);
} else {
// 400, 404, and 500 use camelCase fields: errorCode, message, plus requestId and tracingUrl.
throw new Error(
`Event detail request failed: ${error.errorCode} - ${error.message}` +
(error.requestId ? ` (requestId: ${error.requestId})` : '')
);
}
}
const eventDetail = await eventDetailResponse.json();This endpoint returns two distinct error-body shapes. The 401 and 403 responses carry only errorCode and errorMessage (for example GATEWAY__UNAUTHENTICATED, GATEWAY__ACCESSDENIED, AUTHORIZATION_ENGINE__USER_LOCKED_OUT_EXCEPTION). The 400, 404, and 500 responses carry errorCode and message, plus the optional requestId and tracingUrl. Read the fields that match the status code rather than assuming a single shape.
{
"id": "event-record-id",
"security": { "id": "security-id", "externalId": "security-id", "cusip": "46625H202", "name": "Example Security", "issuerDescription": "Example Issuer", "assetClass": "Equity", "assetType": "Common Stock", "ticker": "EX", "onboardedDate": "2024-01-15T00:00:00Z" },
"eventId": "123456",
"group": "Distribution",
"type": "CashDividend",
"typeDescription": "Cash Dividend",
"subTypeDescription": "305C - Deemed Dividend",
"subType": "CDeemedDividend",
"status": "ConditionallyApproved",
"category": "MandatoryCashDistribution",
"isSupported": false,
"dtcMandatory": "Mandatory",
"totalCashEntitledAmount": 10000.00,
"totalSecuritiesEntitledAmount": null,
"hasAllocations": true,
"hasEntitlements": true,
"isLateAnnouncement": false,
"coreDates": {
"exDate": "2026-06-24T00:00:00Z",
"recordDate": "2026-06-24T00:00:00Z",
"dtcPositionCaptureDate": "2026-06-24T00:00:00Z",
"dueBillRedemptionDate": null,
"declaredPayableDate": "2026-06-24T00:00:00Z",
"digitalAllocationDateTime": null,
"bookEntryAllocationDateTime": null,
"effectiveDateCompany": null,
"anticipateDate": null,
"meetingDate": null,
"dtcInstructionExpirationDateTime": null,
"reconversionDate": null,
"actionDate": null
}
}interface CorporateActionEventDetailResponse {
id: string;
security: SecurityResponse;
eventId: string;
group: string;
type: string;
typeDescription: string;
subTypeDescription: string;
subType: string;
status: string;
category: string;
isSupported: boolean;
dtcMandatory: string;
totalCashEntitledAmount: number | null;
totalSecuritiesEntitledAmount: number | null;
hasAllocations: boolean;
hasEntitlements: boolean;
isLateAnnouncement: boolean;
coreDates: CoreDates;
}
interface SecurityResponse {
id: string;
externalId: string;
cusip: string;
name: string;
issuerDescription: string;
assetClass: string;
assetType: string;
ticker: string;
onboardedDate: string;
}
interface CoreDates {
exDate: string | null;
recordDate: string | null;
dtcPositionCaptureDate: string | null;
dueBillRedemptionDate: string | null;
declaredPayableDate: string | null;
digitalAllocationDateTime: string | null;
bookEntryAllocationDateTime: string | null;
effectiveDateCompany: string | null;
anticipateDate: string | null;
meetingDate: string | null;
dtcInstructionExpirationDateTime: string | null;
reconversionDate: string | null;
actionDate: string | null;
}The event detail response includes security information, event classification, status, category, DTC mandatory classification, support indicator, entitlement and allocation flags, entitled amounts, and a coreDates object (which carries the lifecycle dates including reconversionDate). No separate entitlements endpoint is needed for the workflow described in the source material.
Handle 401 as an expired credential, 403 as lockout or missing detail permission, 404 as an invalid or deleted event, 400 as an invalid event ID format, and 500 with retry. The error body shape depends on the status code: 401 and 403 carry only errorCode and errorMessage, while 400, 404, and 500 carry errorCode and message (plus the optional requestId and tracingUrl). Surface the fields that match the status code rather than discarding them.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Invalid event identifier format | Correct the request. Do not retry as-is. |
| 401 | JWT access credential missing, expired, or invalid | Request a new JWT access credential, then retry once. |
| 403 | Service account lacks the required permission, or the account is locked | Surface access denied. Do not retry. |
| 404 | Invalid or deleted event | Surface event not found. Do not retry. |
| 500, 503 | Service failure | Retry with exponential backoff, maximum three attempts. |
Read-only GET; safe to retry on 5xx or network timeout. Use exponential backoff with a maximum of three retries.
These enumerations are shared across the Corporate Actions endpoints. Each value is defined once here; the endpoint tables above link into this reference. Values are case-sensitive and must be sent exactly as shown.
High-level corporate action classification. Used as the type field inside each eventTypes[] filter item, and returned as type on event responses. Descriptions are sourced from the SR2026 Corporate Action Announcements Data Dictionary.
| Value | Event Name | Description |
|---|---|---|
AutomaticDividendReinvestment | Automatic Dividend Reinvestment | A mandatory event for which the dividend payment is paid only in additional shares of the same security. This event type will predominantly be used for US securities and differs from the Dividend Reinvestment option (a voluntary portion of the event that applies to non-US securities). "DRIP" also appears as an option under relevant events (e.g., Cash Dividend). |
CapitalGainsDistribution | Capital Gains Distribution | A distribution of cash that the issuer has determined will be declared as income financed from capital gains and not ordinary income. |
CashDividend | Cash Dividend | A distribution of cash to shareholders, paid by the issuer, usually based upon current earnings and/or accumulated profits as declared by the board of directors. There are separate events for Dividends with Options and Stock Dividends. |
CDEarlyRedemption | CD Early Redemption | A feature of a security that allows an issuer to make a payment to the security holder. This event will be used for securities subject to redemptions other than those categorized as full and partial calls (e.g., early CD redemptions). Deferred until Phase 4 implementation. |
Change | Change | An event where the issuer is announcing a change in company or security details. |
Consent | Consent | Solicitation to security holders for their agreement (consent) to proposed changes in the terms of the security, usually without a formal general meeting. A fee may be paid to the security holder. |
Conversion | Conversion | Conversion of securities (generally convertible bonds or preferred shares) into another form of securities (usually common shares) at a pre-stated price or rate. |
Default | Default | A notice of failure by the issuer to honour commitments made within the terms of the issued security. It usually relates to making timely payments of interest and principal as they come due. A payment may be made in lieu of reinstituting the original payments. |
Distribution | Distribution | A distribution by the issuer that is not classified as another specific event. |
DividendWithOption | Dividend with Option | A distribution of a dividend to shareholders with the choice of payment method. The shareholder has the option to choose the form of payment (e.g., securities, cash, or both). There are separate events for Cash Dividends, Stock Dividends, and Dividends with Options. |
DutchAuction | Dutch Auction | Identifies a tender event in which the corporation offers to purchase up to a certain amount of securities within a price range. Holders must submit a specific price within that range that they would be willing to accept. The actual tender price is not determined until the end of the offer. |
ExchangeOffer | Exchange Offer | An offer to surrender securities in exchange for other securities or a combination of securities and cash. The exchange may also include a consent solicitation. |
FinalPaydown | Final Paydown | The final distribution of principal due on a security, typically CMOs. |
FullCall | Full Call | The security is redeemed for cash in its entirety on a date that is prior to the maturity date, and for which the holders receive the principal amount of the security. |
FullPrerefunding | Full Prerefunding | The exercise of a privilege by the issuer to repay, in full, any debt security prior to maturity when the issuer deposits assets in trust. This irrevocably restricts their use to satisfaction of the debt. |
GeneralInformation | General Information | General information provided by the issuer that should not result in material changes to the security. |
Interest | Interest | The payment of an obligation that the issuer agrees to make to holders of an interest-bearing security. Usually, the payment is made in cash and on a scheduled basis. |
Liquidation | Liquidation | A company reports its intentions to dismantle its business, paying off debts in order of priority and distributing the remaining assets in cash and/or securities to the owners of the securities. The payment of proceeds may require the presentation of securities. |
MandatoryExchange | Mandatory Exchange | A corporate action requiring the surrender of certificates to be exchanged for a new security or cash. |
MandatoryPut | Mandatory Put | The mandatory exchange of all outstanding bonds (with a putable feature) for cash or a new security, where the event security is remarketed. The issuer may offer holders the right to retain their securities instead of exchanging them. |
Maturity | Maturity | The final repayment, usually in cash, by an issuer for the entire issue, or remaining outstanding securities of a specific security on a specified date. |
Meeting | Meeting | A meeting of a company's share or bond holders to address resolutions put forth by the issuer. |
Merger | Merger | The exchange of one company's security for another company's security, cash, or a combination of cash and securities. |
NameChange | Name Change | The issuer changes its name or the name of its security/securities. This may involve surrendering physical securities. A new security identifier may be assigned to the new name, especially if new securities are issued. |
OddLotOffer | Odd Lot Offer | Identifies a tender offer event made by the corporation or its agent to purchase shares from odd-lot shareholders. An odd-lot shareholder typically refers to a holder of less than 100 shares of stock. |
PartialCall | Partial Call | Securities are redeemed by the issuer for cash, in part, before their scheduled maturity date. The outstanding amount of securities will be proportionally reduced based on a specific percentage of holding. A lottery may be run where pooled securities are held. |
PartialDefeasance | Partial Defeasance | Issuer sets aside cash in escrow to pay off a portion of the issue before the maturity date. New securities are issued for the portion defeased. |
PartialMandatoryPut | Partial Mandatory Put | The mandatory exchange of a portion of bonds where the exchanged securities are usually remarketed. The issuer may offer holders the right to retain instead of exchanging their securities. |
PartialPrerefunding | Partial Prerefunding | Similar to a Full Prerefunding, a partial prerefunding is the exercise of a privilege by the issuer to repay, in part, any debt security prior to maturity when the issuer deposits assets in trust. This irrevocably restricts their use to satisfaction of the debt. New securities are issued for the portion prerefunded. |
PayInKind | Pay in Kind | Income on interest-bearing securities where the payment is made in additional securities rather than cash. |
PlanOfReorganization | Plan of Reorganization | Reorganisation plan devised by the company or trustees that is usually associated with a bankruptcy filing. Identifies an event where a vote/consent is sought for the plan of reorganisation. |
Principal | Principal | A cash payment that represents a reduction of the principal in the security. |
Put | Put | A feature of a bond that entitles the holder to elect to surrender the bond for cash during a predetermined time period, with a predetermined payable date. |
RedemptionOfRights | Redemption of Rights | An event where the issuer pays proceeds to shareholders prior to acquiring or merging with an existing company. |
RedemptionOfWarrants | Redemption of Warrants | An event where the issuer pays proceeds to holders at or after the expiration date of the warrant rather than expire the warrant for no cash (worthless). |
Reorganization | Reorganization | A reorganization event announced by the issuer that cannot be classified as another event. |
ReturnOfCapital | Return of Capital | A distribution of cash resulting from the sale of a capital asset or securities, or any other transaction unrelated to retained earnings. Security holders may have to adjust the "cost basis" of their holding to account for the payment. |
ReverseStockSplit | Reverse Stock Split | The exchange of a company's security for the same company's new security at a preset rate. This corporate action reduces the number of shares outstanding. |
RightsDistribution | Rights Distribution | Securities distributed to common stock holders of a company that grant the option to purchase new or additional securities of the same company during a predetermined time period at a predetermined price. A Rights Distribution is accompanied by a corresponding Rights Subscription, which provides the details related to exercising the rights. In some cases, DTC will allocate rights that are not issued by the company to process a subscription offer. |
RightsSubscription | Rights Subscription | A privilege granted to holders of rights to purchase new or additional securities. Rights are often tradable in a secondary market. |
SaleOfRights | Sale Of Rights | A feature of a security that allows an issuer to make a payment to the security holder. This event will be used for securities subject to redemptions other than full and partial calls (e.g., early CD redemptions). |
SecuritySeparation | Security Separation | No corresponding entry in the SR2026 data dictionary; description not published. |
SpecialDividend | Special Dividend | A cash payment to shareholders that represents an extra or non-regular payment. There are separate events for Cash Dividends, Dividends with Options, and Stock Dividends. |
SpinOff | Spin-Off | A distribution of subsidiary securities to the shareholders of the parent company without a surrender of securities or payment. A spin-off represents a form of divestiture resulting in an independent company. |
StockDividend | Stock Dividend | A dividend paid to shareholders in the form of shares of stock in either the issuing company or in another company. There are separate events for Cash Dividends, Dividends with Options, and Special Dividends. |
StockSplit | Stock Split | The increase in a company's number of outstanding shares of stock without any change in the shareholder's equity or the aggregate market value at the time of the split. The share price is normally reduced. Forward split events are included here. |
TaxEvent | Tax Event | Tax Event announcements are information only announcements regarding taxable events that may give rise to information and/or withholding obligations which occur even in the absence of an actual distribution of dividend and interest payments ("Tax Events"). |
TaxRefund | Tax Refund | An event that enables DTC to make a withholding tax refund, usually on non-U.S. dividends. |
TenderOffer | Tender Offer | An offer made to security holders, normally by a third party, requesting them to sell (tender) their securities for a specified price (usually at a premium over prevailing market prices). Generally, the objective of a tender offer is to take control of the target company. |
Termination | Termination | A security, usually a form of a derivative (e.g., ADR or UIT), for which the agent or issuer has decided to terminate the derivative based on a change to the underlying security(ies) or a change in strategy. |
WarrantsExercise | Warrants Exercise | A feature of a security that permits the holder to exercise an option to exchange the security into another form (usually, warrants into shares). The exercise will commonly require a payment based upon a pre-determined value and time. |
Worthless | Worthless | DTCC advising its participants that their positions in that security will be taken down. The announcement is created when DTC receives a formal letter advising that securities held are worthless. |
Bankruptcy | Bankruptcy | Bankruptcy (Vote) is a legal process for relieving debt that the borrower cannot repay. It's a measure of last resort that typically requires liquidating assets or entering a repayment plan. (Added 7/15/2026.) |
Finer classification nested beneath an event type. Valid type / subType pairings are enumerated by GET /v2/corporate-actions/event-types; do not assume every subtype is valid for every type. Descriptions are sourced from the SR2026 Corporate Action Announcements Data Dictionary; some codes apply across multiple event types and are described generically.
| Value | Sub-Event Name | Description |
|---|---|---|
None | (Non-specific) | Non-specific event with no sub-event classification. |
DRIPDTCOnly | DRIP (DTC only) | Identifies an event where the Issue is eligible for a Dividend Reinvestment program. |
OptOutDTCOnly | Opt Out (DTC only) | Identifies an event (e.g., Cash Dividend) where DTC offers a DRIP option as a default option (holder must opt out of the DRIP Option). |
Domicile | Domicile | Identifies an event where the Issuer has changed the domicile of the Corporation / a change in the place of incorporation of the legal entity of the issuing company. |
DomicileNewCUSIP | Domicile New CUSIP | A domicile change accompanied by the assignment of a new CUSIP. |
DomicilePresentationRequired | Domicile Presentation Required | A domicile change for which presentation of securities is required. |
DomicileNewCUSIPPresentationRequired | Domicile New CUSIP Presentation Required | A domicile change with a new CUSIP for which presentation of securities is required. |
WithPayout | With Payout | Identifies an event where a fee is paid to the registered holder. DTC will not be processing as information only event. |
WithoutPayout | Without Payout | Identifies an event where no fee is paid. DTC will not be processing as information only event. |
FinalPayment | Final Payment | Identifies an event that include notification of a final payment in lieu of the original commitment. |
InterimPayment | Interim Payment | Identifies an event that include notification of an interim payment in lieu of the original commitment. |
TaxCredit | Tax Credit | Tax credit notification for informational purpose only. A tax credit will be generated in addition to a redemption and interest allocations. This tax credit can be a part of the debt instrument or can be stripped and traded separately. Commonly known in U.S. as Build America Bonds. |
Consent | Consent | Identifies an event that includes a consent fee. |
A144 | 144a | Identifies an event where the security is a 144a private placement security. |
CashAndSecurities | Cash and Securities | Identifies an event with a combination of Cash and Securities as payout. |
RegS | Reg S | Identifies an event where the security is a Regulation S type. |
Unwind | Unwind | Identifies an event where "unwinding" of the basket of securities occurs. Example: in order to participate in the tender offer of one of the underlying securities, holder must unwind the basket. DTC creates the event for the holder to respond - "unwind". Tender Offer itself would be a separate event. OR notification that UIT can be "unwinded" in IVORs (separate instruction system) with expiration dates supplied. |
Conversion | Ongoing | Identifies an event with an expiration date stipulated in the security, or a security with an open-ended expiration date up to/near the maturity date for holders to convert the security. This expiration is usually a date far into the future. |
ImportantNotice | Important Notice | Identifies an information only event of DTC Money Market Instrument (MMI) Important Notice announcements. Announcements are based on changes to the MMI security that are entered by the agent. Specific to MMI Important notices only. |
DayExemptionQualifiedNotice | Day Exemption Qualified Notice | Identifies a qualified notice issued by a publicly traded partnership stating applicability of the 10 percent exception under IRS regulation 1.1446(f)-4(b)(3). |
BasedOnRecordDateHoldings | Based on Record Date Holdings | Identifies an event processed as dividend event. |
PresentationRequired | Presentation Required | Identifies an event processed as Reorg event and may include options. |
Retain | Retain | Identifies an event that include an option to retain the event securities rather than exchange them. |
Securities | Securities | Identifies an event where the payment will be made in the form of securities. |
Annual | Annual | Identifies an annual meeting event. |
Extraordinary | Extraordinary | Identifies an extraordinary meeting event. |
General | General Meeting | Identifies a meeting event called by the company on behalf of security holders at which the company can present corporate resolutions that may require a vote by the holders. |
Special | Special | Identifies a special meeting event. |
Cash | Cash | Identifies an event with a payout of cash only. |
CUSIPChangePresentationRequired | CUSIP Change Presentation Required | Identifies a CUSIP change for which presentation of securities is required. |
NewCUSIP | New CUSIP | Identifies an event accompanied by the assignment of a new CUSIP. |
Vote | Vote | Identifies an event where a vote is sought. |
MortgageBacked | Mortgage-Backed | Indicates an event where the Issue has an early redemption feature that allows the holder to elect to sell bonds back to the issuer on a monthly basis, according to specified conditions. |
SurvivorOptions | Survivor Options | Indicates an event where the Issue has an early redemption feature. This feature allows the holder to elect to sell bonds back to the issuer on a predetermined basis (excluding monthly) according to specific priorities. |
SPAC | SPAC | Identifies a Special Purpose Acquisition Company to raise money through an initial public offering (IPO) to acquire or merge with an existing company. |
SaleOfAssets | Sale of Assets | Identifies an event where the distribution is from the proceeds of the sale of assets. |
PhysicalRightsNotIssued | Physical Rights not Issued | Identifies an event where the company is not issuing a security with the right to subscribe for additional shares. In these instances, a User CUSIP is created by DTC (as opposed to a company-issued CUSIP) in order to identify these issues. |
ADR | ADR | Identifies when the event security is an ADR, or a sale of rights where domicile restrictions require the ADR agent to sell rather than issue rights. |
PoisonPill | Poison Pill | Identifies sale of rights event where issuers redeem poison pill rights. |
CDeemedDividend | 305C - Deemed Dividend | Deemed distribution under Section 305(c) of the Internal Revenue Code. |
DividendEquivalentPayment | 871M | Dividend Equivalent Payment under Section 871(m) of the Internal Revenue Code. |
ExcessOfCumulativeNetIncome | ECNI | Identifies when a publicly traded partnership identifies the amount realised on such portion of the distribution as an amount in excess of cumulative net income under IRS regulation 1.1446(f)-4(c)(2)(iii). |
SClassifications1042 | RCLA (1042S Classifications) | Identifies distributions that have multiple components for tax withholding and 1042-S reporting purposes. |
BidTenderSealedTender | Bid Tender/Sealed Tender | Identifies a tender offer event in which the holder can choose the price at which they are willing to tender their securities. This price may or may not be accepted by the offeror. |
CashInLieu | Cash in Lieu | Identifies DTC specific sub-event where holders can elect to "sell" whole shares to satisfy fractional entitlements (usually as a result of a merger) at the beneficial owner level. |
ConvertAndTender | Convert and Tender | Identifies a tender offer event in which the holder must convert securities in order to take part in the event. |
MiniTender | Mini Tender | Identifies a tender offer event presented by a third party to shareholders of the target company, in which the conditions of the offer (e.g., quantity sought) are less than the requirements established by market regulators. As such, regulatory approval is not required. |
OfferToPurchase | Offer to Purchase | Identifies a tender offer event made by another company or the issuing company (buy back) to purchase a portion or all of the outstanding shares. |
SelfTender | Self Tender | Identifies a tender offer event made by the issuing company (buy back) to purchase a portion or all of the outstanding shares. |
GDR | GDR | Identifies when the event security is a GDR. |
MeetingType | Meeting Type | Identifies the type classification for a meeting event. |
| Value | Meaning |
|---|---|
Approved | Event is approved and final. |
ConditionallyApproved | Approved subject to conditions. |
Incomplete | Event data is not yet complete. |
Cancelled | Event was cancelled. |
Deleted | Event was deleted. |
| Value | Meaning |
|---|---|
Mandatory | Participation is automatic; no election required. |
MandatoryWithOptions | Mandatory, but participants may choose from options. |
Voluntary | Participation requires explicit election by the holder. |
| Value |
|---|
InterestOnTreasury |
MaturityOnTreasury |
MandatoryCashDistribution |
MandatorySecurityDistribution |
MandatoryWithChoiceDistribution |
MandatoryReorganization |
VoluntaryReorganization |
Meetings |
| Value |
|---|
Id |
EventId |
EventType |
Status |
SecurityName |
SecurityCusip |
PositionCaptureDate |
DeclaredPayableDate |
EarliestDTCAnticipatedPaymentDate |
EarliestDTCInstructionExpirationDate |
UpdatedAt |
DigitalAllocationDate |
| Value |
|---|
Ascending |
Descending |
| Category | Relevant Core Dates |
|---|---|
InterestOnTreasury | declaredPayableDate, digitalAllocationDateTime, bookEntryAllocationDateTime |
MaturityOnTreasury | declaredPayableDate, digitalAllocationDateTime, bookEntryAllocationDateTime |
MandatoryCashDistribution | exDate, recordDate, dtcPositionCaptureDate, declaredPayableDate, anticipateDate, digitalAllocationDateTime, bookEntryAllocationDateTime |
MandatorySecurityDistribution | exDate, recordDate, dtcPositionCaptureDate, digitalAllocationDateTime, bookEntryAllocationDateTime |
MandatoryWithChoiceDistribution | exDate, recordDate, dtcPositionCaptureDate, dtcInstructionExpirationDateTime, digitalAllocationDateTime, bookEntryAllocationDateTime |
MandatoryReorganization | effectiveDateCompany, dtcPositionCaptureDate, digitalAllocationDateTime, bookEntryAllocationDateTime, reconversionDate |
VoluntaryReorganization | dtcInstructionExpirationDateTime, dtcPositionCaptureDate, digitalAllocationDateTime, bookEntryAllocationDateTime |
Meetings | meetingDate |
| Value | Meaning |
|---|---|
Mandatory | Participation is automatic; no election required. |
MandatoryWithOptions | Mandatory but participants may choose from options. |
Voluntary | Participation requires explicit election by the holder. |
POST /v2/corporate-actions query, while the event type, securities, and event-detail calls are read-only GET requests. All are side-effect free and can be retried on network or service failures. The DTCC APIs provides event listing, taxonomy, securities reference data, and event details.This certification verifies both API connectivity and the customer's ability to correctly interpret corporate action event data.
Authenticate, load events, load event types and securities in parallel, inspect the event, then apply context.
Obtain a JWT access credential using SA-CorporateActionsBot.
POST /v2/corporate-actions
event-types plus securities in parallel.
GET /v2/corporate-actions/{id}
Status, category, DTC classification, and core dates.
GET /v2/corporate-actions/{id}. No additional entitlement endpoint is required.| Rule | Requirement |
|---|---|
| Parallel Loading | Retrieve events, event types, and securities concurrently. |
| Supported Statuses | Approved, ConditionallyApproved, Incomplete, Cancelled, Deleted. |
| Detail Retrieval | All detail information is retrieved from GET /v2/corporate-actions/{id}. |
| Context Interpretation | Customers must correctly apply status, category, DTC mandatory classification, support indicator, and core dates. |
Tenant ID, service account, service account password, base URL, a known corporate action event, and securities access. Required endpoints: /connect/token, POST /v2/corporate-actions, /v2/corporate-actions/event-types, /v1/conversion/securities, /v2/corporate-actions/{id}.
const tenantName = "<tenant-name>"; // recommended, e.g. "DTCC-DA"
const baseUrl = "<base-url>";
const username = "SA-CorporateActionsBot";
const password = process.env.SERVICE_ACCOUNT_PASSWORD!;async function loadCorporateActionsData(accessToken: string) {
const [eventsResponse, eventTypesResponse, securitiesResponse] = await Promise.all([
fetch(`${baseUrl}/v2/corporate-actions`, {
method: "POST",
headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
body: JSON.stringify({ offset: 0, count: 25 })
}),
fetch(`${baseUrl}/v2/corporate-actions/event-types`, { headers: { Authorization: `Bearer ${accessToken}` } }),
fetch(`${baseUrl}/v1/conversion/securities`, { headers: { Authorization: `Bearer ${accessToken}` } })
]);
return {
events: await eventsResponse.json(),
eventTypes: await eventTypesResponse.json(),
securities: await securitiesResponse.json()
};
}
async function getEventDetail(accessToken: string, eventId: string) {
const response = await fetch(`${baseUrl}/v2/corporate-actions/${eventId}`, {
headers: { Authorization: `Bearer ${accessToken}` }
});
if (!response.ok) {
const error = await response.json();
throw new Error(`Event detail failed: ${error.ErrorCode} - ${error.ErrorMessage}`);
}
return response.json();
}This step validates that the integration can obtain a JWT access credential from the Identity Server using service account credentials. The JWT access credential proves the caller's identity and must be supplied as a bearer credential on every subsequent API call in this workflow.
HTTP 200; JWT access credential returned; credential accepted by downstream APIs.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Invalid credentials | Surface authentication rejected. Do not retry with the same credentials. |
| 500, 503 | Identity Server failure | Retry with exponential backoff, maximum three attempts. |
Verify the integration can retrieve a paginated corporate action event inventory with statuses and event identifiers populated.
const data = await loadCorporateActionsData(accessToken);Events returned; pagination supported; statuses populated; event identifiers returned.
HTTP 200; corporate action inventory loaded successfully.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Invalid filter parameters | Correct the request. Do not retry as-is. |
| 401 | Expired or invalid JWT access credential | Re-authenticate, then retry once. |
| 403 | Missing permission | Surface access denied. Do not retry. |
| 500, 503 | Service failure | Retry with exponential backoff, maximum three attempts. |
Verify the integration can retrieve the event type and sub-event type taxonomy used for hierarchical event filtering.
Event types returned; sub-event types returned; hierarchy available.
HTTP 200; event taxonomy successfully loaded.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 401 | Expired or invalid JWT access credential | Re-authenticate, then retry once. |
| 500, 503 | Event-type service unavailable | Filter data unavailable; display a meaningful error and keep the workflow stable. |
Verify the integration can retrieve securities reference data, including CUSIPs and support flags, for filtering corporate action events.
Security identifiers returned; CUSIPs returned; support flags returned.
HTTP 200; security filtering possible.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 401 | Expired or invalid JWT access credential | Re-authenticate, then retry once. |
| 500, 503 | Securities service unavailable | Security filter unavailable; display a meaningful error and keep the workflow stable. |
Verify the integration can narrow the event inventory to a relevant subset using status, event type, sub-event type, security, and search text.
const approvedEvents = events.filter(
event => event.status === "Approved"
);Successful filtering by status, event type, sub-event type, security, and search text.
Relevant events identified.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Invalid filter parameters | Validation error. Correct the filter values before retrying. |
Verify the integration can retrieve full event detail from the single detail endpoint, including security, category, status, classification, and core dates.
const detail = await getEventDetail(accessToken, eventId);Security returned; category returned; status returned; DTC classification returned; core dates returned.
HTTP 200; event detail successfully retrieved.
| HTTP | Condition | Expected integration behavior |
|---|---|---|
| 400 | Invalid event identifier format | Correct the request. Do not retry as-is. |
| 404 | Invalid event ID; event not found | Surface event not found. Do not retry. |
| 500, 503 | Event detail service failure | Invoke retry logic with exponential backoff and handle the failure gracefully. |
Verify the integration derives correct business context from the returned category, status, support indicator, and DTC classification.
if (detail.dtcMandatory === "Voluntary") {
console.log("Election Required");
}Interpret category, status, support flag, and DTC classification.
Business context successfully derived.
This step performs no API calls. If a required context field is absent from the event detail response, treat the step as failed rather than applying a default classification.
Verify the integration identifies the correct set of lifecycle dates for each corporate action category it processes.
| Category | Required Dates |
|---|---|
InterestOnTreasury | declaredPayableDate, digitalAllocationDateTime, bookEntryAllocationDateTime |
MaturityOnTreasury | declaredPayableDate, digitalAllocationDateTime, bookEntryAllocationDateTime |
MandatoryCashDistribution | exDate, recordDate, dtcPositionCaptureDate, declaredPayableDate, anticipateDate, digitalAllocationDateTime, bookEntryAllocationDateTime |
Meetings | meetingDate |
Correctly identify the relevant dates for at least one event available in each category.
The correct set of lifecycle dates is identified for each category present in the test dataset.
This step performs no API calls. If a required date is null for a category that mandates it, surface the gap rather than substituting a placeholder date.
Verify the integration correctly classifies each event as Mandatory, MandatoryWithOptions, or Voluntary and acts on whether an election is required.
| Value | Meaning |
|---|---|
Mandatory | Participation automatic. |
MandatoryWithOptions | Options available to holder. |
Voluntary | Election required. |
The customer correctly classifies events using the returned values.
Each event is classified as Mandatory, MandatoryWithOptions, or Voluntary, and election requirements are applied accordingly.
This step performs no API calls. An unrecognized dtcMandatory value must be surfaced as an unhandled classification rather than defaulted to Mandatory.
Execute the complete corporate actions workflow in a single run to confirm every stage succeeds in sequence.
async function executeWorkflow() {
const token = await authenticate();
const { events, eventTypes, securities } = await loadCorporateActionsData(token);
const selectedEvent = events[0];
const detail = await getEventDetail(token, selectedEvent.id);
return { events, eventTypes, securities, detail };
}Authentication PASS
Load Events PASS
Load Event Types PASS
Load Securities PASS
Filter Events PASS
Retrieve Detail PASS
Apply Context PASS
Workflow Complete PASSEach constituent call returns its expected success code.
| ID | Scenario | HTTP | Expected result |
|---|---|---|---|
| NT-1 | Invalid Credentials | 400 | Authentication rejected. |
| NT-2 | Expired Credential | 401 | Re-authentication required. |
| NT-3 | Invalid Event ID | 404 | Event not found. |
| NT-4 | Missing Permission | 403 | Access denied. |
| NT-5 | Invalid Filter Parameters | 400 | Validation error. |
| NT-6 | Event-Type Service Unavailable | 500, 503 | Filter data unavailable; meaningful error displayed; workflow remains stable. |
| NT-7 | Securities Service Unavailable | 500, 503 | Security filter unavailable; meaningful error displayed; workflow remains stable. |
| NT-8 | Event Detail Service Failure | 500, 503 | Retry logic invoked; graceful failure handling. |
The customer must demonstrate authentication, event retrieval, event-type retrieval, securities retrieval, event filtering, event-detail retrieval, context interpretation, category-date interpretation, DTC classification interpretation, negative-test handling, and end-to-end workflow execution.
This tab records changes to the API Reference Guide that affect integration partners, grouped by their impact: breaking changes, new capabilities, clarifications, and deprecations. Each entry describes current behavior and what, if anything, you need to do. Documentation-only corrections are not listed.
Version 2.0 consolidates the incremental releases previously published as Versions 1.96 through 1.110 into a single release. The changes below are aggregated by impact. Earlier version entries (1.95 and below) are retained as historical record.
https://api.dtcc-da.com/tokenization/services, which now includes the /tokenization path segment (previously https://api.dtcc-da.com/services). Update any downstream API calls that use the production Services host. The production Identity URL (https://api.dtcc-da.com/identity) and both PSE (pre-production) URLs are unchanged.GET /v1/accounts to GET /v1/accounts/roots. Resolve the target accountId from the roots response before retrieving account detail, hierarchy, wallets, activities, and balances.GET /v1/accounts/roots returns root accounts (those with no parent linkage within the tenant), each with descendants nested up to two levels, and supports the rootAccountName, offset, count, and includeObac query parameters.ownershipStake, isOwned, and isOperated, which remain hierarchy-only.GET /v1/conversion/clients) is no longer documented in the guide. Its Load Account Reference Data endpoint card has been removed from the Wallet Management section, and the Wallet Management workflow summary and Workflow Certification Test no longer include a reference-data step. The Wallet Management journey now documents only wallet-inventory retrieval (GET /v1/conversion/wallets) and status tracking.transferLock, alongside doChill, complianceLock, and globalLock. Confirm all four report "enabled": false before treating an Active security as usable.POST /v1/conversion/async-operations/query) requires idempotencyKeys, offset, count, orderBy (CreatedAt), and sortOrder (Ascending or Descending).GET /v1/accounts) returns a paginated, filtered list of accounts. Use the returned accountId values to retrieve account detail, hierarchy, activities, and balances. (Superseded within this release: account resolution subsequently moved to GET /v1/accounts/roots — see the Account Management breaking change above.)GET /v1/conversion/securities), the single-value filters network, issueTypeId, and issueSubTypeId are superseded by the multi-value networks, issueTypeIds, and issueSubTypeIds. The single-value forms still work today and will be removed in a future release; use the multi-value forms.entity={entityId} value is shown on the participant's My Company page in the Tokenization App UI, so participants can look up their assigned entity ID. The description of the entity token input is standardized to "the entity the service account is a member of," consistent with the ENTITY_ID_OF_WHICH_SA_IS_MEMBER_OF phrasing used in the authentication code samples.grant_type, type, entity={entityId}, acr_values=tenant:{tenantName}, username, and password. Use the tenant name form; the tenant identifier form is accepted but not recommended.GET /v1/accounts/{accountId}/hierarchy) as dedicated detail sections. Ownership stake is the direct parent's fractional stake (0 to 1) and multiplies along the path for effective indirect ownership; the depth/performance note explains the depth parameter, one-root-at-a-time traversal for large graphs, skipping the call when children is empty, and omitting includeObac for read-only enumeration.GET /v1/accounts/{accountId}/activities) returns a top-level JSON array of activity records, not an items/metadata envelope. Pagination is carried in the X-Paging-Offset, X-Paging-Count, and X-Paging-TotalCount response headers. The response template, TypeScript interface, and Response Shape prose on the Get Account Activities card reflect the top-level array, and certification Step 5 validates an array rather than a metadata.asOfDate object.fromWalletId and toWalletId activity filters accept, for Classic accounts, the format {participantId}-10 (Free NA) or {participantId}-11 (Free MA), for example 00002667-10; for digital wallets, the registered blockchain wallet address.startDate and endDate filters on account activities (GET /v1/conversion/accounts/{accountId}/activities) are both inclusive and must be supplied together; specifying one without the other is not valid.endDate represents the start of that day at 00:00:00 and does not include records occurring later that day. To include the complete intended end date, specify the following date as endDate.GET /v1/conversion/wallets) free-text filter is searchFor (maximum 256 characters), and the list also supports walletAddress, ids, includeObac, eligiblyOnly, and name. Each wallet record includes trackingWalletId, account, conversionEligible, and failureReason, and wallet type values are Internal and Client.GET /v1/conversion/orders) returns an access-control (obac) object on each order when includeObac=true is passed, and order detail (GET /v1/conversion/orders/{orderId}) includes the nullable submitterEmail and submitterComment fields.trackingWalletId, account, conversionEligible, and failureReason; wallet type values are Internal and Client. The securities list paginates with offset and count.quantity field on POST /v1/conversion/orders is an integer and must be greater than zero. Order detail exposes a check object containing id, approvedBy, approverEmail, and approverComment.state values are Idle, Registering, Deleting, FailedCompliance, and Failed. The securities free-text filter is searchFor and the sort field is orderBy.GET /v1/conversion/orders by status or financialSecurityIds, send each value as a separate repeated query parameter.id and name, and the security with id, cusip, symbol, and status. A conversion order is submitted with financialSecurityId to identify the security.fromWallet, toWallet) include a network attribute on both the orders list and order detail responses.GET /v2/corporate-actions/{id}) so the error-handling example reads the correct fields for each response shape: 401 and 403 carry only errorCode and errorMessage, while 400, 404, and 500 carry errorCode and message plus the optional requestId and tracingUrl.coreDates object on event detail uses the field names digitalAllocationDateTime and bookEntryAllocationDateTime (allocation), dtcPositionCaptureDate (position capture), and dtcInstructionExpirationDateTime (instruction expiration). The Core Dates by Event Category reference reflects these names.Mandatory, MandatoryWithOptions, and Voluntary. Enumeration values are case-sensitive and must be sent exactly as shown.POST /v2/corporate-actions sample request demonstrates the optional filter fields (eventTypes, status, securityCusips, searchFor) and sorting (orderBy, sortOrder) alongside the required offset and count, with the applicable item and length limits noted inline./v1/conversion/clients and the associated "account reference data" / "client reference lookup" wording from the Overview (Primary API Journeys table and Wallet Management domain card), the Certification Portfolio summary, and the API Families, Endpoint Catalog, and Pagination Model reference panels, consistent with the endpoint's removal from the Wallet Management section.quantity as an unquoted integer ("quantity": 500), matching the CreateOrderRequest schema (integer, int32) and the sample on the Submit and Track Conversion Orders card.GET /v1/conversion/securities) supports an optional status filter accepting a single value: Onboarding, Active, Pause, or Failed.POST /v2/corporate-actions with a JSON request body. See the breaking-change callout at the top of this tab for request details and migration guidance. The former GET /v1/corporate-actions is deprecated and will be removed in a future release.POST /v1/conversion/async-operations/query) processes a batch of idempotencyKeys in a single request; submit no more than 100 per request. Keys with no matching operation are omitted from the response rather than returning an error, and results are paginated with offset and count.GET /v1/conversion/orders/{orderId}) exposes fromTransactionId and toTransactionId, the on-chain ledger transaction hashes for the debit and credit legs. Both are null while an order is Processing and are populated once it reaches Completed. These identifiers appear only on order detail, not on the orders list. Only the digital-wallet leg maps to a blockchain transaction; where an external custody or validator provider surfaces the same settled on-chain event, its hash matches the value here.errorCode for HTTP 400, 404, 409, and 500 responses, with the cause and recommended correction for each.activityType is documented (Payment, PaymentReceived, Fee, Mint, Burn, Pause, Unpause, Freeze, Unfreeze, Revoked, Clawedback, Clawback). The definitions apply to both the input filter and the returned values.GET /v1/corporate-actions to POST /v2/corporate-actions. Filter and pagination fields now travel in a JSON request body (EventFilterRequest) rather than query-string parameters: offset and count are required; ids filters by internal (GUID) event identifiers and eventIds by external DTC identifiers; eventTypes is an array of EventTypeFilterItem objects (each with a type and optional subType); securityIds and securityCusips were added; status, searchFor, orderBy, and sortOrder are retained as body fields. The response follows the V2 CorporateActionEventResponse schema (type, typeDescription, subType, subTypeDescription, DTC date fields, dtcProcessingIndicator). The events list is now a read-only POST query while event-types and securities calls remain GET.POST /v2/corporate-actions in place of the deprecated GET /v1/corporate-actions. The Pagination Model Endpoint Support table notes that Offset and Count are sent in the request body rather than the query string.POST /v1/conversion/async-operations/query) processes all idempotencyKeys supplied in a single request. Submit no more than 100 keys per request.GET /v1/conversion/orders/{orderId}) documents fromTransactionId and toTransactionId, the on-chain ledger transaction hashes for the source (debit) and destination (credit) legs. Both are null while an order is Processing and are populated once it reaches Completed. They appear only on order detail, not on the orders list. Only the digital-wallet leg maps to a blockchain transaction; where an external custody or validator provider surfaces the same settled on-chain event, its hash matches the value here.activityType is documented in a value/description table (Payment, PaymentReceived, Fee, Mint, Burn, Pause, Unpause, Freeze, Unfreeze, Revoked, Clawedback, Clawback). The definitions apply to both the input filter and the returned values.ConversionOperationsEngine__WalletNotFound error code moved from the HTTP 404 table to the HTTP 400 table in the Error Code Reference./v1/tracking/networks ledger-networks endpoint has been removed. Wallet reference data loads from /v1/conversion/clients. The network query filter on the securities list is retained.errorCode values, causes, and corrections for HTTP 400, 404, 409, and 500; the 500 and 503 conditions are documented separately.errorCode values, causes, and corrections for HTTP 400, 404, 409, and 500.Active security may still carry a chill or lock that blocks transfers of its tokens across the entire security while the restriction is in effect. Read the restrictions object and test each restriction's enabled flag; an Active status alone does not guarantee a security is usable.POST /v1/conversion/orders returns 202 Accepted with no response body. Resolve the order identifier by polling POST /v1/conversion/async-operations/query with the X-Idempotency-Key retained at submission, then retrieve the order from GET /v1/conversion/orders/{orderId}. The lifecycle is Processing → Completed, with Failed as the terminal failure state.GET /v1/conversion/orders (list, usable for duplicate detection before submitting), POST /v1/conversion/async-operations/query, and GET /v1/conversion/orders/{orderId}. Added the OrderOrigin values Participant, Admin, and ForcedReconversion.Offset and Count parameters with X-Paging-Offset, X-Paging-Count, and X-Paging-TotalCount response headers. The async operations query and the corporate-actions event list carry Offset and Count in the request body rather than the query string.Idle state and conversionEligible = true; a wallet that satisfies only one condition is not eligible.X-Idempotency-Key, and enumeration values are case-sensitive and must be sent exactly as defined.Failed; wallet states include FailedCompliance and Failed.Declined is removed from the lifecycle, leaving Processing, Completed, and Failed. Added queryOperation and getOrder helpers, with correlation by idempotency key.Offset and Count on the orders list, securities list, wallets list, and async operation query. Enumeration values must be provided exactly as defined (case-sensitive), the idempotency header is X-Idempotency-Key throughout, and Deleting is removed from the ProcessingStates values.Offset and Count query parameters, the X-Paging-Offset, X-Paging-Count, and X-Paging-TotalCount response headers, endpoint support, and iteration guidance. The async operation query accepts Offset and Count in the request body rather than the query string.POST /v1/conversion/orders returns 202 Accepted with no response body, so the order identifier is resolved by polling the async operation with the idempotency key retained at submission. Added GET /v1/conversion/orders, POST /v1/conversion/async-operations/query, and GET /v1/conversion/orders/{orderId}, plus the OrderOrigin enumeration (Participant, Admin, ForcedReconversion). Querying the orders list before submission detects whether a prior submission with the same intent already exists.conversionEligible = true in addition to an Idle processing state, applied across the eligibility rules, workflow summary, business rules, and certification criteria.Failed is added to the FinancialSecurityStatus values on the account balances card, and FailedCompliance and Failed are added to the wallet ProcessingStates values.Processing to Completed, with Failed as the terminal failure state.Internal (a participant's own wallets) and Clients (wallets registered on behalf of a participant's clients).