# Retrieve retirement request details

View retirement details using the retirement batch identifier

Endpoint: POST /api/ledger/{ledgerIdentifier}/retirementBatch/byIdentifier
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 retrieve retirement batches on behalf of another account holder, identifying that account holder by their system-assigned srcAcctId.

  - `retirementBatchIdentifiers` (array)
    Identifiers associated with the retirement batch initiated by the system
    Example: "3574500f-6df3-400e-abc9-e6aeb64f03c7"

## Response 200 fields (application/json):

  - `retirementBatches` (array)
    Collection of retrieved retirement batches

  - `retirementBatches.identifier` (string)
    The Retirement Batch's system-assigned identifier.

  - `retirementBatches.originalQuantity` (number)
    The total quantity of holdings included in the retirement batch.

  - `retirementBatches.liabilityIssuanceIdentifier` (string)
    System-assigned identifier of the liability issuance associated with the retirement

  - `retirementBatches.liabilityHoldingIdentifier` (string)
    System-assigned Identifier of the liability holding against which the retirement was performed.
    Example: "476022"

  - `retirementBatches.subaccount` (object)
    This class contains caller-visible set of sub-accounts for either the calling account or the account identified by onBehalfOfSrcAcctId

  - `retirementBatches.subaccount.identifier` (string)
    The sub-account's system-assigned identifier.
    Example: "6192c733-bbd2-11ef-acad-b63fd176813a"

  - `retirementBatches.subaccount.number` (string)
    Sub-account number

  - `retirementBatches.subaccount.account` (object)
    Account record

  - `retirementBatches.subaccount.account.srcAcctId` (string)
    The Account's unique system-assigned identifier used for programmatic (API) interactions.
    Example: "4edse581-b97a-11ef-ea69-b61606fd520c"

  - `retirementBatches.subaccount.account.identifier` (string)
    The Account's ID as displayed in the registry.
    Example: "15184192"

  - `retirementBatches.subaccount.account.name` (string)
    The Account Operating Name on the registry.
    Example: "APXOPCAR Project Manager"

  - `retirementBatches.subaccount.name` (string, required)
    Sub-account name
    Example: "Allocated"

  - `retirementBatches.subaccount.description` (string)
    Sub-account description
    Example: "Holdings to retired & retired"

  - `retirementBatches.subaccount.status` (object)
    A reference datum data object
    Example: "GOC"

  - `retirementBatches.subaccount.status.code` (string, required)
    The reference data's value.

  - `retirementBatches.subaccount.status.name` (string)
    The reference data's name

  - `retirementBatches.subaccount.viableStatusTransitions` (array)
    Viable Sub-account transitions
    Enum: "edit", "activate", "deactivate"

  - `retirementBatches.subaccount.managingExternalPlatform` (object)
    If this is a managed sub-account, information on the external platform managing this sub-account.

  - `retirementBatches.subaccount.managingExternalPlatform.externalPlatformIdentifier` (string)
    The managing external platform's system-assigned identifier.
    Example: "a5f8c9fa-001b-4444-b966-17b1a7871bbf"

  - `retirementBatches.subaccount.managingExternalPlatform.code` (string)
    The External Platform's system code, if applicable.

  - `retirementBatches.subaccount.managingExternalPlatform.name` (string)
    The External Platform's name.
    Example: "Xpansiv Connect"

  - `retirementBatches.subaccount.managingExternalPlatform.metadataConfig` (string)
    Metadata configuration (JSON) for additional fields required by the External Platform.

  - `retirementBatches.subaccount.managingExternalPlatformAccountId` (string)
    If this is a managed sub-account, the relevant account ID in the external platform for the account associated with this sub-account.

  - `retirementBatches.subaccount.managingExternalPlatformSubaccountMetadata` (string)
    Optional JSON payload of managing external platform subaccount metadata.

  - `retirementBatches.subaccount.default` (boolean)
    If true, this is the default sub-account
    Example: true

  - `retirementBatches.shadowedLedgerRetirementBatchIdentifier` (string)
    If shadowing = true, the corresponding Retirement Batch identifier from the external ledger.

  - `retirementBatches.positions` (array)
    Collection of the retirement batch's associated holdings.

  - `retirementBatches.positions.identifier` (string)
    The holding's system-assigned identifier.

  - `retirementBatches.positions.resourceProgramAssignedIdentifier` (string)
    The associated resource's program assigned identifier.
    Example: "GHG1021"

  - `retirementBatches.positions.holdingStatus` (object)
    A reference datum data object
    Example: "GOC"

  - `retirementBatches.positions.programPeriodBeginInclusive` (string)
    Start of program period (vintage) associated to the holding record's issuance.
    Example: "2022-01-01T00:00:00-05:00"

  - `retirementBatches.positions.programPeriodEndExclusive` (string)
    End of program period (vintage) associated to the holding record's issuance.
    Example: "2023-01-01T00:00:00-05:00"

  - `retirementBatches.positions.timeOfProductionBeginInclusive` (string)
    Start of production period associated to the holding's issuance
    Example: "2022-01-01T00:00:00-05:00"

  - `retirementBatches.positions.timeOfProductionEndExclusive` (string)
    End of production period associated to the holding's issuance
    Example: "2023-01-01T00:00:00-05:00"

  - `retirementBatches.positions.serialNumber` (string)
    The holding record's serial number.
    Example: "APXOPCAR-GOC-GHG1021-US-2022--46-5701-6700"

  - `retirementBatches.positions.quantity` (number)
    The quantity of the holding record.
    Example: 1000

  - `retirementBatches.positions.programVersions` (array)
    Associated programs and their versions.

  - `retirementBatches.positions.programVersions.code` (string)
    Program code
    Example: "GHG_MEASUREMENT_PROGRAM"

  - `retirementBatches.positions.programVersions.version` (string)
    Version of Program.
    Example: "5.0.0"

  - `retirementBatches.positions.programVersions.shortName` (string)
    Program short name
    Example: "Carbon Measurement"

  - `retirementBatches.positions.programVersions.protocolVersions` (array)
    A list of Protocols associated with Program.

  - `retirementBatches.positions.programVersions.protocolVersions.code` (string)
    Protocol code
    Example: "AMS-I.D."

  - `retirementBatches.positions.programVersions.protocolVersions.version` (string)
    Version of Protocol
    Example: "1.0.0"

  - `retirementBatches.positions.programVersions.protocolVersions.shortName` (string)
    Protocol's short name
    Example: "AMS-I.D."

  - `retirementBatches.positions.protocolVersions` (array)
    Associated protocols and their versions.

  - `retirementBatches.positions.resourceInputTypeCodes` (array)
    A list of resource input types associated with the holding record's issuance.

  - `retirementBatches.positions.resourceOutputTypeCodes` (array)
    A list of resource output types associated with the holding record's issuance.
    Example: "CARBON_REDUCTION"

  - `retirementBatches.positions.subaccountIdentifier` (string)
    The  system-assigned identifier for the subaccount.
    Example: "5FF7ABAA-095D-11EF-B304-AA080FC10FFA"

  - `retirementBatches.positions.subaccountName` (string)
    Subaccount name, as inputted by subaccount owner.
    Example: "My Linked Holdings"

  - `retirementBatches.positions.subaccountNumber` (string)
    Subaccount Id displayed on the Optimal Outcomes platform's UI.
    Example: "10033"

  - `retirementBatches.positions.programCertificationGroupCode` (string)
    The issuing program certification group of the holding record.
    Example: "NONAFOLU_GHG_MEASUREMENT_PROGRAM"

  - `retirementBatches.positions.upn` (string)
    Xpansiv Connect Universal Project Number (UPN) for Resource associated to the holding's issuance, if assigned.
    Example: "0999F5B4"

  - `retirementBatches.positions.ein` (string)
    Xpansiv Connect Environmental Instrument Number (EIN), if assigned.
    Example: "1246AFA3E2"

  - `retirementBatches.positions.einDescription` (string)
    Xpansiv Connect Environmental Instrument Number (EIN) details, if assigned
    Example: "VCU-20120101-20121231-EDEM-3267-ZMB"

  - `retirementBatches.positions.shadowedLedgerName` (string)
    If shadowing = true, the external ledger's name.
    Example: "Verra"

  - `retirementBatches.positions.managingExternalPlatformName` (string)
    If the holding is held in an external subaccount, the name of the managing external platform associated with the external subaccount.
    Example: "Xpansiv Connect"

  - `retirementBatches.positions.certificateType` (object)
    A reference datum data object
    Example: "GOC"

  - `retirementBatches.createdAt` (string)

  - `retirementBatches.lastUpdatedAt` (string)

  - `retirementBatches.retirementParameters` (object)


## Response 404 fields