openapi: 3.2.0
info:
  description: 'This is the OpenAPI spec for Xpansiv Connect API. Documentation: https://developer.xpansiv.com/developer-portal/'
  title: Xpansiv Connect Issuances 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
security:
- bearerToken: []
tags:
- 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.
paths:
  /issuances/account/{AccountIdentifier}/action/search:
    post:
      tags:
      - Issuances
      operationId: searchIssuances
      summary: Search issuances
      parameters:
      - $ref: '#/components/parameters/AccountIdentifier'
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/Include'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                identifier:
                  type: string
                createdDateFrom:
                  type: string
                  format: date-time
                createdDateTo:
                  type: string
                  format: date-time
                programs:
                  type: array
                  items:
                    $ref: '#/components/schemas/Ref.Program'
      responses:
        '200':
          description: List of issuances
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Page'
                - type: object
                  properties:
                    content:
                      type: array
                      items:
                        type: object
                        properties:
                          identifier:
                            type: string
                            description: Unique identifier.
                          type:
                            type: string
                            description: Issuance type.
                            default: ISSUANCE
                          status:
                            type: string
                            description: Issuance status.
                            default: Issued
                          quantity:
                            type: integer
                            format: int64
                            description: Issuance quantity.
                          unitPrice:
                            allOf:
                            - $ref: '#/components/schemas/Price'
                            description: Issuance price.
                          createdDate:
                            type: string
                            format: date-time
                            description: Issuance created date.
                          lastUpdatedDate:
                            type: string
                            format: date-time
                            description: Issuance last updated date.
                          externalTransferIdentifier:
                            type: string
                            description: Issuance external transfer identifier.
                          taxLot:
                            type: object
                            properties:
                              id:
                                type: integer
                                format: int64
                                description: TaxLot identifier.
                              name:
                                type: string
                                description: TaxLot name.
                          instrument:
                            $ref: '#/components/schemas/Instrument'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                    - INVALID_REQUEST
                    - INVALID_PROGRAM
                    - INVALID_DATE_RANGE
                    - INVALID_PAGE_SIZE
                    - INVALID_PAGE_NUMBER
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
components:
  schemas:
    Instrument:
      oneOf:
      - $ref: '#/components/schemas/CarbonInstrument'
      - $ref: '#/components/schemas/RecInstrument'
      - $ref: '#/components/schemas/ResourceInstrument'
    RecInstrument:
      allOf:
      - $ref: '#/components/schemas/BaseInstrument'
      - type: object
        required:
        - generator
        properties:
          fuelType:
            $ref: '#/components/schemas/FuelType'
          stateEligibilities:
            type: array
            description: Optional property. Use `include` param.
            items:
              type: object
              description: Object to hold full state eligibility information - type of eligibility and name
              properties:
                name:
                  type: string
                  description: Name of the state eligibility.
                type:
                  $ref: '#/components/schemas/Ref.StateEligibilityType'
          voluntaryEligibilities:
            type: array
            description: Optional property. Use `include` param.
            items:
              $ref: '#/components/schemas/VoluntaryEligibility'
          generator:
            $ref: '#/components/schemas/Generator'
    Market:
      properties:
        name:
          type: string
          description: Name of the market.
        apiCode:
          type: string
          description: API code for market execution venue.
        applicableExecutionVenues:
          type: array
          items:
            $ref: '#/components/schemas/Ref.ExecutionVenue'
        applicablePrograms:
          type: array
          items:
            $ref: '#/components/schemas/Ref.Program'
    MarketModelInstrumentPrice:
      properties:
        amount:
          type: number
          format: double
          description: Amount.
        currency:
          $ref: '#/components/schemas/Ref.Currency'
        lastUpdatedDate:
          type: string
          format: date-time
          description: Last updated date-time.
    Ref.ResourceProgram:
      type: string
      description: Ref.Data.RESOURCE_PROGRAM
    CarbonInstrument:
      allOf:
      - $ref: '#/components/schemas/BaseInstrument'
      - type: object
        required:
        - project
        properties:
          serialNumber:
            type: string
          issuanceCertifications:
            type: array
            description: Optional property. Use `include` param.
            items:
              $ref: '#/components/schemas/IssuanceCertification'
          projectCertifications:
            type: array
            description: Optional property. Use `include` param.
            items:
              $ref: '#/components/schemas/ProjectCertification'
          reportingPeriodStart:
            type: string
            format: date-time
            description: Reporting period start date.
          reportingPeriodEnd:
            type: string
            format: date-time
            description: Reporting period end date.
          project:
            $ref: '#/components/schemas/Project'
    ProjectCertification:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/Ref.Certification'
        projectCertificationDateRanges:
          type: array
          items:
            type: object
            properties:
              certificationStart:
                type: string
                format: date-time
                description: The project certification start date.
              certificationEnd:
                type: string
                format: date-time
                description: The project certification end date.
    BaseInstrument:
      type: object
      required:
      - type
      - ein
      - program
      - vintage
      - creditType
      properties:
        type:
          $ref: '#/components/schemas/Ref.InstrumentType'
        id:
          type: integer
          format: int64
          description: Unique Xpansiv Connect identifier.
        ein:
          type: string
          description: 'Environment Instrument Number. Unique identifier associated with an issuance of credits from a given project,  vintage, technology/fuel type and associated certification(s)/eligibility(s). An EIN is associated with a  position and a position will never be associated with more than 1 EIN.

            '
        description:
          type: string
          description: 'The Xpansiv Connect description associated with the instrument providing information regarding location,  vintage, fuel type and certifications.

            '
        program:
          $ref: '#/components/schemas/Ref.Program'
        vintage:
          $ref: '#/components/schemas/Vintage'
        markets:
          type: array
          description: Optional property. Use `include` param.
          items:
            $ref: '#/components/schemas/InstrumentMarket'
        creditType:
          type: string
          description: The type of the credit.
      discriminator:
        propertyName: type
        mapping:
          CARBON: '#/components/schemas/CarbonInstrument'
          REC: '#/components/schemas/RecInstrument'
          RESOURCE_PROJECT: '#/components/schemas/ResourceInstrument'
    Price:
      type: object
      required:
      - currency
      - amount
      properties:
        currency:
          $ref: '#/components/schemas/Ref.Currency'
        amount:
          type: number
          description: The numeric value of the price
          minimum: 0
    InstrumentMarket:
      properties:
        market:
          $ref: '#/components/schemas/Market'
        marketModelInstrument:
          $ref: '#/components/schemas/MarketModelInstrument'
    Ref.VoluntaryEligibilityType:
      type: string
      description: The type of the voluntary eligibility. Ref.Data.REC_VOLUNTARY_ELIGIBILITY
    Ref.GeneratorStatus:
      type: string
      description: The status of the generator in the registry. Ref.Data.GENERATOR_STATUS
    Ref.ResourceInType:
      type: string
      description: Ref.Data.RESOURCE_INPUT_TYPE
    Ref.ResourceOutType:
      type: string
      description: Ref.Data.RESOURCE_OUTPUT_TYPE
    NotAuthorizedError:
      type: object
      properties:
        message:
          type: string
    Ref.ExecutionVenue:
      type: string
      description: Ref.Data.EXECUTION_VENUE
    Ref.CarbonProgram:
      type: string
      description: Ref.Data.CARBON_PROGRAM
    Generator:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          program:
            $ref: '#/components/schemas/Ref.RecProgram'
          registryAssignedId:
            type: string
            description: The registry assigned identifier for the generator.
          status:
            $ref: '#/components/schemas/Ref.GeneratorStatus'
          siteCode:
            type: string
            description: The Site Code of the generator if provided by the registry.
          unitName:
            type: string
            description: The Unit Name of the generator in the registry.
          controlArea:
            type: string
            description: The Control Area that the generator is located in.
          parentCompanyName:
            type: string
            description: The Parent Company Name of the generator if provided by the registry.
          powerCompanyName:
            type: string
            description: The Power Company Name of the generator if provided by the registry.
          powerCompanyCode:
            type: string
            description: The Power Company Code of the generator if provided by the registry.
          ownerName:
            type: string
            description: The Owner Name of the generator if provided by the registry
          ownershipType:
            type: string
            description: The Ownership Type of the generator if provided by the registry.
          countyName:
            type: string
            description: The County Name locatio of the generator if provided by the registry.
          stateProvince:
            $ref: '#/components/schemas/Ref.StateProvince'
          country:
            $ref: '#/components/schemas/Ref.Country'
          contactInfo:
            type: string
            description: Contact Information for the generator if provided by the registry.
          registryAcctHolderName:
            type: string
            description: The Registry Account Holder name of the generator if provided by the registry.
          commencedDt:
            type: string
            format: date-time
            description: The Commenced Operation Date of the generator if provided by the registry.
          nameplateCapacity:
            type: number
            format: double
            description: The Nameplate Capacity of the generator if provided by the registry.
          facNoncompetitiveCertData:
            type: string
          fuelTypes:
            type: array
            description: Additional information about a generator if it is multi-fuel. Optional property. Use `include` param.
            items:
              title: Fuel Type Eligibility aggregation
              type: object
              required:
              - fuelType
              properties:
                fuelType:
                  $ref: '#/components/schemas/FuelType'
                stateEligibilities:
                  type: array
                  items:
                    $ref: '#/components/schemas/StateEligibility'
                voluntaryEligibilities:
                  type: array
                  items:
                    $ref: '#/components/schemas/VoluntaryEligibility'
    Project:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        required:
        - programs
        properties:
          programs:
            type: array
            items:
              type: object
              title: ProjectProgram
              required:
              - program
              - registryAssignedId
              - status
              - creditType
              - projectType
              properties:
                program:
                  $ref: '#/components/schemas/Ref.CarbonProgram'
                programName:
                  type: string
                  description: Registry name.
                registryAssignedId:
                  type: string
                  description: ID assigned by the registry.
                registryAccountHolderName:
                  type: string
                  description: Name of the registry account holder.
                status:
                  $ref: '#/components/schemas/Ref.ProjectRegistryStatus'
                creditType:
                  $ref: '#/components/schemas/Ref.CreditType'
                projectType:
                  $ref: '#/components/schemas/Ref.ProjectType'
                baselineMethodologies:
                  type: array
                  items:
                    $ref: '#/components/schemas/Ref.BaselineMethodology'
                creditingPeriodBegin:
                  type: string
                  format: date-time
                  description: Begin date for credit reporting.
                creditingPeriodEnd:
                  type: string
                  format: date-time
                  description: End date for credit reporting.
          description:
            type: string
            description: The full description from the registry.
          status:
            $ref: '#/components/schemas/Ref.ProjectStatus'
          country:
            $ref: '#/components/schemas/Ref.Country'
          stateProvince:
            type: string
            description: State or Province
          city:
            type: string
            description: City.
          location:
            $ref: '#/components/schemas/Location'
          annualAverageOffsetQty:
            type: integer
            format: int64
            description: Annual average offset quantity.
          projectCertifications:
            type: array
            description: Optional property. Use `include` param.
            items:
              $ref: '#/components/schemas/ProjectCertification'
          issuanceCertifications:
            type: array
            description: Optional property. Use `include` param.
            items:
              $ref: '#/components/schemas/IssuanceCertification'
    Ref.StateEligibilityType:
      type: string
      description: The type of the state eligibility. Ref.Data.REC_STATE_ELIGIBILITY
    Location:
      title: Resource location
      type: object
      properties:
        latitude:
          type: number
          format: double
          description: Latitude.
        longitude:
          type: number
          format: double
          description: Longitude.
    Page:
      type: object
      required:
      - page
      - size
      - totalPages
      - totalElements
      properties:
        page:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        totalPages:
          type: integer
          format: int32
        totalElements:
          type: integer
          format: int64
    ResourceInstrument:
      allOf:
      - $ref: '#/components/schemas/BaseInstrument'
      - type: object
        required:
        - resourceProject
        properties:
          serialNumber:
            type: string
          inType:
            $ref: '#/components/schemas/Ref.ResourceInType'
          outType:
            $ref: '#/components/schemas/Ref.ResourceOutType'
          resourceProject:
            $ref: '#/components/schemas/ResourceProject'
    InternalServerError:
      type: object
      properties:
        message:
          type: string
    Ref.FuelType:
      type: string
      description: Ref.Data.REC_FUEL_TYPE
    Ref.RecProgram:
      type: string
      description: Ref.Data.REC_PROGRAM
    StateEligibility:
      type: object
      description: Object to hold full state eligibility information - type of eligibility, extendable with other information
      properties:
        name:
          type: string
          description: Name of the state eligibility.
        type:
          $ref: '#/components/schemas/Ref.StateEligibilityType'
        stateIdentifier:
          type: string
          description: This is the identifier of the eligibility from the registry
    MarketModelInstrument:
      properties:
        ein:
          type: string
          description: 'Environment Instrument Number. Unique identifier associated with an issuance of credits from a given project,  vintage, technology/fuel type and associated certification(s)/eligibility(s).  An EIN is associated with a position and a position will never be associated with more than 1 EIN.

            '
        description:
          type: string
          description: Description.
        price:
          $ref: '#/components/schemas/MarketModelInstrumentPrice'
    Ref.ResourceProjectStatus:
      type: string
      description: Ref.Data.RESOURCE_PROJECT_STATUS
    Ref.ProjectType:
      type: string
      description: The project type. Ref.Data.CARBON_PROJECT_TYPE
    ResourceProject:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        required:
        - programs
        properties:
          programs:
            type: array
            items:
              type: object
              title: ResourceProjectProgram
              required:
              - program
              - registryAssignedId
              properties:
                program:
                  $ref: '#/components/schemas/Ref.ResourceProgram'
                programName:
                  type: string
                registryAssignedId:
                  type: string
          status:
            $ref: '#/components/schemas/Ref.ResourceProjectStatus'
          country:
            $ref: '#/components/schemas/Ref.Country'
          accountName:
            type: string
          classification1:
            type: string
          classification2:
            type: string
          classification3:
            type: string
          childResourceProject:
            $ref: '#/components/schemas/ChildResourceProject'
          inOutTypes:
            type: array
            items:
              type: object
              required:
              - inType
              - outType
              properties:
                inType:
                  $ref: '#/components/schemas/Ref.ResourceInType'
                outType:
                  $ref: '#/components/schemas/Ref.ResourceOutType'
          typeName:
            type: string
    FuelType:
      type: object
      properties:
        name:
          type: string
          description: The fuel type associated with the underlying asset.
        type:
          $ref: '#/components/schemas/Ref.FuelType'
        fuelSource:
          type: string
          description: The registry fuel source associated with the fuel type (registry-dependent).
    Ref.InstrumentType:
      type: string
      description: REC or CARBON. Ref.Data.INSTRUMENT_TYPE
    Ref.Country:
      type: string
      description: Ref.Data.COUNTRY
    Ref.ProjectStatus:
      type: string
      description: Ref.Data.PROJECT_STATUS
    Ref.Certification:
      type: string
      description: Certification code. Ref.Data.CARBON_CERTIFICATION
    IssuanceCertification:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/Ref.Certification'
        vintageYears:
          type: array
          description: Vintage years.
          items:
            type: integer
            format: int32
    VoluntaryEligibility:
      type: object
      description: Object to hold full voluntary eligibility information - type of eligibility, effective date, expiration, extendable with other information
      properties:
        name:
          type: string
          description: The name of the registry voluntary eligibility.
        type:
          $ref: '#/components/schemas/Ref.VoluntaryEligibilityType'
        effectiveDate:
          type: string
          format: date-time
          description: The effective date of the eligibility.
        expirationDate:
          type: string
          format: date-time
          description: the expiration date of the eligibility.
    Vintage:
      type: object
      required:
      - year
      properties:
        year:
          type: integer
          format: int32
          description: Vintage year.
        month:
          type: integer
          format: int32
          description: Vintage month.
    Ref.StateProvince:
      type: string
      description: Ref.Data.STATE_PROVINCE
    Ref.Program:
      type: string
      description: Ref.Data.PROGRAM
    Ref.ProjectRegistryStatus:
      type: string
      description: The registry status of the project. Ref.Data.PROJECT_REGISTRY_STATUS
    Ref.BaselineMethodology:
      type: string
      description: Ref.Data.BASELINE_METHODOLOGY
    Resource:
      type: object
      required:
      - name
      properties:
        id:
          type: integer
          format: int64
          description: The unique XC db identifier for the project or generator.
        upn:
          type: string
          description: 'Universal Project Identifier. The unique identifier assigned by Xpansiv Connect to every resource across all registries that  have integrated with the Xpansiv Connect platform.

            '
        name:
          type: string
          description: The registry assigned name of the project or generator.
    ChildResourceProject:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        properties:
          accountName:
            type: string
          inOutTypes:
            type: array
            items:
              type: object
              required:
              - inType
              - outType
              properties:
                inType:
                  $ref: '#/components/schemas/Ref.ResourceInType'
                outType:
                  $ref: '#/components/schemas/Ref.ResourceOutType'
          programs:
            type: array
            items:
              type: object
              title: ChildResourceProjectProgram
              required:
              - program
              - registryAssignedId
              properties:
                program:
                  $ref: '#/components/schemas/Ref.ResourceProgram'
                programName:
                  type: string
                registryAssignedId:
                  type: string
    Ref.CreditType:
      type: string
      description: The type of the credit. Ref.Data.CARBON_CREDIT_TYPE
    Ref.Currency:
      description: Ref.Data.CURRENCY
      type: string
      minLength: 3
      example: USD
  responses:
    '500':
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
    '401':
      description: Not authorized error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotAuthorizedError'
  parameters:
    AccountIdentifier:
      description: Account identifier
      name: AccountIdentifier
      example: 098B0A25
      in: path
      required: true
      schema:
        type: string
    PageSize:
      name: size
      in: query
      required: false
      schema:
        type: integer
        format: int32
    Include:
      name: include
      description: Comma-separated values from optional response fields
      in: query
      required: false
      schema:
        type: string
    PageNumber:
      name: page
      in: query
      required: false
      schema:
        type: integer
        format: int32
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT