# Initiate a retirement request

Retire, or claim, instruments against an obligation

Endpoint: POST /api/ledger/{ledgerIdentifier}/retire
Version: 1.0.0
Security: JWT

## Path parameters:

  - `ledgerIdentifier` (string, required)
    Ledger identifier, can be found using /api/ledger endpoint
    Example: "4b7375e9-79b0-4b8b-a89e-a21607f0239f"

## Request fields (application/json):

  - `onBehalfOfSrcAcctId` (string)
    If permitted, allows the caller to retire on behalf of another account holder, identifying that account holder by their system-assigned srcAcctId.

  - `requests` (array)
    retirement request

  - `requests.liabilityHoldingIdentifier` (string)
    Identifier of the liability holding against which this retirement will be associated. Available liability holdings returned by GET /api/ledger/{ledgerIdentifier}/holding with asset = false.
    Example: "476022"

  - `requests.retirementReasonCode` (string)
    Retirement reason code to be associated with retirement
    Example: "COMPLIANCE_REQUIREMENTS"

  - `requests.holdingCriteria` (array)
    Criteria for holdings associated with the retirement batch.

  - `requests.holdingCriteria.holdingIdentifier` (string)
    Holding Identifier, as returned by the holdings API
    Example: "476099"

  - `requests.holdingCriteria.quantity` (number)
    Quantity of holding to be used in this operation
    Example: 3

  - `requests.correlationId` (string)
    Client system correlation Id – allows the caller to correlate between requests and responses

  - `requests.subaccountIdentifier` (string)
    Target subaccount identifier – required if performing a retirement against a ledger that has subaccounts enabled.

  - `requests.retirementParameters` (object)

  - `shadowedLedgerRetirementOptions` (object)

  - `shadowedLedgerRetirementOptions.suppressShadowedLedgerInteraction` (boolean)

  - `shadowedLedgerRetirementOptions.shadowedLedgerRetirementIdentifiersByHoldingIdentifier` (object)

## Response 200 fields (application/json):

  - `responses` (array)
    responses for the bulk retirement request

  - `responses.correlationId` (string)
    Matches the correlationId provided in the retirement request.

  - `responses.retirementIdentifier` (string)
    Identifier associated with the retirement batch initiated by the system
    Example: "b24ad896-d899-478d-9513-7061375b637c"


## Response 404 fields