DTCC Digital Assets

Digital Assets API Reference Guide

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.

Getting Started
One integration guide across the DTCC Digital Assets journey

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.

Base URLs:
EnvironmentIdentity (Authentication)Services
PSE (Pre-Production)https://api.pse.lds.dtcc-da.com/identityhttps://api.pse.lds.dtcc-da.com/services
Productionhttps://api.dtcc-da.com/identityhttps://api.dtcc-da.com/tokenization/services
Authentication pattern: These workflows use the Service Account Credentials grant. The token request is sent to /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.
Account ManagementAccount detail, hierarchy summary, access control metadata, locked operation handling, and on-chain account activities through the DTCC APIs.
Wallet ManagementWallet inventory and status tracking for wallet administration workflows.
Conversion OrdersRegistered securities, issue and ledger reference data, active security selection, idle wallet selection, order submission, and order lifecycle tracking.
Corporate ActionsEvent discovery, event type taxonomy, securities filtering, event detail, core dates by category, DTC mandatory classification, and status handling.
Guide Structure

Workflow-first organization

Each tab starts with a compact flow showing call ordering, parallel-load opportunities, branch behavior, and service dependencies before endpoint-level detail.

Integration Pattern

Service-account authentication

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.

Operational Readiness

Rules, status, and error handling

Each journey includes business rules, retry guidance, permission considerations, idempotency, async state tracking, and graceful degradation for reference-data failures.

Primary API Journeys

JourneyPrimary APIsPurpose
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}/balancesResolve 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/walletsLoad 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.
How to use this guide: Start with the relevant tab for the implementation journey, review the compact flow, then use the searchable endpoint cards for request parameters, sample calls, response models, retry guidance, and service dependencies.
Certification

Workflow Certification Framework

CERT
Tokenization Service Workflow Certification Guide
Production Readiness Validation Framework
›

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.

Certification Focus

Focus Area

Workflow Execution

Complete the ordered sequence of steps that compose each production workflow.

Focus Area

Business-Rule Compliance

Apply the platform business rules that govern eligibility, direction, and validation.

Focus Area

Error Handling

Handle invalid credentials, expired credentials, access denials, and service failures.

Focus Area

Operational Readiness

Demonstrate production supportability across the certified workflows.

Focus Area

Production Supportability

Sustain and monitor operations after go-live without introducing risk.

Focus Area

Evidence Collection

Produce request logs, response payloads, and execution output as audit evidence.

Certification Philosophy

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.

Authenticate

Establish a valid session.

Retrieve Required Data

Load inputs for the workflow.

Apply Business Rules

Enforce platform constraints.

Execute Workflow Actions

Perform the operation.

Validate Outcomes

Confirm expected results.

Handle Failures

Manage error conditions.

Produce Evidence

Capture supporting audit artifacts.

AuthenticationData RetrievalBusiness RulesAction ExecutionOutcome ValidationFailure HandlingEvidence

Certification Portfolio

The following workflow certifications are currently included within the Tokenization Service certification framework.

Account ManagementSupports account discovery, hierarchy inspection, sub-account visibility, wallet visibility, activity retrieval, balance retrieval, and operational monitoring.
Wallet ManagementSupports wallet discovery, wallet inventory review, and status monitoring.
Conversion OrdersSupports security discovery, reference-data retrieval, wallet discovery, eligibility determination, conversion-order creation, and lifecycle monitoring.
Corporate ActionsSupports corporate-action discovery, event filtering, event inspection, event classification, lifecycle-date interpretation, and corporate-action monitoring.

Common Certification Requirements

All workflow certifications require demonstration of the following.

RequirementDetail
AuthenticationValid service account authentication.
Error HandlingInvalid credentials, expired credentials, access denied, invalid requests, not found conditions, and service failures.
Workflow CompletionAll required steps executed successfully.
AuditabilityRequest logs, response payloads, execution output, workflow results, and negative-test results.

Common Error Types

HTTPConditionExpected integration behavior
400Malformed request, invalid parameter, or invalid credentialsCorrect the request. Do not retry as-is.
401JWT access credential missing, expired, or invalidRequest a new JWT access credential, then retry once.
403Service account lacks the required permission, or the account is lockedSurface access denied. Do not retry.
404Resource not foundSurface not found. Do not retry.
500, 503Service failureRetry 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.

Certification Framework Summary

Account Management→Wallet Management→Conversion Orders→Corporate Actions

These workflow certifications serve as the formal production-readiness gate for Tokenization Service integrations.

Pre-Implementation
Participant Setup & Onboarding

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.

Workflow Summary

Collect Onboarding Inputs

Capture participant name, DTC account information, technical contact, entity administrator, and go-live inputs.

Initiate Onboarding

The Integration team uses the Operations Portal to initiate participant onboarding, validate onboarding inputs, and launch the provisioning workflow.

Provision Participant

Create the participant entity, DTCC standard account structure, provision wallets, assign controller permissions, create the participant administrator, send onboarding notifications, and activate the participant.

Readiness rule: to access APIs participants must provision and configure service accounts
Onboarding Setup: Service accounts and Wallet Registration can only be set up by the participant through the UI. API-based service account and wallet registration setup is not available.
Category 1
Account Management

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.

Authentication pattern: These workflows use the Service Account Credentials grant. The token request is sent to /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.

Workflow Summary

A condensed view of the API call sequence, dependencies, and branch rules.

Authenticate

POST /connect/token
Obtain a service-account bearer token.

Resolve accountId

GET /v1/accounts/roots
Discover root accounts (descendants nested 2 levels) and resolve the target accountId; skip when already known.

Fetch account

GET /v1/accounts/{accountId}
Retrieve the account entity and optional OBAC.

Fetch hierarchy

GET /v1/accounts/{accountId}/hierarchy
Retrieve child accounts as a tree.

Fetch wallets

GET /v1/accounts/{accountId}/wallets
Retrieve linked wallets with ownership stake.

Activities + Balances (parallel)

GET /v1/conversion/accounts/{accountId}/activities and GET /v1/conversion/accounts/{accountId}/balances
No interdependency; issue in parallel.

Parallel branch: the activities and balances calls share only the accountId and have no data dependency on each other; issue them in parallel after the account detail is confirmed.
Service AccountAccount Management ServiceAccess ControlConversion Service
GET
Get Root Accounts
/v1/accounts/roots
›

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.

Request Parameters

ParameterLocationTypeRequiredDescription
rootAccountNamequerystringOptionalFilter root accounts by name
offsetqueryintegerOptionalZero-based pagination offset (min 0; default 0)
countqueryintegerOptionalPage size (min 1; default 50)
includeObacquerybooleanOptionalWhen true, append OBAC metadata to each account in the tree

Sample Request

typescript
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();

Response Template

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
  }
]

TypeScript Interface

typescript
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;
}

Error Handling

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.

Common Error Types

HTTPConditionExpected integration behavior
400Bad request or invalid query parameterCorrect the request. Do not retry as-is.
401JWT access credential missing, expired, or invalidRequest a new JWT access credential, then retry once.
403Service account lacks the required permission, or the account is lockedSurface access denied. Do not retry.
404Not found — unable to find the resource specifiedSurface not found. Do not retry.
500Internal server errorRetry with exponential backoff and appropriate timeout handling.

Retry Guidance

Read-only GET; safe to retry on 5xx or network timeout. Implement exponential backoff with appropriate timeout handling.

Permissions & Scopes

Required PermissionGET_ACCOUNTS_ROOTS
Auth PatternService Account Credentials grant
Credential DeliveryAuthorization: Bearer {access_token}

GET
Get Account Detail
/v1/accounts/{accountId}
›

Retrieves account data and optional page-level access control permissions. This call confirms that the account exists and that the caller has access.

Request Parameters

ParameterLocationTypeRequiredDescription
accountIdpathstringYesThe account identifier
includeObacquerybooleanOptionalWhen true, includes access-control information

Sample Request

typescript
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();

Response Template

json
{
  "accountId": "account-id",
  "name": "Example Account",
  "externalId": null,
  "itemId": null,
  "obac": { "isController": true, "isShared": false, "hasShareRequest": false }
}

TypeScript Interface

typescript
interface AccountsModel {
  accountId: string;
  name: string;
  externalId?: string | null;
  itemId?: string | null;
  obac?: AccessControlInfoResponse | null;
}
interface AccessControlInfoResponse {
  isController: boolean;
  isShared: boolean;
  hasShareRequest: boolean;
}

Error Handling

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.

Common Error Types

HTTPConditionExpected integration behavior
400Malformed request or invalid query parameterCorrect the request. Do not retry as-is.
401JWT access credential missing, expired, or invalidRequest a new JWT access credential, then retry once.
403Service account lacks the required permission, or the account is lockedSurface access denied. Do not retry.
404Resource not foundSurface not found. Do not retry.
500, 503Service failureRetry with exponential backoff, maximum three attempts.

Retry Guidance

Read-only GET; safe to retry on 5xx or network timeout. Do not retry credential requests on 4xx.

Permissions & Scopes

Auth PatternService Account Credentials grant
Credential DeliveryAuthorization: Bearer {access_token}

GET
Get Account Hierarchy
/v1/accounts/{accountId}/hierarchy
›

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.

Ownership Stake

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).

Hierarchy Depth & Performance

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.

Request Parameters

ParameterLocationTypeRequiredDescription
accountIdpathstring (UUID)YesThe account identifier
depthqueryintegerOptionalLevels to traverse (min 0); omit or pass a large value (e.g. 9999) for the full tree
includeObacquerybooleanOptionalWhen true, append per-node OBAC metadata

Sample Request

typescript
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();

Response Template

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
  }
]

TypeScript Interface

typescript
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
}

Error Handling

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.

Common Error Types

HTTPConditionExpected integration behavior
400Malformed request or invalid query parameterCorrect the request. Do not retry as-is.
401JWT access credential missing, expired, or invalidRequest a new JWT access credential, then retry once.
403Service account lacks the required permission, or the account is lockedSurface access denied. Do not retry.
404Resource not foundSurface not found. Do not retry.
500, 503Service failureRetry with exponential backoff, maximum three attempts.

Retry Guidance

Read-only GET; safe to retry on 5xx or network timeout. Do not retry credential requests on 4xx.

Permissions & Scopes

Required PermissionGET_ACCOUNTS_HIERARCHY
Auth PatternService Account Credentials grant
Credential DeliveryAuthorization: Bearer {access_token}

GET
Get Account Wallets
/v1/accounts/{accountId}/wallets
›

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.

Request Parameters

ParameterLocationTypeRequiredDescription
accountIdpathstring (UUID)YesThe account identifier
offsetqueryintegerOptionalZero-based pagination offset (min 0)
countqueryintegerOptionalPage size (min 1)
depthqueryintegerOptionalDepth of hierarchy traversed when gathering linked wallets
includeObacquerybooleanOptionalWhen true, append per-wallet OBAC metadata

Sample Request

typescript
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();

Response Template

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
  }
]

TypeScript Interface

typescript
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
}

Error Handling

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.

Common Error Types

HTTPConditionExpected integration behavior
400Malformed request or invalid query parameterCorrect the request. Do not retry as-is.
401JWT access credential missing, expired, or invalidRequest a new JWT access credential, then retry once.
403Service account lacks the required permission, or the account is lockedSurface access denied. Do not retry.
404Resource not foundSurface not found. Do not retry.
500, 503Service failureRetry with exponential backoff, maximum three attempts.

Retry Guidance

Read-only GET; safe to retry on 5xx or network timeout.

Permissions & Scopes

Auth PatternService Account Credentials grant
Credential DeliveryAuthorization: Bearer {access_token}

GET
Get Account Activities
/v1/conversion/accounts/{accountId}/activities
›

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.

Request Parameters

