Xpansiv Connect API

openapi: 3.0.1
info:
  description: >-
    This is the OpenAPI spec for Xpansiv Connect API. Documentation:
    https://developer.xpansiv.com/developer-portal/
  title: Xpansiv Connect API
  version: 1.0.0-beta
servers:
  - url: https://sandbox.preprod.connect.xpansiv.com/app/api/v1
    description: SANDBOX
  - url: https://uat.preprod.connect.xpansiv.com/app/api/v1
    description: UAT
  - url: https://connect.xpansiv.com/app/api/v1
    description: PROD
tags:
  - name: Account
    description: >
      The Account API allows uses of Xpansiv Connect to pull a list of their
      registry sub-accounts. As related to the  retirement activity, the list
      reflects the retirement sub-accounts which are required when executing
      retirements  in specific registries or when searching retirement history.
      The registries with data to return for this call  are NEPOOL, M_RETS, NAR,
      MIRECS, NCRETS, NYGATS, TIGR, CAR, VCS, ACR, RMS AND TERCS.
  - name: Exchange
    description: >
      The Exchange APIs allow users to take various actions, both read and
      write, for their interactions with  execution venues, such as the CBL
      platform. The Search Deposits API allows the user to search the current
      deposits placed on execution venues. The Deposit Creation API allows the
      user to place inventory on deposit on a target execution venue.  The
      Deposit Withdraw API allows the user to withdraw and place back into
      inventory deposits held on an execution venue.  The Deposit Withdraw and
      Create Retirements API allows the user to withdraw and retire deposits
      held on an  execution venue.  The Deposit Settlement API call would be
      used to settle executed trades on an execution venue by an execution 
      venue operator.
  - name: Forward Deals
    description: >
      The Forward Deals API allows the user to search The Forward Deals
      associated with their Xpansiv Connect account  and/or other Xpansiv
      Connect accounts that have granted their user that access. Forward Deal
      information is  returned based on a Deal's last updated date. Note that
      this call has a number of optional fields that the users  needs to include
      if desired in the output.
  - name: Issuances
    description: >
      The Issuance API allows the user to pull information on any Issuances
      associated with their account,  or permissioned account, for the various
      registries they are linked with. The Instrument details on the  Issuance
      will be returned in the format of a Carbon Instrument (type CARBON) or a
      REC Instrument (type REC)  as appropriate. Each of the types are returned
      with data specific to the Carbon or REC attributes.
  - name: Portfolio
    description: >
      The Portfolio API allows the user to search their credit inventory (tax
      lot) data on active positions  across all registry accounts linked to
      their Xpansiv Connect account and/or other Xpansiv Connect accounts  that
      have granted their user that access. Note that This call has a number of
      optional fields that the user  needs to include if desired in the output.
  - name: Projects
    description: >
      The Project API allows the user to pull publicly available information
      about carbon projects registered  in the registries that are integrated
      with Xpansiv Connect. Note - this call has a number of optional fields 
      that the user needs to include if desired in the output.
  - name: ReferenceData
    description: >-
      The Reference Data API enables discovering Xpansiv Connect reference data
      types and values.
  - name: Reports
    description: >
      The Reports API allows the user to retrieve a comprehensive credit
      inventory (aka Tax Lot by Program Report)  on all active positions with a
      single call across all registry accounts linked to their Xpansiv Connect
      account  or other Xpansiv Connect accounts that have granted their user
      that access. Note - this call has a number of  optional fields that the
      user needs to include if desired in the output.
  - name: Retirements
    description: >
      The Retirements APIs allow users to take various actions, both read and
      write, for their retirement  activity. The Create Retirements API allows
      users of Xpansiv Connect to retire one or more positions from  their
      linked registry accounts and/or other Xpansiv Connect accounts that have
      granted their API user with  that access. The Get Registry Rules API call
      provides the user with the information required to pass the  correct rule
      attributes specific to each registry with each retirement attempt. The
      Check Retirement Status  API allows users to query the status of their
      retirements. The Search retirements API allows users search their 
      retirement history. Note - this call has a number of optional fields that
      the user needs to include if  desired in the output.
  - name: Split Lots
    description: >
      The Split Lots API allows the user to search split lot data on their
      Xpansiv Connect account and/or other  Xpansiv Connect accounts that have
      granted your user that access.
  - name: Transfers
    description: >
      The Transfers APIs allow users to  take various actions, both read and
      write, for their bilateral transaction  activity. The Search Transfers API
      allows the user to search registry transfer data for their Xpansiv 
      Connect account and/or other Xpansiv Connect accounts that have granted
      your user that access. Note - this  call has a number of optional fields
      that the user needs to include if desired in the output.  The Create
      Transfers API allows the user to create new bilateral transfers. The
      Cancel Transfers API allows  the user to cancel/withdrawal any pending
      outgoing transfers. The Reject Transfers API allows the user to  reject
      any pending incoming transfer. The Accept Transfers API allows the user to
      accept any pending incoming transfer.
