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 Instruments 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: Instruments
paths:
  /instruments/action/search:
    post:
      operationId: searchInstruments
      parameters:
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/Include'
      summary: Instruments search
      requestBody:
        description: Instruments search endpoint
        required: true
        content:
          application/json:
            schema:
              description: Program is mandatory when EIN is not provided
              type: object
              properties:
                ein:
                  type: string
                program:
                  $ref: '#/components/schemas/Ref.Program'
                registryAssignedId:
                  type: string
                upn:
                  type: string
                id:
                  type: integer
                  format: int64
      responses:
        '200':
          description: Instruments search successfully executed
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Page'
                - type: object
                  required:
                  - content
                  properties:
                    content:
                      type: array
                      items:
                        $ref: '#/components/schemas/Instrument'
        '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'
      tags:
      - Instruments
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'
    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:
    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