ParameterLocationTypeRequiredDescription
accountIdpathstring (UUID)YesThe account identifier
startDatequerystring (date-time)OptionalInclusive start date and time of the requested interval. If specified, endDate must also be provided.
endDatequerystring (date-time)OptionalInclusive 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.
networksquerystring[]OptionalFilter activities by one or more networks
activityTypesquerystring[]OptionalFilter activities by one or more types
fromWalletIdquerystringOptionalThe 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.
toWalletIdquerystringOptionalThe 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.
searchForquerystringOptionalSearch filter; matches by CUSIP and Security
offsetqueryintegerOptionalPagination offset
countqueryintegerOptionalPage size

Sample Request

typescript
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();

Response Template

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.

TypeScript Interface

typescript
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 };
}

Error Handling

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.

Common Error Types

HTTPConditionExpected integration behavior
400Malformed request or invalid query parameterCorrect the request. Do not retry as-is.
401JWT access credential missing, expired, or invalidRequest a new JWT access credential, then retry once.
403Service account lacks the required permission, or the account is lockedSurface access denied. Do not retry.
404Resource not foundSurface not found. Do not retry.
500, 503Service failureRetry with exponential backoff, maximum three attempts. Continue to display account detail without activities.

Retry Guidance

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.

Permissions & Scopes

Auth PatternService Account Credentials grant
Credential DeliveryAuthorization: Bearer {access_token}

GET
Get Account Balances
/v1/conversion/accounts/{accountId}/balances
›

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.

Request Parameters

ParameterLocationTypeRequiredDescription
accountIdpathstring (UUID)YesThe account identifier; the same identifier used by /v1/accounts/{accountId}, and it must be accessible under the calling service account's permissions.
balancesDatequerystring (date-time)OptionalReturn balances as of this date and time. If omitted, the latest available balances are returned.
networksquerystring[]OptionalFilter by one or more networks.
walletIdquerystringOptionalAn optional wallet to filter by.
searchForquerystringOptionalSearch key filter; matches by CUSIP and Security.
orderByquerystringOptionalField to sort by. Accepts the AccountBalanceFields value Security (default Security).
sortOrderquerystringOptionalAscending or Descending (default Ascending).
offsetqueryinteger (int32)OptionalZero-based pagination offset (min 0).
countqueryinteger (int32)OptionalPage size (min 1).

Enumerations

Enumeration values must be provided exactly as they are defined; they are case-sensitive.

GET /v1/conversion/accounts/{accountId}/balances

DirectionParameter / FieldEnum NameValues
Input (query)orderByAccountBalanceFieldsSecurity
Input (query)sortOrderSortOrderAscending, Descending

Sample Request

typescript
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();

Response Template

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" }
}

TypeScript Interface

typescript
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
}

Response Metadata

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).

Error Handling

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.

Common Error Types

HTTPConditionExpected integration behavior
400Malformed request or invalid query parameterCorrect the request. Do not retry as-is.
401JWT access credential missing, expired, or invalidRequest a new JWT access credential, then retry once.
403Service account lacks the required permission, or the account is lockedSurface access denied. Do not retry.
404Resource not foundSurface not found. Do not retry.
500, 503Service failureRetry with exponential backoff, maximum three attempts.

Retry Guidance

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.

Permissions & Scopes

Auth PatternService Account Credentials grant
Credential DeliveryAuthorization: Bearer {access_token}

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.

Certification

Account Management Workflow Certification Test

CERT
Account Management Workflow Certification Test
Certification · v1 · Authenticate → Resolve via Roots → Retrieve Account → Retrieve Hierarchy → Retrieve Wallets → Activities + Balances
›

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.

Certification Workflow

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.

Authenticate

Obtain a JWT access credential using SA-AccountBot.

Resolve via Roots

GET /v1/accounts/roots
Discover root accounts and resolve the target accountId.

Retrieve Account

GET /v1/accounts/{accountId}
Confirm accountId and name.

Retrieve Hierarchy

GET /v1/accounts/{accountId}/hierarchy
Retrieve the child-account tree.

Retrieve Wallets

GET /v1/accounts/{accountId}/wallets
Retrieve linked wallets with ownership stake.

Activities + Balances (parallel)

GET /v1/conversion/accounts/{accountId}/activities and GET /v1/conversion/accounts/{accountId}/balances
Retrieve on-chain activities and reconcile balances.

Parallel branch: the activities and balances calls share only the 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.
Single grant for all steps: All steps use the Service Account Credentials grant. The JWT access credential issued in step one is reused for every subsequent call, including the activities and balances retrieval in step six.
Service AccountRoots ResolutionAccount RetrievalHierarchyWalletsActivities & Balances

Prerequisites

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.

Test Data

typescript
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!;

POST
Step 1 — Authentication
${baseUrl}/connect/token
›

Goal

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.

Procedure

typescript
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;
}

Expected Result

HTTP 200; JWT access credential returned; credential accepted by downstream APIs.

Common Error Types

HTTPConditionExpected integration behavior
400Invalid credentials; invalid_clientSurface authentication rejected. Do not retry with the same credentials.
500, 503Identity Server failureRetry with exponential backoff, maximum three attempts.

GET
Step 2 — Resolve Account via Roots
${baseUrl}/v1/accounts/roots
›

Goal

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.

Procedure

typescript
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();
}

Validation

typescript
// 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.

Expected Result

HTTP 200; root accounts returned; at least one accountId resolved; response successfully parsed.

Common Error Types

HTTPConditionExpected integration behavior
400Invalid query parameterCorrect the request. Do not retry as-is.
401Expired or invalid JWT access credentialRe-authenticate, then retry once.
403Insufficient permissionsSurface access denied. Do not retry.

GET
Step 3 — Retrieve Account
${baseUrl}/v1/accounts/${accountId}
›

Goal

Verify the integration can retrieve account information and interpret the account entity correctly.

Procedure

typescript
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();
}

Validation

typescript
{
  accountId: string,
  name: string,
  externalId: string | null
}

Confirm the response carries accountId and name.

Expected Result

HTTP 200; account returned; accountId matches the resolved request; name interpreted; response successfully parsed. The workflow requires account resolution before subsequent operations.

Common Error Types

HTTPConditionExpected integration behavior
401Expired or invalid JWT access credentialRe-authenticate, then retry once.
403Insufficient permissionsSurface access denied. Do not retry.
404Account not foundSurface account not found. Do not retry.

GET
Step 4 — Retrieve Hierarchy
${baseUrl}/v1/accounts/${accountId}/hierarchy
›

Goal

Verify the integration can retrieve the account's child-account hierarchy as a recursively nested tree.

Procedure

typescript
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();
}

Validation

typescript
// 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.

Expected Result

HTTP 200; hierarchy tree returned; child entities visible; ownershipStake present on each node; no parsing errors.

Common Error Types

HTTPConditionExpected integration behavior
401Expired or invalid JWT access credentialRe-authenticate, then retry once.
403Insufficient permissionsSurface access denied. Do not retry.
500, 503Service failureDisplay account detail without hierarchy and offer retry.

GET
Step 5 — Retrieve Wallets
${baseUrl}/v1/accounts/${accountId}/wallets
›

Goal

Verify the integration can retrieve the wallets linked to the account, each with its computed ownership stake and operational flags.

Procedure

typescript
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();
}

Validation

typescript
// 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.

Expected Result

HTTP 200; linked wallets returned; ownershipStake present on each wallet; data successfully parsed.

Common Error Types

HTTPConditionExpected integration behavior
400Invalid query parameterCorrect the request. Do not retry as-is.
401Expired or invalid JWT access credentialRe-authenticate, then retry once.
403Insufficient permissionsSurface access denied. Do not retry.
500, 503Service failureDisplay account detail without wallet detail and offer retry.

GET
Step 6 — Query Activities + Balances (parallel)
${baseUrl}/v1/conversion/accounts/${accountId}/activities & .../balances
›

Goal

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.

Procedure

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.

typescript
async 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)
]);

Validation — Activities (flat array)

typescript
// 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.

Validation — Balances (MetadataResponse 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.

typescript
{
  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.

typescript
for (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.

Expected Result

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.

Common Error Types

This endpoint returns distinct error envelope shapes depending on which layer rejects the request.

HTTPConditionResponse bodyExpected integration behavior
400Malformed authentication requesterrorCode, message, requestId, tracingUrlCorrect the request encoding and verify all required fields are present. Do not retry as-is.
401Invalid service account credentialserrorCode, message, requestId, tracingUrlAuthentication rejected. Verify credentials before retrying.
401Expired or missing access token; GATEWAY__UNAUTHENTICATEDErrorCode, ErrorMessageRe-authenticate, then retry once.
403Service account lacks the required permission for this accounterrorCode, message, requestId, tracingUrlConfirm the service account was granted the balances permission. Do not retry.
403Token does not grant access to this account; GATEWAY__ACCESSDENIEDErrorCode, ErrorMessageSurface access denied. Do not retry.
403User locked out; AUTHORIZATION_ENGINE__USER_LOCKED_OUT_EXCEPTIONErrorCode, ErrorMessageSurface the lockout. Do not retry until the lockout is cleared.
404Account identifier does not exist or is not accessibleerrorCode, message, requestId, tracingUrlValidate the account identifier before calling. Do not retry without correcting it.
500, 503Service failureerrorCode, errorMessageRetry with exponential backoff and a bounded retry count. Surface the failure once retries are exhausted and terminate the workflow safely.

Token Lifecycle and Resilience

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.


E2E
Step 7 — End-to-End Workflow Execution
authenticate → getRootAccounts → getAccount → getHierarchy → getWallets → (getActivities ∥ getBalances)
›

Goal

Execute the complete workflow in a single transaction, resolving the account via roots and issuing the activities and balances calls in parallel.

Procedure

typescript
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 };
}

Expected Result

log
Authenticate              PASS
Resolve via Roots         PASS
Retrieve Account          PASS
Retrieve Hierarchy        PASS
Retrieve Wallets          PASS
Query Activities          PASS
Query Balances            PASS
Workflow Complete         PASS

Each constituent call returns its expected success code.

Negative Test Cases

IDScenarioHTTPExpected result
NT-1Invalid Credentials400Authentication rejected with invalid_client. Invalid service account credentials are an expected authentication failure scenario.
NT-2Expired Credential401Re-authentication required.
NT-3Invalid Account404Account Not Found.
NT-4Access Denied403Access Denied for insufficient permissions.
NT-5Activity Service Failure500, 503Account data remains available, activity retrieval fails gracefully, and the user receives a clear error message.
NT-6Invalid Service Account Credentials (Step 6)401Authentication rejected. Verify credentials before retrying.
NT-7Insufficient Permission (Step 6)403Access denied. Confirm the service account was granted the balances permission.
NT-8Expired Balance Token (Step 6)401Re-authentication required; GATEWAY__UNAUTHENTICATED.
NT-9Unauthorized Account Access (Step 6)403Access denied; GATEWAY__ACCESSDENIED.
NT-10Locked Out User (Step 6)403Lockout detected; AUTHORIZATION_ENGINE__USER_LOCKED_OUT_EXCEPTION.
NT-11Malformed Authentication Request (Step 6)400Bad request. Correct the request encoding and confirm all required fields are present.
NT-12Balance Service Failure (Step 6)500, 503Retry logic executed, failure reported, and the workflow terminated safely.

Production Certification Criteria

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.

Category 2
Wallet Management

Wallet Management covers wallet inventory used to support wallet administration and status tracking. This guide version focuses on wallet discovery and status-tracking APIs.

Wallet registration: Wallet registration is performed through the UI and is not available through the API.
Authentication pattern: These workflows use the Service Account Credentials grant. The token request is sent to /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.

Workflow Summary

A condensed view of the API call sequence, dependencies, and branch rules.

Authenticate

POST /connect/token
Obtain service-account token.

Load wallets

GET /v1/conversion/wallets
Display current wallet inventory.

Track status

Use wallet inventory views to monitor wallet state and status changes.

Service AccountWallet InventoryStatus Tracking
GET
List Registered Wallets
/v1/conversion/wallets
›

Loads existing wallets for inventory display and status review.

Request Parameters

ParameterLocationTypeRequiredDescription
searchForquerystringOptionalSearch for term. Maximum length 256 characters.
walletAddressquerystringOptionalThe wallet address. Maximum length 256 characters.
typequerystringOptionalThe wallet type: Internal or Client
networksquerystring[]OptionalA list of networks
idsquerystring[]OptionalA list of wallet identifiers
includeObacquerybooleanOptionalWhen true, the response includes access control metadata
eligiblyOnlyquerybooleanOptionalFilter by conversion eligibility
namequerystringOptionalThe wallet name
orderBy / sortOrderquerystringOptionalSorting controls
offset / countqueryintegerOptionalPagination controls

Enumerations

Enumeration values must be provided exactly as they are defined; they are case-sensitive.

GET /v1/conversion/wallets

DirectionParameter / FieldEnum NameValues
Input (query)orderByWalletFieldsName, Network, CreatedAt
Input (query)sortOrderSortOrderAscending, Descending
Output (response)typeWalletTypesInternal, Client
Output (response)stateProcessingStatesIdle, Registering, Deleting, FailedCompliance, Failed

Sample Request

typescript
const walletsResponse = await fetch(`${baseUrl}/v1/conversion/wallets`, {
  headers: { 'Authorization': `Bearer ${access_token}` }
});
const wallets = await walletsResponse.json();

Response Template

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 }
]