security:
  - bearerToken: []
paths:
  /reference-data:
    get:
      tags:
        - ReferenceData
      operationId: getReferenceData
      summary: Retrieve list of reference data
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                          code:
                            type: string
                          description:
                            type: string
                          order:
                            type: integer
                            format: int64
                          value:
                            type: string
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
  /account/{AccountIdentifier}/program/{ProgramCode}/subaccounts:
    get:
      tags:
        - Account
      operationId: getSubAccountsByProgram
      summary: Get sub-accounts
      description: Get sub-accounts for a given account and program
      parameters:
        - $ref: '#/components/parameters/AccountIdentifier'
        - $ref: '#/components/parameters/ProgramCode'
      responses:
        '200':
          description: List of sub-accounts
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - code
                    - name
                    - subAccountType
                    - active
                    - public
                  properties:
                    code:
                      type: string
                      description: Unique identifier.
                    name:
                      type: string
                      description: Name of the Sub-Account in the registry.
                    subAccountType:
                      $ref: '#/components/schemas/Ref.SubAccountType'
                    active:
                      type: boolean
                      description: True/False.
                    public:
                      type: boolean
                      description: True/False.
                    complianceStatus:
                      $ref: '#/components/schemas/Ref.ComplianceStatus'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - INVALID_PROGRAM
                  message:
                    type: string
                  field:
                    type: string
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
  /account/{AccountIdentifier}:
    get:
      summary: Search for account
      tags:
        - Account
      operationId: accountSearch
      parameters:
        - $ref: '#/components/parameters/AccountIdentifier'
        - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: Account found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - INVALID_REQUEST
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
  /account-holders/action/search:
    post:
      operationId: searchAccountHolders
      tags:
        - AccountHolders
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      summary: Account Holders search
      requestBody:
        description: Account Holders search endpoint
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                registryAccountId:
                  type: string
                  description: ID of the account on the registry.
                registryAccountName:
                  type: string
                program:
                  $ref: '#/components/schemas/Ref.Program'
                accountType:
                  type: string
                  description: Account type description.
                active:
                  type: boolean
                  description: True/False.
                generatorAccount:
                  type: boolean
                  description: True/False.
      responses:
        '200':
          description: Account Holders search successfully executed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - type: object
                    properties:
                      content:
                        type: array
                        items:
                          $ref: '#/components/schemas/AccountHolder'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - INVALID_REQUEST
                      - INVALID_PROGRAM
                      - INVALID_PAGE_SIZE
                      - INVALID_PAGE_NUMBER
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
  /exchanges/{ExchangeCode}/accounts/{AccountIdentifier}/action/search-deposits:
    parameters:
      - $ref: '#/components/parameters/ExchangeCode'
      - $ref: '#/components/parameters/AccountIdentifier'
    post:
      summary: Search deposits
      description: Get list of deposits for an exchange
      tags:
        - Exchange
      operationId: searchDeposits
      responses:
        '200':
          description: List of deposits
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - depositIdentifier
                    - executionVenue
                    - taxLot
                    - instrument
                    - quantity
                    - availableQuantity
                    - settledQuantity
                    - status
                  properties:
                    depositIdentifier:
                      type: string
                      description: Unique identifier.
                    executionVenue:
                      type: object
                      required:
                        - code
                        - name
                      properties:
                        code:
                          $ref: '#/components/schemas/Ref.ExecutionVenue'
                        name:
                          type: string
                          description: Target execution venue code name.
                    depositMarket:
                      type: object
                      required:
                        - market
                        - marketModelInstrument
                      properties:
                        market:
                          type: object
                          required:
                            - name
                            - apiCode
                          properties:
                            name:
                              type: string
                              description: >-
                                Name of the target market on the execution
                                venue.
                            apiCode:
                              type: string
                              description: AIP code sent to the execution venue.
                        marketModelInstrument:
                          type: object
                          required:
                            - description
                            - price
                          properties:
                            description:
                              type: string
                              description: >-
                                Description of the Market Model Instrument for
                                the deposit.
                            price:
                              type: object
                              required:
                                - amount
                              properties:
                                amount:
                                  type: number
                                  format: double
                                  description: Price, if applicable, for the deposit.
                    taxLot:
                      type: object
                      required:
                        - name
                      properties:
                        name:
                          type: string
                          description: The name of the TaxLot associated with the deposit.
                    instrument:
                      type: object
                      required:
                        - ein
                        - description
                        - program
                        - vintage
                        - resource
                      properties:
                        ein:
                          type: string
                          description: The EIN code for the deposit.
                        description:
                          type: string
                          description: >-
                            The Xpansiv Connect description for the EIN on the
                            deposit.
                        type:
                          $ref: '#/components/schemas/Ref.InstrumentType'
                        program:
                          $ref: '#/components/schemas/Ref.Program'
                        vintage:
                          $ref: '#/components/schemas/Vintage'
                        resource:
                          type: object
                          required:
                            - name
                          properties:
                            name:
                              type: string
                              description: The registry name of the item on deposit.
                            registryAssignedId:
                              type: string
                              description: >-
                                The registry assigned id for the item on
                                deposit.
                    quantity:
                      type: integer
                      format: int64
                      description: The original quantity of the deposit.
                    availableQuantity:
                      type: integer
                      format: int64
                      description: The remaining quantity of the deposit.
                    settledQuantity:
                      type: integer
                      format: int64
                      description: >-
                        The quantity of the deposit settled as a result of
                        trading activity.
                    status:
                      $ref: '#/components/schemas/Ref.DepositStatus'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - INVALID_EXCHANGE
                      - INVALID_ACCOUNT
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /exchanges/{ExchangeCode}/execution-venues/{ExecutionVenueCode}/accounts/{AccountIdentifier}/action/deposit:
    parameters:
      - $ref: '#/components/parameters/ExchangeCode'
      - $ref: '#/components/parameters/ExecutionVenueCode'
      - $ref: '#/components/parameters/AccountIdentifier'
    post:
      summary: Deposits creation
      description: Deposits creation
      tags:
        - Exchange
      operationId: deposit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - market
                - deposits
              properties:
                market:
                  type: string
                deposits:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required:
                      - taxLotId
                      - quantity
                    properties:
                      taxLotId:
                        type: integer
                        format: int64
                        description: >-
                          TaxLot id of the inventory selected for the deposit to
                          the execution venue.
                      quantity:
                        type: integer
                        format: int64
                        minimum: 1
                        description: Quantity to be deposited.
                      priority:
                        type: integer
                        format: int64
                        description: >-
                          Priority for the deposit to be used in the trade
                          settlement process.
      responses:
        '200':
          description: Deposits created
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - depositIdentifier
                  properties:
                    depositIdentifier:
                      type: string
                      description: The depositIdentifier of create deposit.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - message
                properties:
                  code:
                    type: string
                    enum:
                      - INVALID_REQUEST
                      - INVALID_EXCHANGE
                      - INVALID_ACCOUNT
                      - INVALID_EXECUTION_VENUE
                      - INVALID_DEPOSITS
                      - INVALID_MARKET
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          enum:
                            - NOT_ENOUGH_QUANTITY
                            - DUPLICATE_TAX_LOT
                            - TAX_LOT_NOT_FOUND
                        message:
                          type: string
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /exchanges/{ExchangeCode}/accounts/{AccountIdentifier}/action/withdraw:
    parameters:
      - $ref: '#/components/parameters/ExchangeCode'
      - $ref: '#/components/parameters/AccountIdentifier'
    post:
      summary: Deposits withdraw
      description: Deposits withdraw
      tags:
        - Exchange
      operationId: withdraw
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - withdrawals
              properties:
                withdrawals:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required:
                      - depositIdentifier
                      - quantity
                    properties:
                      depositIdentifier:
                        type: string
                        description: The depositIdentifier of the deposit to withdraw.
                      quantity:
                        type: integer
                        format: int64
                        description: Quantity of the amount on deposit to be withdrawn.
                        minimum: 1
      responses:
        '200':
          description: Deposits withdrawn
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - depositIdentifier
                    - status
                  properties:
                    depositIdentifier:
                      type: string
                      description: >-
                        The depositIdentifier with which the withdraw request
                        was made.
                    status:
                      $ref: '#/components/schemas/Ref.WithdrawStatus'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - message
                properties:
                  code:
                    type: string
                    enum:
                      - INVALID_REQUEST
                      - DEPOSIT_NOT_FOUND
                      - INVALID_EXCHANGE
                      - INVALID_WITHDRAWALS
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          enum:
                            - NOT_ENOUGH_QUANTITY
                        message:
                          type: string
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /exchanges/{ExchangeCode}/account/{AccountIdentifier}/program/{RetirementProgramCode}/action/withdraw-and-retire:
    post:
      tags:
        - Exchange
      operationId: withdrawAndRetire
      parameters:
        - $ref: '#/components/parameters/ExchangeCode'
        - $ref: '#/components/parameters/AccountIdentifier'
        - $ref: '#/components/parameters/RetirementProgramCode'
      summary: Withdraw credits and create retirements
      description: >-
        Allows the combination of withdrawal of credits and creation of
        retirements in bulk
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - dryRun
                - retirements
              properties:
                dryRun:
                  description: >-
                    If true it will only do the validation of the request but
                    not to create the retirements
                  type: boolean
                retirements:
                  type: array
                  items:
                    type: object
                    required:
                      - ein
                      - quantity
                    properties:
                      ein:
                        type: string
                      quantity:
                        type: integer
                        format: int64
                      externalIdentifier:
                        type: string
                attributes:
                  type: object
                  additionalProperties: true
        required: true
      responses:
        '200':
          description: Retirements
          content:
            application/json:
              schema:
                type: object
                required:
                  - retirements
                  - batchIdentifier
                properties:
                  retirements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Retirement'
                  batchIdentifier:
                    type: string
                    description: EMA retirement batch identifier
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - INVALID_PROGRAM
                      - INVALID_REQUEST
                      - EMPTY_REQUEST
                      - INVALID_ATTRIBUTES
                      - INVALID_RETIREMENTS
                      - INVALID_EXCHANGE
                      - INVALID_ACCOUNT
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        message:
                          type: string
                  attributeErrors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          enum:
                            - INVALID_TYPE
                            - INVALID_VALUE
                            - UNEXPECTED_FIELD
                            - UNAVAILABLE_FIELD
                            - REQUIRED_FIELD
                            - INVALID_SUB_ACCOUNT
                            - INVALID_BENEFICIAL_OWNER_NAME
                        message:
                          type: string
                        field:
                          type: string
                        value:
                          type: string
                  retirementErrors:
                    type: array
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          code:
                            type: string
                            enum:
                              - INVALID_VALUE
                              - QUARANTINED_POSITION
                              - INSUFFICIENT_QUANTITY
                              - INVALID_EIN
                              - DUPLICATE_EIN
                              - INVALID_TAX_LOT_ALLOCATION_STRATEGY
                              - INVALID_TAX_LOT_ALLOCATION
                              - UNEXPECTED_QUANTITY_PER_TAX_LOT
                              - ZERO_QUANTITY_TAX_LOTS
                              - DUPLICATE_TAX_LOTS
                              - ZERO_QUANTITY
                              - INVALID_QUANTITY_SUM
                              - EIN_CURRENTLY_LOCKED
                          message:
                            type: string
                          field:
                            type: string
                          value:
                            type: string
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
  /exchanges/{ExchangeCode}/account/{AccountIdentifier}/program/{ProgramCode}/action/withdraw-and-export:
    post:
      tags:
        - Exchange
      operationId: withdrawAndExport
      parameters:
        - $ref: '#/components/parameters/ExchangeCode'
        - $ref: '#/components/parameters/AccountIdentifier'
        - $ref: '#/components/parameters/ProgramCode'
      summary: Withdraw credits and create exports
      description: >-
        Allows the combination of withdrawal of credits and creation of export
        in bulk
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - exports
              properties:
                dryRun:
                  description: >-
                    If true it will only do the validation of the request but
                    not withdraw nor export
                  type: boolean
                exports:
                  type: array
                  items:
                    type: object
                    required:
                      - ein
                      - quantity
                    properties:
                      ein:
                        type: string
                      quantity:
                        type: integer
                        format: int64
                      externalIdentifier:
                        type: string
        required: true
      responses:
        '200':
          description: Successful withdraw and export
          content:
            application/json:
              schema:
                type: object
                required:
                  - batchIdentifier
                  - exports
                properties:
                  batchIdentifier:
                    type: string
                    description: EMA export batch identifier
                  exports:
                    type: array
                    items:
                      type: object
                      required:
                        - tran

# --- truncated at 32 KB (142 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xpansiv/refs/heads/main/openapi/xpansiv-connect-openapi.yml