openapi: 3.2.0
info:
  title: Transfer Position External Retirementbatch V1 API
  description: Use API credentials to view and manage instruments.
  version: 1.0.0
servers:
- url: https://optimalapi-ext.apx.com/transfer/v1
- url: https://optimalapi-uat-ext.apx.com/transfer/v1
tags:
- name: retirementbatch-v1
  description: View or submit a retirement request, or redemption claim, on instrument(s).
paths:
  /api/ledger/{ledgerIdentifier}/retirementBatch/byIdentifier:
    post:
      tags:
      - retirementbatch-v1
      summary: Retrieve retirement request details
      description: View retirement details using the retirement batch identifier
      operationId: getRetirementBatchesByIdentifier
      parameters:
      - name: ledgerIdentifier
        in: path
        description: Ledger identifier, can be found using /api/ledger endpoint
        required: true
        schema:
          type: string
          format: uuid
        example: 4b7375e9-79b0-4b8b-a89e-a21607f0239f
      requestBody:
        description: Populated RetirementBatchRetrieveByIdentifierRequest
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetirementBatchRetrieveByIdentifierRequest'
        required: true
      responses:
        '200':
          description: success
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/RetirementBatchRetrieveByIdentifierResponse'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AbstractRestError'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                oneOf:
                - $ref: '#/components/schemas/GeneralError'
                - $ref: '#/components/schemas/AbstractRestError'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AbstractRestError'
        '404':
          description: Not Found
          content: {}
        '406':
          description: Not Acceptable
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '422':
          description: Unprocessable Entity
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/GeneralError'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/GeneralError'
  /api/ledger/{ledgerIdentifier}/retire:
    post:
      tags:
      - retirementbatch-v1
      summary: Initiate a retirement request
      description: Retire, or claim, instruments against an obligation
      operationId: initiateRetirements
      parameters:
      - name: ledgerIdentifier
        in: path
        description: Ledger identifier, can be found using /api/ledger endpoint
        required: true
        schema:
          type: string
          format: uuid
        example: 4b7375e9-79b0-4b8b-a89e-a21607f0239f
      requestBody:
        description: Populated BulkRetirementRequest
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkRetirementRequest'
        required: true
      responses:
        '200':
          description: success
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/BulkRetirementResponse'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AbstractRestError'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                oneOf:
                - $ref: '#/components/schemas/GeneralError'
                - $ref: '#/components/schemas/AbstractRestError'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AbstractRestError'
        '404':
          description: Not Found
          content: {}
        '406':
          description: Not Acceptable
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '422':
          description: Unprocessable Entity
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/GeneralError'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/GeneralError'
components:
  schemas:
    RetirementResponse:
      type: object
      properties:
        correlationId:
          type: string
          description: Matches the correlationId provided in the retirement request.
        retirementIdentifier:
          type: string
          description: Identifier associated with the retirement batch initiated by the system
          example: b24ad896-d899-478d-9513-7061375b637c
      description: Response for the balk retirement request
    RetirementBatchRetrieveByIdentifierResponse:
      type: object
      properties:
        retirementBatches:
          type: array
          description: Collection of retrieved retirement batches
          items:
            $ref: '#/components/schemas/RetirementBatch'
    ReferenceDatum:
      required:
      - code
      type: object
      properties:
        code:
          type: string
          description: The reference data's value.
        name:
          type: string
          description: The reference data's name
      description: A reference datum data object
    Account:
      type: object
      properties:
        srcAcctId:
          type: string
          description: The Account's unique system-assigned identifier used for programmatic (API) interactions.
          example: 4edse581-b97a-11ef-ea69-b61606fd520c
        identifier:
          type: string
          description: The Account's ID as displayed in the registry.
          example: '15184192'
        name:
          type: string
          description: The Account Operating Name on the registry.
          example: APXOPCAR Project Manager
      description: Account record
    BulkRetirementResponse:
      type: object
      properties:
        responses:
          type: array
          description: responses for the bulk retirement request
          items:
            $ref: '#/components/schemas/RetirementResponse'
    RetirementRequest:
      type: object
      properties:
        liabilityHoldingIdentifier:
          type: string
          description: 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'
        retirementReasonCode:
          type: string
          description: Retirement reason code to be associated with retirement
          example: COMPLIANCE_REQUIREMENTS
        holdingCriteria:
          type: array
          description: Criteria for holdings associated with the retirement batch.
          items:
            $ref: '#/components/schemas/QuantifiedHolding'
        correlationId:
          type: string
          description: Client system correlation Id – allows the caller to correlate between requests and responses
        subaccountIdentifier:
          type: string
          description: Target subaccount identifier – required if performing a retirement against a ledger that has subaccounts enabled.
        retirementParameters:
          $ref: '#/components/schemas/JsonNode'
    RetirementBatchRetrieveByIdentifierRequest:
      type: object
      properties:
        onBehalfOfSrcAcctId:
          type: string
          description: 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:
          uniqueItems: true
          type: array
          description: Identifiers associated with the retirement batch initiated by the system
          example: 3574500f-6df3-400e-abc9-e6aeb64f03c7
          items:
            type: string
    ExtShadowedLedgerRetirementOptionsDTO:
      type: object
      properties:
        suppressShadowedLedgerInteraction:
          type: boolean
        shadowedLedgerRetirementIdentifiersByHoldingIdentifier:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ExtShadowedLedgerEntityIdentifierMappingDTO'
    ExternalPlatform:
      type: object
      properties:
        externalPlatformIdentifier:
          type: string
          description: The managing external platform's system-assigned identifier.
          format: uuid
          example: a5f8c9fa-001b-4444-b966-17b1a7871bbf
        code:
          type: string
          description: The External Platform's system code, if applicable.
        name:
          type: string
          description: The External Platform's name.
          example: Xpansiv Connect
        account:
          $ref: '#/components/schemas/Account'
        metadataConfig:
          type: string
          description: Metadata configuration (JSON) for additional fields required by the External Platform.
    ErrorItem:
      type: object
      properties:
        parameter:
          type: string
        correlationId:
          type: string
        path:
          type: string
        field:
          type: string
        code:
          type: string
        message:
          type: string
    ErrorContainer:
      type: object
      properties:
        submissionId:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorItem'
    NamedProtocolVersion:
      type: object
      properties:
        code:
          type: string
          description: Protocol code
          example: AMS-I.D.
        version:
          type: string
          description: Version of Protocol
          example: 1.0.0
        effectiveAt:
          type: string
          description: Start date of the Protocol Version
          format: date-time
        expiresAt:
          type: string
          description: End date of the Protocol Version
          format: date-time
        issuing:
          type: boolean
          description: Issuing/Adorning flag
        shortName:
          type: string
          description: Protocol's short name
          example: AMS-I.D.
    Holding:
      type: object
      properties:
        identifier:
          type: string
          description: The holding's system-assigned identifier.
        resourceProgramAssignedIdentifier:
          type: string
          description: The associated resource's program assigned identifier.
          example: GHG1021
        holdingStatus:
          $ref: '#/components/schemas/ReferenceDatum'
        programPeriodBeginInclusive:
          type: string
          description: Start of program period (vintage) associated to the holding record's issuance.
          format: date-time
          example: '2022-01-01T00:00:00-05:00'
        programPeriodEndExclusive:
          type: string
          description: End of program period (vintage) associated to the holding record's issuance.
          format: date-time
          example: '2023-01-01T00:00:00-05:00'
        timeOfProductionBeginInclusive:
          type: string
          description: Start of production period associated to the holding's issuance
          format: date-time
          example: '2022-01-01T00:00:00-05:00'
        timeOfProductionEndExclusive:
          type: string
          description: End of production period associated to the holding's issuance
          format: date-time
          example: '2023-01-01T00:00:00-05:00'
        serialNumber:
          type: string
          description: The holding record's serial number.
          example: APXOPCAR-GOC-GHG1021-US-2022--46-5701-6700
        quantity:
          type: number
          description: The quantity of the holding record.
          example: 1000
        programVersions:
          type: array
          description: Associated programs and their versions.
          items:
            $ref: '#/components/schemas/ProgramVersion'
        protocolVersions:
          type: array
          description: Associated protocols and their versions.
          items:
            $ref: '#/components/schemas/ProtocolVersion'
        resourceInputTypeCodes:
          type: array
          description: A list of resource input types associated with the holding record's issuance.
          items:
            type: string
        resourceOutputTypeCodes:
          type: array
          description: A list of resource output types associated with the holding record's issuance.
          example: CARBON_REDUCTION
          items:
            type: string
        subaccountIdentifier:
          type: string
          description: The  system-assigned identifier for the subaccount.
          example: 5FF7ABAA-095D-11EF-B304-AA080FC10FFA
        subaccountName:
          type: string
          description: Subaccount name, as inputted by subaccount owner.
          example: My Linked Holdings
        subaccountNumber:
          type: string
          description: Subaccount Id displayed on the Optimal Outcomes platform's UI.
          example: '10033'
        programCertificationGroupCode:
          type: string
          description: The issuing program certification group of the holding record.
          example: NONAFOLU_GHG_MEASUREMENT_PROGRAM
        upn:
          type: string
          description: Xpansiv Connect Universal Project Number (UPN) for Resource associated to the holding's issuance, if assigned.
          example: 0999F5B4
        ein:
          type: string
          description: Xpansiv Connect Environmental Instrument Number (EIN), if assigned.
          example: 1246AFA3E2
        einDescription:
          type: string
          description: Xpansiv Connect Environmental Instrument Number (EIN) details, if assigned
          example: VCU-20120101-20121231-EDEM-3267-ZMB
        shadowedLedgerName:
          type: string
          description: If shadowing = true, the external ledger's name.
          example: Verra
        managingExternalPlatformName:
          type: string
          description: If the holding is held in an external subaccount, the name of the managing external platform associated with the external subaccount.
          example: Xpansiv Connect
        holdingGroupIdentifier:
          type: string
          description: Identifier for grouped holdings in transfer operations, if applicable.
        certificateType:
          $ref: '#/components/schemas/ReferenceDatum'
    RetirementBatch:
      type: object
      properties:
        identifier:
          type: string
          description: The Retirement Batch's system-assigned identifier.
        originalQuantity:
          type: number
          description: The total quantity of holdings included in the retirement batch.
        liabilityIssuanceIdentifier:
          type: string
          description: System-assigned identifier of the liability issuance associated with the retirement
        liabilityHoldingIdentifier:
          type: string
          description: System-assigned Identifier of the liability holding against which the retirement was performed.
          example: '476022'
        subaccount:
          $ref: '#/components/schemas/Subaccount'
        shadowedLedgerRetirementBatchIdentifier:
          type: string
          description: If shadowing = true, the corresponding Retirement Batch identifier from the external ledger.
        positions:
          type: array
          description: Collection of the retirement batch's associated holdings.
          items:
            $ref: '#/components/schemas/Holding'
        createdAt:
          type: string
          description: Created at timestamp for the Retirement Batch
          format: date-time
        lastUpdatedAt:
          type: string
          description: Last updated at timestamp for the Retirement Batch
          format: date-time
        retirementParameters:
          $ref: '#/components/schemas/JsonNode'
    ExtShadowedLedgerEntityIdentifierMappingDTO:
      type: object
      properties:
        holdingIdentifier:
          type: string
        shadowedLedgerEntityIdentifier:
          type: string
    QuantifiedHolding:
      type: object
      properties:
        holdingIdentifier:
          type: string
          description: Holding Identifier, as returned by the holdings API
          example: '476099'
        quantity:
          type: number
          description: Quantity of holding to be used in this operation
          example: 3
      description: Quantified Holding
    ProgramVersion:
      type: object
      properties:
        code:
          type: string
          description: Program code
          example: GHG_MEASUREMENT_PROGRAM
        version:
          type: string
          description: Version of Program.
          example: 5.0.0
        shortName:
          type: string
          description: Program short name
          example: Carbon Measurement
        protocolVersions:
          type: array
          description: A list of Protocols associated with Program.
          items:
            $ref: '#/components/schemas/NamedProtocolVersion'
    AbstractRestError:
      type: object
      properties:
        code:
          type: string
        ticket:
          type: string
        message:
          type: string
    GeneralError:
      type: object
      properties:
        code:
          type: string
        ticket:
          type: string
        message:
          type: string
    BulkRetirementRequest:
      type: object
      properties:
        onBehalfOfSrcAcctId:
          type: string
          description: If permitted, allows the caller to retire on behalf of another account holder, identifying that account holder by their system-assigned srcAcctId.
        requests:
          type: array
          description: retirement request
          items:
            $ref: '#/components/schemas/RetirementRequest'
        shadowedLedgerRetirementOptions:
          $ref: '#/components/schemas/ExtShadowedLedgerRetirementOptionsDTO'
    JsonNode:
      type: object
    ProtocolVersion:
      type: object
      properties:
        code:
          type: string
          description: Protocol code
          example: AMS-I.D.
        version:
          type: string
          description: Version of Protocol
          example: 1.0.0
        effectiveAt:
          type: string
          description: Start date of the Protocol Version
          format: date-time
        expiresAt:
          type: string
          description: End date of the Protocol Version
          format: date-time
        issuing:
          type: boolean
          description: Issuing/Adorning flag
    Subaccount:
      required:
      - name
      type: object
      properties:
        identifier:
          type: string
          description: The sub-account's system-assigned identifier.
          readOnly: true
          example: 6192c733-bbd2-11ef-acad-b63fd176813a
        number:
          type: string
          description: Sub-account number
          readOnly: true
        account:
          $ref: '#/components/schemas/Account'
        name:
          type: string
          description: Sub-account name
          example: Allocated
        description:
          type: string
          description: Sub-account description
          example: Holdings to retired & retired
        _default:
          type: boolean
          description: If true, this is the default sub-account
          writeOnly: true
          example: true
        status:
          $ref: '#/components/schemas/ReferenceDatum'
        viableStatusTransitions:
          uniqueItems: true
          type: array
          description: Viable Sub-account transitions
          readOnly: true
          items:
            type: string
            description: Subaccount Transition
            enum:
            - edit
            - activate
            - deactivate
        managingExternalPlatform:
          $ref: '#/components/schemas/ExternalPlatform'
        managingExternalPlatformAccountId:
          type: string
          description: If this is a managed sub-account, the relevant account ID in the external platform for the account associated with this sub-account.
        managingExternalPlatformSubaccountMetadata:
          type: string
          description: Optional JSON payload of managing external platform subaccount metadata.
        default:
          type: boolean
          description: If true, this is the default sub-account
          readOnly: true
          example: true
      description: This class contains caller-visible set of sub-accounts for either the calling account or the account identified by onBehalfOfSrcAcctId