TypeScript Interface

typescript
interface WalletSummary {
  id: string;
  name: string;
  type: string;
  network: string;
  walletAddress: string;
  state: string;
  trackingWalletId: string;
  account: AccountDetails;
  conversionEligible: boolean;
  failureReason: string | null;
}

Error Handling

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.

Common Error Types

HTTPConditionExpected integration behavior
400Malformed request or invalid query parameterCorrect the request. Do not retry as-is.
401JWT access credential missing, expired, or invalidRequest a new JWT access credential, then retry once.
403Service account lacks the required permission, or the account is lockedSurface access denied. Do not retry.
404Resource not foundSurface not found. Do not retry.
500, 503Service failureRetry with exponential backoff, maximum three attempts. Terminate the inventory view safely if the failure persists.

Retry Guidance

Read-only GET; safe to retry on 5xx or network timeout.

Permissions & Scopes

Auth PatternService Account Credentials grant
Credential DeliveryAuthorization: Bearer {access_token}

Cross-service dependency: the DTCC APIs provide wallet inventory data used by wallet administration views.
Certification

Wallet Management Workflow Certification Test

CERT
Wallet Management Workflow Certification Test
Certification · v1 · Authenticate → Load Wallets → Review → Track Status
›

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.

Certification Workflow

Authenticate once, load wallet inventory, then review inventory and track status.

Authenticate

Obtain a JWT access credential using SA-WalletReader.

Load Wallet Inventory

GET /v1/conversion/wallets

Review Inventory

Review the wallet inventory records.

Track Status

Extract and review wallet status values.

Sequence: Inventory review runs after wallet inventory loads.
AuthenticationWallet InventoryStatus Tracking

Prerequisites

Tenant ID, service account, service account password, base URL, and known wallet data. Required access: /connect/token, /v1/conversion/wallets.

Test Data

typescript
const tenantName = "<tenant-name>"; // recommended, e.g. "DTCC-DA"
const baseUrl = "<base-url>";
const username = "SA-WalletReader";
const password = process.env.SERVICE_ACCOUNT_PASSWORD!;

Shared Helper Functions

typescript
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();
}

POST
Step 1 — Authentication
${baseUrl}/connect/token
›

Goal

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.

Procedure

typescript
const accessToken = await authenticate();

Expected Result

HTTP 200; JWT access credential returned; credential accepted by downstream APIs. Evidence: authentication successful, credential received.

Common Error Types

HTTPConditionExpected integration behavior
400Invalid credentials; invalid clientSurface authentication rejected. Do not retry with the same credentials.
500, 503Identity Server failureRetry with exponential backoff, maximum three attempts.

GET
Step 2 — Load Wallet Inventory
${baseUrl}/v1/conversion/wallets
›

Goal

Verify wallet inventory can be retrieved.

Procedure

typescript
const wallets = await getWallets(accessToken);

Validation

Wallet data returned; response is non-empty; wallet identifiers present.

Expected Result

HTTP 200; wallet inventory successfully loaded. Evidence: wallet inventory response, wallet count.

Common Error Types

HTTPConditionExpected integration behavior
400Invalid query parameters such as an invalid sort field or malformed filterCorrect the request. Do not retry as-is.
401Expired or invalid JWT access credentialRe-authenticate, then retry once.
403Missing permissionSurface access denied. Do not retry.
500, 503Wallet endpoint failureInventory unavailable; surface the failure and terminate the workflow safely.

GET
Step 3 — Review Wallet Inventory
review wallet inventory records
›

Goal

Verify wallet inventory can be reviewed.

Procedure

typescript
const inventoryView = wallets.map(wallet => ({
  wallet,
  account: wallet.account
}));

Validation

Wallets visible; wallets associated with account data; inventory records complete.

Expected Result

Inventory review completed. Evidence: sample wallet records.

Common Error Types

This step performs no additional API calls. Review the wallet inventory returned in Step 2.


GET
Step 4 — Track Wallet Status
extract wallet status values
›

Goal

Verify wallet status data is visible and reviewable.

Procedure

typescript
const walletStatuses = wallets.map(wallet => ({
  walletId: wallet.id,
  state: wallet.state
}));

Validation

state field available; state values populated; states can be reported.

Expected Result

Wallet state visible; wallet state review completed. Evidence: state report, sample wallet states.

Common Error Types

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.


E2E
Step 5 — End-to-End Workflow Execution
executeWalletWorkflow()
›

Goal

Execute the complete wallet management workflow in a single run to confirm every stage succeeds in sequence.

Procedure

typescript
async function executeWalletWorkflow() {
  const token = await authenticate();
  const wallets = await getWallets(token);
  return { wallets };
}

Expected Result

log
Authenticate      PASS
Load Wallets      PASS
Review Inventory  PASS
Track Status      PASS
Workflow Complete PASS

Each constituent call returns its expected success code.

Negative Test Cases

IDScenarioHTTPExpected result
NT-1Invalid Credentials400Authentication rejected; invalid client.
NT-2Expired Credential401Re-authentication required.
NT-3Missing Permission403Access denied.
NT-4Invalid Query Parameters400Validation error, for example an invalid sort field or malformed filter.
NT-5Wallet Endpoint Failure500, 503Inventory unavailable; failure surfaced; workflow terminated safely.

Production Certification Criteria

A customer is certified only on successful authentication, wallet inventory retrieval, inventory review, and wallet-status review, plus proper handling of all negative tests.

Category 3
Conversion Orders

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.

Authentication pattern: These workflows use the Service Account Credentials grant. The token request is sent to /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.

Workflow Summary

A condensed view of the API call sequence, dependencies, and branch rules.

Authenticate

POST /connect/token
Obtain service-account token.

Load securities and filters

GET /v1/conversion/securities
GET /v1/conversion/securities/issue-types
GET /v1/conversion/securities/issue-subtypes in parallel.

Load order inputs

GET /v1/conversion/securities?status=Active
GET /v1/conversion/wallets in parallel.

Filter eligibility

Use Active securities and wallets that are Idle and conversion eligible.

Submit order

POST /v1/conversion/orders
Returns 202 Accepted with no body. Retain the idempotency key.

Poll async operation

POST /v1/conversion/async-operations/query
Poll with the idempotency key until resourceId is populated.

Retrieve order detail

GET /v1/conversion/orders/{orderId}
Use resourceId as the order identifier.

Track lifecycle

Orders are processed straight through from Processing to Completed. Failed is terminal.

Order rule: Submission requires an idempotency key, an Active security, wallets that are Idle and conversion eligible, valid conversion direction, quantity greater than zero, and server-side operational-hours compliance. Because submission returns no body, the idempotency key is the only handle on the order until the async operation exposes resourceId.
Service AccountParallel LoadingEligibilityIdempotencyAsync Polling
GET
List Registered Securities and Filter Data
/v1/conversion/securities · /v1/conversion/securities/issue-types · /v1/conversion/securities/issue-subtypes
›

Fetches a paginated securities list alongside issue type and issue sub-type reference data.

Request Parameters

ParameterLocationTypeRequiredDescription
Offset / CountqueryintegerOptionalControls which slice of the securities list is returned, where offset sets the starting position and count sets the number of records per page.
searchForquerystringOptionalFree-text term matched against issuer name, security name, or CUSIP to narrow the securities list.
networksquerystring[]OptionalRestricts 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.
issueTypeIdsqueryinteger[] (int32)OptionalRestricts 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.
issueSubTypeIdsqueryinteger[] (int32)OptionalRestricts 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.
statusquerystringOptionalRestricts results to securities in a single lifecycle status. Accepts one FinancialSecurityStatus value: Onboarding, Active, Pause, or Failed.
orderBy / sortOrderquerystringOptionalDetermines which field the securities list is ordered on and whether that order runs ascending or descending.

Enumerations

Enumeration values must be provided exactly as they are defined; they are case-sensitive.

GET /v1/conversion/securities

DirectionParameter / FieldEnum NameValues
Input (query)orderByFinancialSecurityFieldsCUSIP, Description, Issuer
Input (query)sortOrderSortOrderAscending, Descending
Input (query)statusFinancialSecurityStatusOnboarding, Active, Pause, Failed
Output (response)statusFinancialSecurityStatusOnboarding, 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.

Sample Request

typescript
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();

Response Template

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 }
    }
  }
]

TypeScript Interface

typescript
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; }

Business Rules

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.

Status and Restrictions Are Separate Signals

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.

FieldRestrictionWhat it means
doChillDelivery Order (DO) ChillA temporary restriction on transfers, typically while a settlement or verification is pending.
globalLockGlobal LockA block on all transfers of the token, typically during a corporate action or a regulatory investigation.
complianceLockCompliance LockA block on transfers imposed for regulatory or compliance reasons, for example a sanctions concern.
transferLockTransfer LockA block on transfers of the token imposed at the security level, independent of the chill, global lock, and compliance lock signals.
How to tell if a security is restricted: Read the security, then inspect its 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.
json · restrictions block
"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 restriction
function 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);

Error Handling

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.

Common Error Types

HTTPConditionExpected integration behavior
400Malformed request or invalid query parameterCorrect the request. Do not retry as-is.
401JWT access credential missing, expired, or invalidRequest a new JWT access credential, then retry once.
403Service account lacks the required permission, or the account is lockedSurface access denied. Do not retry.
404Resource not foundSurface not found. Do not retry.
500, 503Service failureRetry with exponential backoff, maximum three attempts. Disable only the affected filter rather than the whole view.

Retry Guidance

All four endpoints are read-only GETs and safe to retry on 5xx or network timeout.

Permissions & Scopes

Auth PatternService Account Credentials grant
Credential DeliveryAuthorization: Bearer {access_token}

GET
Load Active Securities and Registered Wallets
/v1/conversion/securities · /v1/conversion/wallets
›

Loads order-entry inputs in parallel and filters wallets to Idle state.

Request Parameters

ParameterLocationTypeRequiredDescription
statusquerystringOptionalActive
Offset / CountqueryintegerOptionalPagination controls

Enumerations

Enumeration values must be provided exactly as they are defined; they are case-sensitive.

GET /v1/conversion/securities

DirectionParameter / FieldEnum NameValues
Input (query)orderByFinancialSecurityFieldsCUSIP, Description, Issuer
Input (query)sortOrderSortOrderAscending, Descending
Output (response)statusFinancialSecurityStatusOnboarding, Active, Pause, Failed

GET /v1/conversion/wallets

DirectionParameter / FieldEnum NameValues
Input (query)orderByWalletFieldsName, Network, CreatedAt
Input (query)sortOrderSortOrderAscending, Descending
Output (response)typeWalletTypesInternal, Client
Output (response)stateProcessingStatesIdle, Registering, Deleting, FailedCompliance, Failed

Sample Request

typescript
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');

Response Template

json
{
  "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 }
  ]
}

TypeScript Interface

typescript
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;
}

Eligibility Rules

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.

Error Handling

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.

Common Error Types

HTTPConditionExpected integration behavior
400Malformed request or invalid query parameterCorrect the request. Do not retry as-is.
401JWT access credential missing, expired, or invalidRequest a new JWT access credential, then retry once.
403Service account lacks the required permission, or the account is lockedSurface access denied. Do not retry.
404Resource not foundSurface not found. Do not retry.
500, 503Service failureRetry with exponential backoff, maximum three attempts. Block order submission until inputs load successfully.

Retry Guidance

Both calls are read-only GETs and safe to retry on 5xx or network timeout.

Permissions & Scopes

Auth PatternService Account Credentials grant
Credential DeliveryAuthorization: Bearer {access_token}

POST
Submit and Track Conversion Orders
/v1/conversion/orders · /v1/conversion/async-operations/query · /v1/conversion/orders/{orderId}
›

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.

Request Parameters

GET /v1/conversion/orders

ParameterLocationTypeRequiredDescription
searchForquerystringOptionalFree-text search key filter
fromWalletquerystringOptionalSource wallet identifier filter
toWalletquerystringOptionalDestination wallet identifier filter
updateFrom / updateToquerystringOptionalLower and upper bounds of the update date range
idsqueryarrayOptionalFilter by specific order identifiers
financialSecurityIdsqueryarrayOptionalFilter by security identifiers
statusqueryarrayOptionalFilter by order status
originqueryarrayOptionalFilter by how the order was originated
includeObacquerybooleanOptionalInclude access control metadata when true
orderBy / sortOrderquerystringOptionalSorting controls
Offset / CountqueryintegerOptionalPagination controls

POST /v1/conversion/orders

ParameterLocationTypeRequiredDescription
X-Idempotency-KeyheaderstringYesMax 255 characters; prevents duplicate submissions. Retain this value for the async operation query.
financialSecurityIdbodystringYesSecurity being converted
fromWalletIdbodystringYesThe 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.
toWalletIdbodystringYesThe 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.
activityTypebodystringYesMemoSeg 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.
quantitybodyinteger (int32)YesAmount to convert; must be greater than zero

POST /v1/conversion/async-operations/query

ParameterLocationTypeRequiredDescription
idempotencyKeysbodyarrayYesOne 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 / CountbodyintegerYesPagination controls; both are required on this request body.
orderBybodystring (enum)YesField to sort by. Accepts the AsyncOperationOrderFields value CreatedAt.
sortOrderbodystring (enum)YesSort direction. See SortOrder allowed values: Ascending, Descending.

GET /v1/conversion/orders/{orderId}

ParameterLocationTypeRequiredDescription
orderIdpathstringYesOrder identifier, taken from resourceId on the async operation response

Batch Query Behavior

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.

BehaviorDetail
Unmatched keysSubmitting 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.
PaginationThe 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 sizeSubmit no more than 100 keys per request to avoid the performance impact of very large arrays.

Enumerations

Enumeration values must be provided exactly as they are defined; they are case-sensitive.

GET /v1/conversion/orders

DirectionParameter / FieldEnum NameValues
Input (query)orderByOrderFieldsCreatedAt, UpdatedAt
Input (query)sortOrderSortOrderAscending, Descending
Input (query)statusOrderStatusProcessing, Completed, Failed
Input (query)originOrderOriginParticipant, Admin, ForcedReconversion
Output (response)statusOrderStatusProcessing, Completed, Failed
Output (response)originOrderOriginParticipant, Admin, ForcedReconversion

POST /v1/conversion/async-operations/query

DirectionParameter / FieldEnum NameValues
Input (body)orderByAsyncOperationOrderFieldsCreatedAt
Input (body)sortOrderSortOrderAscending, Descending
Output (response)objectKindObjectKindUndefined, Order, Wallet, FinancialSecurity
Output (response)statusAsyncOperationStatusNew, Processing, Completed, Failed
Output (response)operationNameOperationNameUndefined, Register, Submit, Import

GET /v1/conversion/orders/{orderId}

DirectionParameter / FieldEnum NameValues
Output (response)statusOrderStatusProcessing, Completed, Failed
Output (response)originOrderOriginParticipant, 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.

Sample Request

GET /v1/conversion/orders

typescript
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

typescript
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

typescript
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}

typescript
const detailResponse = await fetch(`${baseUrl}/v1/conversion/orders/${orderId}`, {
  headers: { 'Authorization': `Bearer ${access_token}` }
});
const orderDetail: OrderDetailResponse = await detailResponse.json();
// orderDetail.status === 'Processing'

Response Template

GET /v1/conversion/orders

json
[
  {
    "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

json
[
  {
    "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}

json
{
  "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.

Transaction Identifiers

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.

FieldContains
fromTransactionIdThe on-chain ledger transaction hash for the source (debit) leg of the conversion — for example, a Burn on Besu such as 0x639dc5....
toTransactionIdThe 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.

Relationship to external custody or validator providers (for example, Fireblocks): The transaction hash originates from the underlying ledger (Besu or Canton), not from the Conversion Service. When an external custody or validator provider surfaces the on-chain transaction hash for the same settled ledger event, that value matches the corresponding 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.

TypeScript Interface

typescript
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;
}

Business Rules

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.

Error Handling

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.

Common Error Types

HTTPConditionExpected integration behavior
400Malformed request, missing X-Idempotency-Key, quantity of zero, or wallet identifier not found see Error Code Reference belowCorrect the request. Do not retry as-is.
401JWT access credential missing, expired, or invalidRequest a new JWT access credential, then retry once.
403Service account lacks the required permission, or the account is lockedSurface access denied. Do not retry.
404Security or order identifier not found see Error Code Reference belowSurface not found. Do not create a replacement order.
409Duplicate X-Idempotency-Key, or a conflicting wallet already exists see Error Code Reference belowTreat the order as already submitted. Query the async operation with the same key to resolve the existing order identifier.
422Business rule violation such as invalid conversion direction, ineligible security, ineligible wallet, or submission outside operational hoursSurface the specific rule violation. Do not retry until the input is corrected.
500Unhandled or infrastructure failure see Error Code Reference belowNot retryable without platform investigation. Surface the failure and escalate.
503Service failureRetry with the same X-Idempotency-Key, maximum three attempts.
Reference

Error Code Reference

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.

HTTP 400 — Bad Request

Error CodeCauseCorrection
ConversionOperationsEngine__InvalidQuantityquantity ≤ 0.Submit with a positive quantity.
ConversionOperationsEngine__SameOrderWalletsfromWalletId and toWalletId are identical.Use two distinct wallet IDs.
ConversionOperationsEngine__SameWalletLedgersBoth wallets are on the same network.Use wallets on different networks.
ConversionOperationsEngine__WalletIsNotConversionEligibleThe wallet has conversionEligible = false.Use a wallet that has completed registration and is marked eligible.
ConversionOperationsEngine__OperationCannotBePerformedThe wallet's processingState is not Idle.Wait for wallet registration to complete before submitting.
ConversionOperationsEngine__OrderFinancialInstrumentRequiredfinancialSecurityId was not provided.Include financialSecurityId in the request body.
ConversionOperationsEngine__InactiveFinancialSecurityOrderCreatingExceptionThe referenced security is not in Active status.Use an active security.
ConversionOperationsEngine__OutsideAllowedTimeWindowRequest submitted outside operational hours or on a holiday.Resubmit during the operational window.
ConversionOperationsEngine__InvalidOrderActivityTypeactivityType is not a supported value.Use a supported activity type code.
ConversionOperationsEngine__InvalidWalletAddressThe wallet address is not valid for the specified network.Correct the address format.
ConversionOperationsEngine__WalletNotFoundThe wallet ID does not exist or is not accessible to your tenant.Verify the wallet ID.

HTTP 404 — Not Found

Error CodeCauseCorrection
ConversionOperationsEngine__OrderNotFoundThe order ID does not exist or is not accessible.Verify the order ID.
ConversionOperationsEngine__FinancialSecurityNotFoundThe financialSecurityId does not exist.Verify the financial security ID.

HTTP 409 — Conflict

Error CodeCauseCorrection
AsyncOperation__AsyncOperationAlreadyExistsThe 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__WalletAlreadyExistsA wallet with the same address and network already exists in your tenant.Use the existing wallet or register with a different address.
ConversionOperationsEngine__WalletWithSameNameAlreadyExistA wallet with the same name already exists in your tenant.Choose a different wallet name.

HTTP 500 — Internal Server Error

Unhandled or infrastructure failures. The errorCode value is "500". Not retryable without platform investigation.

Reference

Delivery Order Error & Status Codes

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.

Error Codes (Delivery Order NACK)

6 buckets · 90 codes. Click a bucket to expand, or type to filter.

Participants & Accounts35›
Error CodeFieldExplanation
CAAL-9AAAReceiving ParticipantThe receiving participant is invalid.
CAAL-9AALReceiving ParticipantPast cutoff refer to documentation
CAAL-9AANReceiving ParticipantNot eligible for processing
CAAL-9AAUReceiving ParticipantChilled for SDFS valued DO(s)
CAAL-9AAWReceiving ParticipantChilled for SDFS free DO(s)
CAAL-9AAYReceiving ParticipantNot SDFS eligible
CAAL-9ABBReceiving ParticipantNot Found
CAAL-9ABDReceiving ParticipantMissing
CAAL-9ACKReceiving ParticipantGlobal lock
CAAL-9ACQReceiving ParticipantChilled for MMI securities
CAAL-9ACSReceiving ParticipantOnly eligible for MMI securities
CAAL-9AFTReceiving ParticipantReceiving participant mismatch. Receiver is 881 for SFT Stock Loans
CAAL-IAEMReceiving ParticipantNot OCC hedge eligible
CAAM-9AAADelivering ParticipantThe delivering participant is invalid.
CAAM-9AAEDelivering ParticipantInvalid data refer to documentation
CAAM-9AAUDelivering ParticipantChilled for SDFS valued DO(s)
CAAM-9AAWDelivering ParticipantChilled for SDFS free DO(s)
CAAM-9AAYDelivering ParticipantNot SDFS eligible
CAAM-9ABBDelivering ParticipantNot found on Master Tables
CAAM-9ABDDelivering ParticipantMissing
CAAM-9ACKDelivering ParticipantGlobal lock
CAAM-9ACQDelivering ParticipantChilled for MMI securities
CAAM-9ACSDelivering ParticipantOnly eligible for MMI securities
CAAM-IAEMDelivering ParticipantNot OCC hedge eligible
CAAU-9AAAID AgentInvalid
CAAU-9ABBID AgentID Agent Not Found in IPO Database
CABB-9AAACustomerDefault Can Affect Future Do
CABB-9ABECustomerInternal Customer Is Required
CABB-9ABZCustomerInternal Customer Not in IPO Database
CABE-9AAAInternal Account NumberInvalid
CABL-9AAACorrespondent AccountInvalid
CABL-9ABECorrespondent AccountRequired
CAGX-9ABDDeliverer Account IDMissing
CAGY-9ABDReceiver Account IDMissing
CRCF-9AAADepository Third PartyInvalid
Security & CUSIP13›
Error CodeFieldExplanation
GAAA-9AAACUSIPInvalid
GAAA-9AAHCUSIPData equal to zero
GAAA-9AAICUSIPInvalid format Bonds for CNS must be round lot
GAAA-9AALCUSIPPast cutoff-refer to documentation
GAAA-9AANCUSIPNot eligible for processing
GAAA-9ABBCUSIPNot Found on DTC Master Table
GAAA-9ABDCUSIPMissing
GAAA-9ACKCUSIPGlobal lock
GAAA-9ACNCUSIPChilled
GAAA-IAEMCUSIPNot OCC hedge eligible
GAAA-IAENCUSIPNot RAD eligible
GAHT-9AAAObligation Warehouse Control NumberInvalid
JAAM-IAENMMI Input RecordNot RAD eligible
Amounts & Quantities13›
Error CodeFieldExplanation
DAAD-9AAAIPO calculationInvalid Price per Share or Net Amount
DAAS-9AAAFractional Shares Quantity (IPO Verification)Invalid
DAAT-9AAHSettlement AmountFor valued DOs, must be > zero.
DAAT-9AALSettlement AmountPast cutoff-refer to documentation
DAAT-9ACGSettlement AmountMust equal 0
DAAT-IAEMSettlement AmountNot OCC hedge eligible
DABB-9AAAShares QuantityInvalid
DABB-9AAFShares QuantityNon-numeric data
DABB-9AAHShares QuantityData equal to zero-(returned by IPO verification). Must be >zero.
DABB-9AA2Shares QuantityGreater than 50,000,000 for valued DO(s)
DABB-9ACPShares QuantityInsufficient position
DABB-9ADHShares QuantityLess than minimum denomination
DABB-9AAIShares QuantityNot multiple of 1000 (CNS bond deliveries)
Dates7›
Error CodeFieldExplanation
BAAA-9AAASettlement DateInvalid
BAAA-9AAFSettlement Datenot numeric
BAAA-9AAJSettlement Datenot valid at cross border depository
BAAA-9ABDSettlement DateMissing
BAAA-9ABLSettlement DateGreater than Current Date
BAAB-9ABETrade DateRequired
BAAB-9AAFTrade Datenot numeric
Transaction Details & Indicators16›
Error CodeFieldExplanation
CAGN-9ABBTransaction NumberNot found
CAGN-IAEMTransaction NumberNot OCC hedge eligible
CAGN-MAADTransaction NumberMaturity date is less than current date
CAHM-9ABDCustomer Reference NumberMissing
CAHN-9AAAPartner Reference NumberInvalid
EAAP-9AAAMoney Indicator (IPO)Invalid
EABF-9AAASell/Buy IndInvalid
EABF-9AAESell/Buy IndInvalid data-refer to documentation
EABG-9AAECDO IndicatorInvalid data-refer to documentation
GACA-9AAAActivity CodeInvalid-must be 026
GACA-IAELActivity CodeIPO Activity Code Invalid (IPOVFYOC)
GAHL-9AAAReason CodeInvalid
GAHL-9AAEReason CodeInvalid data-refer to documentation
GAHL-9AAFReason CodeNon-numeric data
GAHL-9AFTReason CodeReason Code Mismatch.
GAHL-9AFFReason CodeReason Code Invalid Data.
IPO & Special Processing6›
Error CodeFieldExplanation
CABC-9AAAIPO VerificationInvalid IDS Link Time
EAAA-9AAAMerrill to Merrill DO for IPO IssueInvalid
EAE3-9AAAIDS Trade Ind (IPO)Invalid
GAHO-0004OtherReference Key must be alphanumeric.
GAHO-9AAIOtherReference Key Invalid Format–refer to documentation on Comments field position 502-721.
GAHO-9AELOtherReference Key Missing or Invalid. Comments are required in the first 17 characters of the field.

Status Codes (Delivery Order to ATP)

Status CodeDescriptionStatus
RJCIRejected in IMSFailed
RJCTRejected in ATPFailed
PDRPDropped in ATP, due to position validationFailed
XPERFailed due to insufficient positionFailed
CANACancelled in ATPFailed
CANCCancelled in IMSFailed
CANSCancelled in staging areaFailed
INELInEligibleFailed
UNPRUnprocessedFailed
PDRIIMS Permanently DroppedFailed
RDPRDropped by ATP To Be ReintroducedFailed
RJCFIMS Rejected to FileFailed
DATPPDC Reduction Dropped in ATPFailed

Retry Guidance

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.

Permissions & Scopes

Auth PatternService Account Credentials grant
Credential DeliveryAuthorization: Bearer {access_token}
Operational WindowMonday to Friday, 02:00 to 18:00 ET
Business RuleConversion direction must be DTC_Classic to non-Classic or vice versa
Cross-service dependency: the DTCC APIs provides securities, wallets, and order management. the DTCC APIs provides ledger/network reference data for filtering.
Certification

Conversion Order Certification Tests

CERT
Conversion Order Certification Tests
Certification · v2 · Auth → Reference Data → Eligibility → Submit → Async → Retrieve → Lifecycle → Audit
›

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.

Certification Workflow

Authenticate, load reference data in parallel, validate eligibility, submit, then track the order asynchronously to a terminal state.

Authenticate

Service Account Credentials grant against /connect/token.

Load Reference Data

Orders, securities, and wallets in parallel, plus issue type, issue sub-type, and ledger filters.

Validate Security

Security status equals Active.

Validate Wallet

Wallet state equals Idle and conversionEligible is true.

Submit Order

POST /v1/conversion/orders returns 202 Accepted with no body.

Track Async Operation

Query by X-Idempotency-Key until a terminal status.

Correlate To Order

resourceId resolves the order identifier.

Retrieve Order Detail

GET /v1/conversion/orders/{orderId}.

Validate Lifecycle And Audit

Processing to Completed, then reconstruct the audit trail.

Order submission rule: Submission does not execute the conversion and returns no response body. Completion must be determined through async operation tracking rather than assumed from the submission response. Enforcement of operational hours, idempotency, direction, and eligibility occurs server side at submission time.
Service AccountParallel LoadingEligibilityIdempotencyAsync TrackingAudit

Key Business Rules

RuleRequirement
Security EligibilityKnown security states are Onboarding, Active, Pause, and Failed. Only Active securities are eligible for conversion-order creation.
Wallet EligibilityKnown wallet states are Idle, Registering, Deleting, FailedCompliance, and Failed. Only wallets that are Idle and conversion eligible may be used.
Conversion DirectionConversion must occur between DTC Classic and digital wallets.
Quantity ValidationQuantity must be greater than zero.
IdempotencyEvery submission must include X-Idempotency-Key. The same key must remain traceable throughout asynchronous processing.
Asynchronous ProcessingOrder creation returns HTTP 202 Accepted. Completion is determined through async operation tracking, not from the submission response.
Operational HoursMonday to Friday, 02:00 ET to 18:00 ET. Enforcement is server-side.

Test Data

typescript
const tenantName = "<tenant-name>"; // recommended, e.g. "DTCC-DA"
const baseUrl = "<base-url>";
const username = "SA-ConversionBot";
const password = process.env.SERVICE_ACCOUNT_PASSWORD!;

Shared Helper Functions

typescript
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();
}

POST
Step 1 — Authentication
${baseUrl}/connect/token
›

Goal

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.

Procedure

typescript
const accessToken = await authenticate();

Validation

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.

Expected Result

HTTP 200; credential issued and usable.

Common Error Types

HTTPConditionExpected integration behavior
400Invalid service account credentials or malformed grant requestCorrect the credentials. Do not retry with the same values.
403Service account lacks the required permissionSurface the permission failure. Do not retry.
500, 503Identity service failureRetry with exponential backoff, maximum three attempts.

GET
Step 2 — Reference Data Retrieval
loadReferenceData() · loadFilterData()
›

Goal

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.

Procedure

typescript
const { orders, securities, wallets } = await loadReferenceData(accessToken);
const { issueTypes, issueSubTypes } = await loadFilterData(accessToken);

Validation

Order inventory returned. Security inventory returned. Wallet inventory returned. Issue type reference data returned. Issue sub-type reference data returned. Ledger network data returned.

Expected Result

HTTP 200 on each call; all six data sets available for downstream steps.

Common Error Types

HTTPConditionExpected integration behavior
401Expired or invalid access credentialRe-authenticate, then retry once.
403Service account lacks the required permissionSurface access denied. Do not retry.
500, 503Service failureRetry with exponential backoff. Each call fails independently, so present a partial state rather than blocking the whole load.

GET
Step 3 — Security Validation
status equals Active
›

Goal

Verify that a valid conversion security can be identified from the security inventory loaded in Step 2.

Procedure

typescript
const security = securities.find(security => security.status === "Active");

Validation

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.

Expected Result

Eligible security identified.

Common Error Types

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.


GET
Step 4 — Wallet Validation
state equals Idle and conversionEligible is true
›

Goal

Verify that suitable source and destination wallets can be selected from the wallet inventory loaded in Step 2.

Procedure

typescript
const eligibleWallets = wallets.filter(
  wallet => wallet.state === "Idle" && wallet.conversionEligible === true
);

Validation

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.

Expected Result

Eligible wallets identified.

Common Error Types

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.


POST
Step 5 — Order Submission
${baseUrl}/v1/conversion/orders
›

Goal

Verify that a conversion order can be submitted with a valid idempotency key and accepted for asynchronous processing.

Procedure

typescript
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"
  })
});

Validation

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.

Expected Result

HTTP 202 Accepted with no response body.

Common Error Types

HTTPConditionExpected integration behavior
400Malformed request, missing X-Idempotency-Key, or quantity of zeroCorrect the request. Do not retry as-is.
403Service account lacks the required permission, or the account is lockedSurface access denied. Do not retry.
409Duplicate X-Idempotency-KeyTreat the order as already submitted. Query the async operation with the same key to resolve the existing order.
422Business rule violation such as invalid direction, ineligible security, ineligible wallet, or submission outside operational hoursSurface the specific rule violation. Do not retry until the input is corrected.
500, 503Service failureRetry with the same X-Idempotency-Key, maximum three attempts.

POST
Step 6 — Idempotency Validation
duplicate submission with same X-Idempotency-Key
›

Goal

Verify that resubmitting an identical request with the same idempotency key does not create a duplicate order.

Procedure

Submit the same order request twice using the same X-Idempotency-Key.

Validation

A duplicate order is not created, idempotency is maintained, and the operation remains traceable under the original key.

Expected Result

Duplicate processing prevented.

Common Error Types

HTTPConditionExpected integration behavior
409Duplicate X-Idempotency-KeyTreat as already submitted. Reconcile against the existing order rather than resubmitting.
400X-Idempotency-Key omitted entirelySubmission rejected. Add the header before retrying.

POST
Step 7 — Async Operation Validation
${baseUrl}/v1/conversion/async-operations/query
›

Goal

Verify that asynchronous operations can be monitored using the idempotency key retained at submission.

Procedure

typescript
const operation = await queryOperation(accessToken, idempotencyKey);

Validation

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.

Expected Result

HTTP 200; async operation successfully tracked.

Common Error Types

HTTPConditionExpected integration behavior
401Expired or invalid access credentialRe-authenticate, then retry once.
500, 503Service failureRetry with exponential backoff. The query is read-only and safe to repeat.

GET
Step 8 — Async-to-Order Correlation
resourceId resolves the order identifier
›

Goal

Verify that an async operation can be correlated to the order it produced.

Procedure

typescript
const operation = await queryOperation(accessToken, idempotencyKey);
const order = await getOrder(accessToken, operation.resourceId);

Validation

resourceId is populated, resourceUrl is populated, the referenced order exists, and the order is retrievable.

Expected Result

HTTP 200; async operation successfully correlated to an order.

Common Error Types

HTTPConditionExpected integration behavior
404resourceId references an order that cannot be retrievedSurface not found. Do not create a replacement order.
500, 503Service failureRetry with exponential backoff, maximum three attempts.

GET
Step 9 — Retrieve Final Order
${baseUrl}/v1/conversion/orders/{orderId}
›

Goal

Verify that final order detail can be accessed once the order identifier is known.

Procedure

typescript
const orderDetail = await getOrder(accessToken, operation.resourceId);

Validation

The response carries order identifier, status, participant information, transaction information, and audit timestamps.

Expected Result

HTTP 200; order detail successfully retrieved.

Common Error Types

HTTPConditionExpected integration behavior
401Expired or invalid access credentialRe-authenticate, then retry once.
404Order identifier not foundSurface not found. Do not create a replacement order.
500, 503Service failureRetry with exponential backoff, maximum three attempts.

GET
Step 10 — Lifecycle Validation
order status transitions
›

Goal

Verify that lifecycle transitions can be monitored through to a terminal state.

Validation

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.

Expected Result

HTTP 200; current order status returned and reportable.

Common Error Types

HTTPConditionExpected integration behavior
401Expired or invalid access credentialRe-authenticate, then retry once.
404Order identifier not foundSurface not found. Do not create a replacement order.
500, 503Service failureRetry with exponential backoff, maximum three attempts.

GET
Step 11 — Audit Validation
end-to-end transaction trace
›

Goal

Verify that the complete transaction history can be reconstructed from the artifacts produced across the workflow.

Validation

The order identifier is traceable, the idempotency key is traceable, the async operation is traceable, audit timestamps are available, and transaction identifiers are available.

Expected Result

End-to-end audit trace established.

Common Error Types

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.


E2E
Step 12 — End-to-End Workflow Execution
complete conversion order lifecycle
›

Goal

Execute the complete workflow from authentication through audit validation in a single uninterrupted run.

Validation

text
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               PASS

Each constituent call returns its expected success code.

Expected Result

Complete workflow executed and every stage verified.

Negative Test Cases

IDScenarioHTTPExpected result
NT-1Invalid service account credentials400Authentication rejected.
NT-2Invalid security422Order rejected.
NT-3Ineligible wallet422Order rejected.
NT-4Missing idempotency key400Request rejected.
NT-5Expired access credential401Authorization failure; re-authentication required.
NT-6Async processing failure—Async operation returns Failed status with errorCode and errorMessage present. Not an HTTP error condition.
NT-7Invalid order retrieval404Order not found; error handled without creating a replacement order.
NT-8Service unavailable503Retry attempted, failure reported, workflow stops safely.

Production Certification Criteria

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.

Category 4
Corporate Actions

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.

Authentication pattern: These workflows use the Service Account Credentials grant. The token request is sent to /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.

Workflow Summary

A condensed view of the API call sequence, dependencies, and branch rules.

Authenticate

POST /connect/token
Obtain service-account token.

Load events

POST /v2/corporate-actions
Retrieve paginated events with a JSON body; offset and count are required, filters are optional.

Load filter data

GET /v2/corporate-actions/event-types
GET /v1/conversion/securities
Load in parallel.

Inspect event

GET /v2/corporate-actions/{id}
Retrieve full event detail.

Apply context

Interpret status, category, DTC mandatory classification, support flag, and relevant core dates.

Detail rule: Full corporate action detail is returned from GET /v2/corporate-actions/{id}, including security data, event classification, core dates, DTC mandatory classification, support status, and payout-related metadata.
Service AccountParallel LoadingEvent FiltersEvent Detail
POST
List Corporate Action Events and Reference Data
POST /v2/corporate-actions · GET /v2/corporate-actions/event-types · GET /v1/conversion/securities
›

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.

Endpoint migration: The corporate action events list has moved from 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.

Request Parameters

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.

ParameterLocationTypeRequiredDescription
offsetbodyinteger (int32)YesZero-based index of the first record to return. Minimum 0.
countbodyinteger (int32)YesMaximum number of records to return per page. Minimum 1.
idsbodystring[]OptionalFilter by internal event identifiers (GUID format). Up to 50 values.
eventIdsbodystring[]OptionalFilter by external (DTC) event identifiers. Up to 50 values.
eventTypesbodyEventTypeFilterItem[]OptionalFilter by event types and subtypes. Each item is an object with a required type (EventTypeEnumeration) and an optional subType (SubEventTypeEnumeration). Up to 50 values.
securityIdsbodystring[]OptionalFilter by event security identifier. Up to 50 values.
securityCusipsbodystring[]OptionalFilter by security CUSIP. Up to 50 values.
statusbodyEventStatusEnumeration[]OptionalFilter by event status. Up to 5 values.
searchForbodystringOptionalFree-text search key filter. Maximum length 50 characters.
orderBybodyEventFields enumOptionalField the results are sorted on.
sortOrderbodySortOrder enumOptionalSort direction: Ascending or Descending.

Enumerations

Enumeration values must be provided exactly as they are defined; they are case-sensitive.

POST /v2/corporate-actions

DirectionParameter / FieldEnum NameReference
Input (body)eventTypes[].typeEventTypeEnumerationEvent Type ▾
Input (body)eventTypes[].subTypeSubEventTypeEnumerationSub-Event Type ▾
Input (body)statusEventStatusEnumerationEvent Status ▾
Input (body)orderByEventFieldsEvent Fields ▾
Input (body)sortOrderSortOrderSort Order ▾
Output (response)subTypeSubEventTypeEnumerationSub-Event Type ▾
Output (response)statusEventStatusEnumerationEvent 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

DirectionParameter / FieldEnum NameReference
Output (response)eventTypeEventTypeEnumerationEvent Type ▾
Output (response)subEventTypeSubEventTypeEnumerationSub-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

DirectionParameter / FieldEnum NameValues
Input (query)orderByFinancialSecurityFieldsCUSIP, Description, Issuer
Input (query)sortOrderSortOrderAscending, Descending
Output (response)statusFinancialSecurityStatusOnboarding, Active, Pause, Failed

Sample Request

typescript
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();

Response Template

POST /v2/corporate-actions

json
[
  {
    "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.

json
[
  {
    "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.

json
[
  {
    "id": "security-id",
    "cusip": "46090E103",
    "issuerName": "Example Issuer",
    "security": "Invesco QQQ Trust",
    "securitySymbol": "QQQ",
    "status": "Active"
  }
]

TypeScript Interface

typescript
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;
}

Status Values

Approved, ConditionallyApproved, Incomplete, Cancelled, and Deleted.

Error Handling

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.

Common Error Types

HTTPConditionExpected integration behavior
400Malformed request or invalid filter parameterCorrect the request. Do not retry as-is.
401JWT access credential missing, expired, or invalidRequest a new JWT access credential, then retry once.
403Service account lacks the required permission, or the account is lockedSurface access denied. Do not retry.
404Resource not foundSurface not found. Do not retry.
500, 503Service failureRetry with exponential backoff, maximum three attempts. Keep the workflow stable and disable only the affected filter.

Retry Guidance

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.

Permissions & Scopes

Auth PatternService Account Credentials grant
Credential DeliveryAuthorization: Bearer {access_token}

GET
Get Corporate Action Event Detail
/v2/corporate-actions/{id}
›

Retrieves full detail for a specific corporate action event.

Request Parameters

ParameterLocationTypeRequiredDescription
idpathstringYesUnique key of a single corporate action event, taken from the results of the event list call.

Enumerations

Enumeration values must be provided exactly as they are defined; they are case-sensitive.

GET /v2/corporate-actions/{id}

DirectionParameter / FieldEnum NameReference
Output (response)typeEventTypeEnumerationEvent Type ▾
Output (response)subTypeSubEventTypeEnumerationSub-Event Type ▾
Output (response)statusEventStatusEnumerationEvent Status ▾
Output (response)dtcMandatoryDtcMandatoryDTC Mandatory ▾
Output (response)categoryEventCategoryEvent Category ▾

Enumeration values are defined once in the Corporate Action Enumerations reference at the end of this section.

Sample Request

typescript
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.

Response Template

json
{
  "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
  }
}

TypeScript Interface

typescript
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;
}

Single Endpoint Detail

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.

Error Handling

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.

Common Error Types

HTTPConditionExpected integration behavior
400Invalid event identifier formatCorrect the request. Do not retry as-is.
401JWT access credential missing, expired, or invalidRequest a new JWT access credential, then retry once.
403Service account lacks the required permission, or the account is lockedSurface access denied. Do not retry.
404Invalid or deleted eventSurface event not found. Do not retry.
500, 503Service failureRetry with exponential backoff, maximum three attempts.

Retry Guidance

Read-only GET; safe to retry on 5xx or network timeout. Use exponential backoff with a maximum of three retries.

Permissions & Scopes

Auth PatternService Account Credentials grant
Credential DeliveryAuthorization: Bearer {access_token}
Reference

Corporate Action Enumerations

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.

Event Type Enumeration

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.

Show all event types
ValueEvent NameDescription
AutomaticDividendReinvestmentAutomatic Dividend ReinvestmentA 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).
CapitalGainsDistributionCapital Gains DistributionA distribution of cash that the issuer has determined will be declared as income financed from capital gains and not ordinary income.
CashDividendCash DividendA 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.
CDEarlyRedemptionCD Early RedemptionA 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.
ChangeChangeAn event where the issuer is announcing a change in company or security details.
ConsentConsentSolicitation 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.
ConversionConversionConversion of securities (generally convertible bonds or preferred shares) into another form of securities (usually common shares) at a pre-stated price or rate.
DefaultDefaultA 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.
DistributionDistributionA distribution by the issuer that is not classified as another specific event.
DividendWithOptionDividend with OptionA 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.
DutchAuctionDutch AuctionIdentifies 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.
ExchangeOfferExchange OfferAn offer to surrender securities in exchange for other securities or a combination of securities and cash. The exchange may also include a consent solicitation.
FinalPaydownFinal PaydownThe final distribution of principal due on a security, typically CMOs.
FullCallFull CallThe 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.
FullPrerefundingFull PrerefundingThe 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.
GeneralInformationGeneral InformationGeneral information provided by the issuer that should not result in material changes to the security.
InterestInterestThe 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.
LiquidationLiquidationA 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.
MandatoryExchangeMandatory ExchangeA corporate action requiring the surrender of certificates to be exchanged for a new security or cash.
MandatoryPutMandatory PutThe 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.
MaturityMaturityThe final repayment, usually in cash, by an issuer for the entire issue, or remaining outstanding securities of a specific security on a specified date.
MeetingMeetingA meeting of a company's share or bond holders to address resolutions put forth by the issuer.
MergerMergerThe exchange of one company's security for another company's security, cash, or a combination of cash and securities.
NameChangeName ChangeThe 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.
OddLotOfferOdd Lot OfferIdentifies 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.
PartialCallPartial CallSecurities 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.
PartialDefeasancePartial DefeasanceIssuer 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.
PartialMandatoryPutPartial Mandatory PutThe 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.
PartialPrerefundingPartial PrerefundingSimilar 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.
PayInKindPay in KindIncome on interest-bearing securities where the payment is made in additional securities rather than cash.
PlanOfReorganizationPlan of ReorganizationReorganisation 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.
PrincipalPrincipalA cash payment that represents a reduction of the principal in the security.
PutPutA 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.
RedemptionOfRightsRedemption of RightsAn event where the issuer pays proceeds to shareholders prior to acquiring or merging with an existing company.
RedemptionOfWarrantsRedemption of WarrantsAn 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).
ReorganizationReorganizationA reorganization event announced by the issuer that cannot be classified as another event.
ReturnOfCapitalReturn of CapitalA 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.
ReverseStockSplitReverse Stock SplitThe 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.
RightsDistributionRights DistributionSecurities 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.
RightsSubscriptionRights SubscriptionA privilege granted to holders of rights to purchase new or additional securities. Rights are often tradable in a secondary market.
SaleOfRightsSale Of RightsA 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).
SecuritySeparationSecurity SeparationNo corresponding entry in the SR2026 data dictionary; description not published.
SpecialDividendSpecial DividendA 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.
SpinOffSpin-OffA 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.
StockDividendStock DividendA 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.
StockSplitStock SplitThe 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.
TaxEventTax EventTax 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").
TaxRefundTax RefundAn event that enables DTC to make a withholding tax refund, usually on non-U.S. dividends.
TenderOfferTender OfferAn 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.
TerminationTerminationA 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.
WarrantsExerciseWarrants ExerciseA 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.
WorthlessWorthlessDTCC 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.
BankruptcyBankruptcyBankruptcy (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.)

Sub-Event Type Enumeration

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.

Show sub-event types
ValueSub-Event NameDescription
None(Non-specific)Non-specific event with no sub-event classification.
DRIPDTCOnlyDRIP (DTC only)Identifies an event where the Issue is eligible for a Dividend Reinvestment program.
OptOutDTCOnlyOpt 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).
DomicileDomicileIdentifies 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.
DomicileNewCUSIPDomicile New CUSIPA domicile change accompanied by the assignment of a new CUSIP.
DomicilePresentationRequiredDomicile Presentation RequiredA domicile change for which presentation of securities is required.
DomicileNewCUSIPPresentationRequiredDomicile New CUSIP Presentation RequiredA domicile change with a new CUSIP for which presentation of securities is required.
WithPayoutWith PayoutIdentifies an event where a fee is paid to the registered holder. DTC will not be processing as information only event.
WithoutPayoutWithout PayoutIdentifies an event where no fee is paid. DTC will not be processing as information only event.
FinalPaymentFinal PaymentIdentifies an event that include notification of a final payment in lieu of the original commitment.
InterimPaymentInterim PaymentIdentifies an event that include notification of an interim payment in lieu of the original commitment.
TaxCreditTax CreditTax 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.
ConsentConsentIdentifies an event that includes a consent fee.
A144144aIdentifies an event where the security is a 144a private placement security.
CashAndSecuritiesCash and SecuritiesIdentifies an event with a combination of Cash and Securities as payout.
RegSReg SIdentifies an event where the security is a Regulation S type.
UnwindUnwindIdentifies 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.
ConversionOngoingIdentifies 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.
ImportantNoticeImportant NoticeIdentifies 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.
DayExemptionQualifiedNoticeDay Exemption Qualified NoticeIdentifies 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).
BasedOnRecordDateHoldingsBased on Record Date HoldingsIdentifies an event processed as dividend event.
PresentationRequiredPresentation RequiredIdentifies an event processed as Reorg event and may include options.
RetainRetainIdentifies an event that include an option to retain the event securities rather than exchange them.
SecuritiesSecuritiesIdentifies an event where the payment will be made in the form of securities.
AnnualAnnualIdentifies an annual meeting event.
ExtraordinaryExtraordinaryIdentifies an extraordinary meeting event.
GeneralGeneral MeetingIdentifies 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.
SpecialSpecialIdentifies a special meeting event.
CashCashIdentifies an event with a payout of cash only.
CUSIPChangePresentationRequiredCUSIP Change Presentation RequiredIdentifies a CUSIP change for which presentation of securities is required.
NewCUSIPNew CUSIPIdentifies an event accompanied by the assignment of a new CUSIP.
VoteVoteIdentifies an event where a vote is sought.
MortgageBackedMortgage-BackedIndicates 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.
SurvivorOptionsSurvivor OptionsIndicates 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.
SPACSPACIdentifies a Special Purpose Acquisition Company to raise money through an initial public offering (IPO) to acquire or merge with an existing company.
SaleOfAssetsSale of AssetsIdentifies an event where the distribution is from the proceeds of the sale of assets.
PhysicalRightsNotIssuedPhysical Rights not IssuedIdentifies 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.
ADRADRIdentifies 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.
PoisonPillPoison PillIdentifies sale of rights event where issuers redeem poison pill rights.
CDeemedDividend305C - Deemed DividendDeemed distribution under Section 305(c) of the Internal Revenue Code.
DividendEquivalentPayment871MDividend Equivalent Payment under Section 871(m) of the Internal Revenue Code.
ExcessOfCumulativeNetIncomeECNIIdentifies 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).
SClassifications1042RCLA (1042S Classifications)Identifies distributions that have multiple components for tax withholding and 1042-S reporting purposes.
BidTenderSealedTenderBid Tender/Sealed TenderIdentifies 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.
CashInLieuCash in LieuIdentifies 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.
ConvertAndTenderConvert and TenderIdentifies a tender offer event in which the holder must convert securities in order to take part in the event.
MiniTenderMini TenderIdentifies 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.
OfferToPurchaseOffer to PurchaseIdentifies a tender offer event made by another company or the issuing company (buy back) to purchase a portion or all of the outstanding shares.
SelfTenderSelf TenderIdentifies a tender offer event made by the issuing company (buy back) to purchase a portion or all of the outstanding shares.
GDRGDRIdentifies when the event security is a GDR.
MeetingTypeMeeting TypeIdentifies the type classification for a meeting event.

Event Status Enumeration

ValueMeaning
ApprovedEvent is approved and final.
ConditionallyApprovedApproved subject to conditions.
IncompleteEvent data is not yet complete.
CancelledEvent was cancelled.
DeletedEvent was deleted.

DTC Mandatory

ValueMeaning
MandatoryParticipation is automatic; no election required.
MandatoryWithOptionsMandatory, but participants may choose from options.
VoluntaryParticipation requires explicit election by the holder.

Event Category

Value
InterestOnTreasury
MaturityOnTreasury
MandatoryCashDistribution
MandatorySecurityDistribution
MandatoryWithChoiceDistribution
MandatoryReorganization
VoluntaryReorganization
Meetings

Event Fields (orderBy)

Value
Id
EventId
EventType
Status
SecurityName
SecurityCusip
PositionCaptureDate
DeclaredPayableDate
EarliestDTCAnticipatedPaymentDate
EarliestDTCInstructionExpirationDate
UpdatedAt
DigitalAllocationDate

Sort Order

Value
Ascending
Descending

Core Dates by Event Category

CategoryRelevant Core Dates
InterestOnTreasurydeclaredPayableDate, digitalAllocationDateTime, bookEntryAllocationDateTime
MaturityOnTreasurydeclaredPayableDate, digitalAllocationDateTime, bookEntryAllocationDateTime
MandatoryCashDistributionexDate, recordDate, dtcPositionCaptureDate, declaredPayableDate, anticipateDate, digitalAllocationDateTime, bookEntryAllocationDateTime
MandatorySecurityDistributionexDate, recordDate, dtcPositionCaptureDate, digitalAllocationDateTime, bookEntryAllocationDateTime
MandatoryWithChoiceDistributionexDate, recordDate, dtcPositionCaptureDate, dtcInstructionExpirationDateTime, digitalAllocationDateTime, bookEntryAllocationDateTime
MandatoryReorganizationeffectiveDateCompany, dtcPositionCaptureDate, digitalAllocationDateTime, bookEntryAllocationDateTime, reconversionDate
VoluntaryReorganizationdtcInstructionExpirationDateTime, dtcPositionCaptureDate, digitalAllocationDateTime, bookEntryAllocationDateTime
MeetingsmeetingDate

DTC Mandatory Classification

ValueMeaning
MandatoryParticipation is automatic; no election required.
MandatoryWithOptionsMandatory but participants may choose from options.
VoluntaryParticipation requires explicit election by the holder.
Retry and dependencies: The event list is a read-only 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.
Certification

Corporate Actions Workflow Certification Test

CERT
Corporate Actions Workflow Certification Test
Certification · v1 · Load Events → Load Types + Securities → Inspect → Apply Context
›

This certification verifies both API connectivity and the customer's ability to correctly interpret corporate action event data.

Certification Workflow

Authenticate, load events, load event types and securities in parallel, inspect the event, then apply context.

Authenticate

Obtain a JWT access credential using SA-CorporateActionsBot.

Load Events

POST /v2/corporate-actions

Load Types + Securities

event-types plus securities in parallel.

Inspect Event

GET /v2/corporate-actions/{id}

Apply Context

Status, category, DTC classification, and core dates.

Single endpoint detail: All event detail information is retrieved from GET /v2/corporate-actions/{id}. No additional entitlement endpoint is required.
AuthenticationParallel LoadingEvent FiltersEvent Detail

Key Business Rules

RuleRequirement
Parallel LoadingRetrieve events, event types, and securities concurrently.
Supported StatusesApproved, ConditionallyApproved, Incomplete, Cancelled, Deleted.
Detail RetrievalAll detail information is retrieved from GET /v2/corporate-actions/{id}.
Context InterpretationCustomers must correctly apply status, category, DTC mandatory classification, support indicator, and core dates.

Prerequisites

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}.

Test Data

typescript
const tenantName = "<tenant-name>"; // recommended, e.g. "DTCC-DA"
const baseUrl = "<base-url>";
const username = "SA-CorporateActionsBot";
const password = process.env.SERVICE_ACCOUNT_PASSWORD!;

Shared Helper Functions

typescript
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();
}

POST
Step 1 — Authentication
${baseUrl}/connect/token
›

Goal

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.

Expected Result

HTTP 200; JWT access credential returned; credential accepted by downstream APIs.

Common Error Types

HTTPConditionExpected integration behavior
400Invalid credentialsSurface authentication rejected. Do not retry with the same credentials.
500, 503Identity Server failureRetry with exponential backoff, maximum three attempts.

POST
Step 2 — Load Corporate Action Events
${baseUrl}/v2/corporate-actions
›

Goal

Verify the integration can retrieve a paginated corporate action event inventory with statuses and event identifiers populated.

Procedure

typescript
const data = await loadCorporateActionsData(accessToken);

Validation

Events returned; pagination supported; statuses populated; event identifiers returned.

Expected Result

HTTP 200; corporate action inventory loaded successfully.

Common Error Types

HTTPConditionExpected integration behavior
400Invalid filter parametersCorrect the request. Do not retry as-is.
401Expired or invalid JWT access credentialRe-authenticate, then retry once.
403Missing permissionSurface access denied. Do not retry.
500, 503Service failureRetry with exponential backoff, maximum three attempts.

GET
Step 3 — Load Event Type Taxonomy
${baseUrl}/v2/corporate-actions/event-types
›

Goal

Verify the integration can retrieve the event type and sub-event type taxonomy used for hierarchical event filtering.

Validation

Event types returned; sub-event types returned; hierarchy available.

Expected Result

HTTP 200; event taxonomy successfully loaded.

Common Error Types

HTTPConditionExpected integration behavior
401Expired or invalid JWT access credentialRe-authenticate, then retry once.
500, 503Event-type service unavailableFilter data unavailable; display a meaningful error and keep the workflow stable.

GET
Step 4 — Load Securities Filter Data
${baseUrl}/v1/conversion/securities
›

Goal

Verify the integration can retrieve securities reference data, including CUSIPs and support flags, for filtering corporate action events.

Validation

Security identifiers returned; CUSIPs returned; support flags returned.

Expected Result

HTTP 200; security filtering possible.

Common Error Types

HTTPConditionExpected integration behavior
401Expired or invalid JWT access credentialRe-authenticate, then retry once.
500, 503Securities service unavailableSecurity filter unavailable; display a meaningful error and keep the workflow stable.

GET
Step 5 — Event Filtering
filter by status, type, sub-type, security, and search text
›

Goal

Verify the integration can narrow the event inventory to a relevant subset using status, event type, sub-event type, security, and search text.

Procedure

typescript
const approvedEvents = events.filter(
  event => event.status === "Approved"
);

Validation

Successful filtering by status, event type, sub-event type, security, and search text.

Expected Result

Relevant events identified.

Common Error Types

HTTPConditionExpected integration behavior
400Invalid filter parametersValidation error. Correct the filter values before retrying.

GET
Step 6 — Retrieve Event Detail
${baseUrl}/v2/corporate-actions/{id}
›

Goal

Verify the integration can retrieve full event detail from the single detail endpoint, including security, category, status, classification, and core dates.

Procedure

typescript
const detail = await getEventDetail(accessToken, eventId);

Validation

Security returned; category returned; status returned; DTC classification returned; core dates returned.

Expected Result

HTTP 200; event detail successfully retrieved.

Common Error Types

HTTPConditionExpected integration behavior
400Invalid event identifier formatCorrect the request. Do not retry as-is.
404Invalid event ID; event not foundSurface event not found. Do not retry.
500, 503Event detail service failureInvoke retry logic with exponential backoff and handle the failure gracefully.

GET
Step 7 — Apply Event Context
interpret category, status, support flag, and DTC classification
›

Goal

Verify the integration derives correct business context from the returned category, status, support indicator, and DTC classification.

Procedure

typescript
if (detail.dtcMandatory === "Voluntary") {
  console.log("Election Required");
}

Validation

Interpret category, status, support flag, and DTC classification.

Expected Result

Business context successfully derived.

Common Error Types

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.


GET
Step 8 — Category-Specific Date Interpretation
identify relevant dates by category
›

Goal

Verify the integration identifies the correct set of lifecycle dates for each corporate action category it processes.

Required Dates by Category

CategoryRequired Dates
InterestOnTreasurydeclaredPayableDate, digitalAllocationDateTime, bookEntryAllocationDateTime
MaturityOnTreasurydeclaredPayableDate, digitalAllocationDateTime, bookEntryAllocationDateTime
MandatoryCashDistributionexDate, recordDate, dtcPositionCaptureDate, declaredPayableDate, anticipateDate, digitalAllocationDateTime, bookEntryAllocationDateTime
MeetingsmeetingDate

Validation

Correctly identify the relevant dates for at least one event available in each category.

Expected Result

The correct set of lifecycle dates is identified for each category present in the test dataset.

Common Error Types

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.


GET
Step 9 — DTC Classification Interpretation
classify events by returned values
›

Goal

Verify the integration correctly classifies each event as Mandatory, MandatoryWithOptions, or Voluntary and acts on whether an election is required.

Classification Values

ValueMeaning
MandatoryParticipation automatic.
MandatoryWithOptionsOptions available to holder.
VoluntaryElection required.

Validation

The customer correctly classifies events using the returned values.

Expected Result

Each event is classified as Mandatory, MandatoryWithOptions, or Voluntary, and election requirements are applied accordingly.

Common Error Types

This step performs no API calls. An unrecognized dtcMandatory value must be surfaced as an unhandled classification rather than defaulted to Mandatory.


E2E
Step 10 — End-to-End Workflow Execution
executeWorkflow()
›

Goal

Execute the complete corporate actions workflow in a single run to confirm every stage succeeds in sequence.

Procedure

typescript
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 };
}

Expected Result

log
Authentication    PASS
Load Events       PASS
Load Event Types  PASS
Load Securities   PASS
Filter Events     PASS
Retrieve Detail   PASS
Apply Context     PASS
Workflow Complete PASS

Each constituent call returns its expected success code.

Negative Test Cases

IDScenarioHTTPExpected result
NT-1Invalid Credentials400Authentication rejected.
NT-2Expired Credential401Re-authentication required.
NT-3Invalid Event ID404Event not found.
NT-4Missing Permission403Access denied.
NT-5Invalid Filter Parameters400Validation error.
NT-6Event-Type Service Unavailable500, 503Filter data unavailable; meaningful error displayed; workflow remains stable.
NT-7Securities Service Unavailable500, 503Security filter unavailable; meaningful error displayed; workflow remains stable.
NT-8Event Detail Service Failure500, 503Retry logic invoked; graceful failure handling.

Production Certification Criteria

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.

Release History
Site Changelog

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.

RELEASE
Version 2.0
›

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.

Breaking Base URLs

  • The production Services base URL is 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.

Breaking Account Management

  • Account resolution has moved from 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.
  • The roots response omits ownershipStake, isOwned, and isOperated, which remain hierarchy-only.
  • Updated the Account Management workflow summary, endpoint catalog, Primary API Journeys table, and the Account Management certification test (now Resolve via Roots).

Breaking Wallet Management

  • The account reference endpoint (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.

New Conversion Orders

  • Added a Delivery Order Error & Status Codes section to the Error Code Reference, covering the error codes returned on a delivery order NACK and the status codes returned when an order is submitted to ATP. See that section for the full code lists.
  • Securities carry a fourth transfer restriction, transferLock, alongside doChill, complianceLock, and globalLock. Confirm all four report "enabled": false before treating an Active security as usable.
  • The async operations query (POST /v1/conversion/async-operations/query) requires idempotencyKeys, offset, count, orderBy (CreatedAt), and sortOrder (Ascending or Descending).

New Account Management

  • The List Accounts endpoint (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.)

Deprecation Conversion Orders

  • On the securities list (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.

Clarification Authentication

  • The authentication callouts now note that the 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.
  • The token request parameters are 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.

Clarification Account Management

  • Service naming in the Account Management section was updated for consistency with current platform terminology. The conversion service is now referred to as Conversion Service, and the account management service is now referred to as Account Management Service. This affects the Account Management flow-key chips and the service-intro prose on the Get Account Activities and Get Account Balances cards. No endpoint paths, parameters, or API behavior changed.
  • The Ownership Stake and Hierarchy Depth & Performance guidance notes now appear inside the Get Account Hierarchy card (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.
  • Account activities (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.
  • The 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.
  • The 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.
  • A date-only 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.

Clarification Wallet Management

  • The wallet list (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.

Clarification Conversion Orders

  • The conversion orders list (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.
  • Wallet records include trackingWalletId, account, conversionEligible, and failureReason; wallet type values are Internal and Client. The securities list paginates with offset and count.
  • The 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.
  • Wallet state values are Idle, Registering, Deleting, FailedCompliance, and Failed. The securities free-text filter is searchFor and the sort field is orderBy.
  • When filtering GET /v1/conversion/orders by status or financialSecurityIds, send each value as a separate repeated query parameter.
  • Order detail identifies the participant with id and name, and the security with id, cusip, symbol, and status. A conversion order is submitted with financialSecurityId to identify the security.
  • Order wallet objects (fromWallet, toWallet) include a network attribute on both the orders list and order detail responses.

Clarification Corporate Actions

  • Corrected the Event Detail Error Response sample on the Get Corporate Action Event Detail card (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.
  • The 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.
  • DTC mandatory classification values are Mandatory, MandatoryWithOptions, and Voluntary. Enumeration values are case-sensitive and must be sent exactly as shown.
  • The 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.

Clarification Overview / Reference

  • Removed /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.
  • The Conversion Order Request sample in the Sample Payloads panel now sends quantity as an unquoted integer ("quantity": 500), matching the CreateOrderRequest schema (integer, int32) and the sample on the Submit and Track Conversion Orders card.
RELEASE
Version 1.95
›

Breaking Authentication

  • All API families authenticate using the Service Account Credentials grant. See the breaking-change callout at the top of this tab for the full token request and migration guidance. A runnable sample token request is available from the Authentication panel.

New Conversion Orders

  • The securities list (GET /v1/conversion/securities) supports an optional status filter accepting a single value: Onboarding, Active, Pause, or Failed.
RELEASE
Version 1.94a
›

Breaking Corporate Actions

  • The event list moved to 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.

New Conversion Orders

  • The async operations query (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.
  • Order detail (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.
  • Order submission documents a machine-readable errorCode for HTTP 400, 404, 409, and 500 responses, with the cause and recommended correction for each.

Clarification Account Management

  • Each account activity 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.
RELEASE
Version 1.94
›

Breaking Corporate Actions

  • The corporate action events list migrated from the deprecated 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.

Clarification Overview / Reference

  • The Primary API Journeys table, API Families panel, and Endpoint Catalog reference 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.
RELEASE
Version 1.93
›

Clarification Conversion Orders

  • The async operations query (POST /v1/conversion/async-operations/query) processes all idempotencyKeys supplied in a single request. Submit no more than 100 keys per request.
RELEASE
Version 1.92
›

Clarification Conversion Orders

  • Order detail (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.
RELEASE
Version 1.91
›

Clarification Account Management

  • Each account activity 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.

Clarification Conversion Orders

  • The ConversionOperationsEngine__WalletNotFound error code moved from the HTTP 404 table to the HTTP 400 table in the Error Code Reference.
RELEASE
Version 1.9
›

Breaking Wallet Management & Conversion Orders

  • The /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.

New Conversion Orders

  • Order submission includes an Error Code Reference enumerating the machine-readable errorCode values, causes, and corrections for HTTP 400, 404, 409, and 500; the 500 and 503 conditions are documented separately.
RELEASE
Version 1.8
›

New Conversion Orders

  • The Common Error Types section on the Submit and Track Conversion Orders card splits the combined 500/503 row into separate 500 and 503 rows, with cross-references from the 400, 404, 409, and 500 rows to the detail tables. An Error Code Reference subsection lists the machine-readable errorCode values, causes, and corrections for HTTP 400, 404, 409, and 500.
RELEASE
Version 1.7
›

New Conversion Orders

  • Security status and transfer restrictions are separate signals. An 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.
RELEASE
Version 1.6
›

Clarification Corporate Actions

  • The corporate action notification endpoints are based on DTCC's ISO CANO messages. Refer to DTCC's ISO 20022 Messaging Specifications for the data dictionary.
RELEASE
Version 1.5
›

New Conversion Orders — asynchronous submission

  • 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.
  • Added 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.

New Pagination

  • Offset-based pagination uses the 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.

Clarification Conversion Orders

  • Wallet eligibility requires both an Idle state and conversionEligible = true; a wallet that satisfies only one condition is not eligible.
  • Query the orders list before submitting to detect whether a prior submission with the same intent already exists.
  • The idempotency header is X-Idempotency-Key, and enumeration values are case-sensitive and must be sent exactly as defined.

Clarification Account & Wallet Management

  • Security status includes Failed; wallet states include FailedCompliance and Failed.
RELEASE
Version 1.4
›

New Conversion Orders

  • The certification section was rebuilt as the Conversion Order Certification Tests, with twelve steps covering authentication, reference-data retrieval, security and wallet validation, order submission, idempotency, async operation tracking, async-to-order correlation, final order retrieval, lifecycle validation, audit validation, and end-to-end execution. Maker-Checker Validation (Test 11) is excluded, and maker/checker references are removed from the validation model, checklist, and workflow diagram. Declined is removed from the lifecycle, leaving Processing, Completed, and Failed. Added queryOperation and getOrder helpers, with correlation by idempotency key.

Clarification Conversion Orders

  • Pagination parameters are 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.

New Pagination

  • A Pagination Model panel documents offset-based pagination: the 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.
RELEASE
Version 1.3
›

New Conversion Orders

  • The asynchronous submission contract is documented: 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.

Clarification Conversion Orders

  • Wallet eligibility requires conversionEligible = true in addition to an Idle processing state, applied across the eligibility rules, workflow summary, business rules, and certification criteria.

Clarification Account & Wallet Management

  • Failed is added to the FinancialSecurityStatus values on the account balances card, and FailedCompliance and Failed are added to the wallet ProcessingStates values.
RELEASE
Version 1.2
›

Clarification Enumerations

  • Enumerations tables across Account Management, Wallet Management, Conversion Orders, and Corporate Actions were rebuilt to the four-column shape used in the enumeration reference document, with Direction as the leading column and a method and path label above each table. Combined tables were split into separate labeled tables, one per endpoint.
RELEASE
Version 1.1
›

New Conversion Orders

  • Conversions move securities between electronic book-entry and digital tokenized forms. The process is identical in both directions; only the source and destination assignments differ. Retrieve and verify the wallet and securities before submitting an order. The lifecycle runs straight through from Processing to Completed, with Failed as the terminal failure state.

Clarification Account Management

  • Accounts organize wallets. Two accounts are configured by default: Internal (a participant's own wallets) and Clients (wallets registered on behalf of a participant's clients).
Certifications: Certification walkthroughs are revised alongside the API changes above. When working through a certification, use the current steps in each category's Certification section rather than a cached copy.