openapi: 3.0.0
info:
  version: 1.0.0
  title: TIGRS Registry Client API
  description: >-

    This API is used for retrieving and retiring TIGR certificates. APIs require
    an OAuth Authentication token. To create API credentials, please reach out
    to the TIGR administrator.
  contact:
    email: tigrs@apx.com
tags:
  - name: corporateEntity
    description: Corporate Entities Operations
  - name: ledger
    description: Ledger Operations
  - name: subaccount
    description: SubAccount Operations
  - name: system
    description: System Information
paths:
  /api/corporateEntity:
    get:
      tags:
        - corporateEntity
      summary: Corporate Entities
      operationId: getCorporateEntities
      parameters:
        - name: accountIds
          in: query
          description: >-
            Account ids: if specified, limits results to the items related to
            the accounts whose ids match the provided set; otherwise, all
            results related to any authorized account will be returned
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: $filter
          in: query
          description: OData-like filter expression
          required: false
          schema:
            type: string
        - name: $count
          in: query
          description: Whether to include the count of records with the result
          required: false
          schema:
            type: boolean
        - name: $orderby
          in: query
          description: Comma-separated list of columns for sorting
          required: false
          schema:
            type: string
        - name: $skip
          in: query
          description: Number of records to skip
          required: false
          schema:
            type: integer
            format: int32
        - name: $top
          in: query
          description: Maximum number of records to return
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ODataEnvelopeOfCorporateEntities'
        '400':
          description: Invalid parameter(s)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '429':
          description: Server too busy or acceptable use policy violation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '500':
          description: An unexpected error has occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
      security:
        - JWT: []
  /api/ledger/holding:
    get:
      tags:
        - ledger
      summary: Holdings
      operationId: getHoldings
      parameters:
        - name: accountIds
          in: query
          description: >-
            Account ids: if specified, limits results to the items related to
            the accounts whose ids match the provided set; otherwise, all
            results related to any authorized account will be returned
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: vintageStart
          in: query
          description: 'Vintage start (inclusive). Example: 2024-08-01T00:00:00Z'
          required: false
          schema:
            type: string
            format: date-time
        - name: vintageEnd
          in: query
          description: 'Vintage end (exclusive). Example: 2024-08-31T00:00:00Z'
          required: false
          schema:
            type: string
            format: date-time
        - name: program
          in: query
          description: Program code
          required: false
          schema:
            type: string
        - name: $filter
          in: query
          description: OData-like filter expression
          required: false
          schema:
            type: string
        - name: $orderby
          in: query
          description: Comma-separated list of columns for sorting
          required: false
          schema:
            type: string
        - name: $skip
          in: query
          description: Number of records to skip
          required: false
          schema:
            type: integer
            format: int32
        - name: $top
          in: query
          description: Maximum number of records to return
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ODataEnvelopeWithTotalCountOfHolding'
        '400':
          description: Invalid parameter(s)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '429':
          description: Server too busy or acceptable use policy violation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '500':
          description: An unexpected error has occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
      security:
        - JWT: []
  /api/ledger/retire:
    post:
      tags:
        - ledger
      summary: Retirements
      operationId: retireUsingPOST
      parameters:
        - name: onBehalfOfAccountId
          in: query
          description: >-
            Account id for which the request is being made: defaults to the
            primary account id of the requester unless specified
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestContainerOfRetireRequest'
        description: Retire requests
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseContainerOfRetireResponse'
        '400':
          description: Invalid parameter(s)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '413':
          description: Request payload is too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '429':
          description: Server too busy or acceptable use policy violation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '500':
          description: An unexpected error has occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
      security:
        - JWT: []
  /api/subaccount/{subaccountType}:
    post:
      tags:
        - subaccount
      summary: Subaccounts
      operationId: createSubaccountsUsingPOST
      parameters:
        - name: subaccountType
          in: path
          description: Subaccount type
          required: true
          schema:
            type: string
            enum:
              - ACT
              - RET
        - name: onBehalfOfAccountId
          in: query
          description: >-
            Account id for which the request is being made: defaults to the
            primary account id of the requester unless specified
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestContainerOfSubaccountCreateRequest'
        description: Subaccount create requests
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/ResponseContainerOfSubaccountCreateResponse
        '400':
          description: Invalid parameter(s)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '413':
          description: Request payload is too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '429':
          description: Server too busy or acceptable use policy violation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '500':
          description: An unexpected error has occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
      security:
        - JWT: []
  /api/system/ping:
    get:
      tags:
        - system
      summary: Ping System
      operationId: pingUsingGET
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pong'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '429':
          description: Server too busy or acceptable use policy violation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '500':
          description: An unexpected error has occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
      security:
        - JWT: []
servers:
  - url: //tigrsregistry.apx.com:443/clientapi
components:
  securitySchemes:
    JWT:
      type: apiKey
      name: Authorization
      in: header
  schemas:
    CorporateEntities:
      type: object
      required:
        - accountId
        - corporateEntityId
        - corporateEntityName
        - corporateId
        - corporateIdType
      properties:
        accountId:
          type: integer
          format: int32
          description: The account identifier
          example: '123'
        corporateEntityId:
          type: integer
          format: int32
          description: The corporate entity id
          example: '55'
        corporateEntityName:
          type: string
          description: The corporate entity name
          example: Acme Corp.
        corporateId:
          type: string
          description: The corporate id
          example: 1234-55
        corporateIdType:
          type: string
          description: The corporate id type
          example: DUNS
      title: CorporateEntities
      description: Corporate entities information
    ErrorContainer:
      type: object
      properties:
        errors:
          type: array
          description: List of errors
          items:
            $ref: '#/components/schemas/ErrorItem'
        submissionId:
          type: string
          description: Submission identifier for issue investigation
      title: ErrorContainer
      description: Container for errors
    ErrorItem:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: The error code
        correlationId:
          type: string
          description: The correlation identifier from the input
        field:
          type: string
          description: The field in error, if applicable
        message:
          type: string
          description: The error message
        parameter:
          type: string
          description: The parameter in error, if applicable
        path:
          type: string
          description: The path to the field specifically in error, if applicable
      title: ErrorItem
      description: Describes a specific error
    Holding:
      type: object
      required:
        - accountId
        - certificateSerialNumberRange
        - certificateStatus
        - countryIso2Code
        - creditType
        - fuelTypeCode
        - fuelTypeDescription
        - quantity
        - resourceName
        - resourceProgramAssignedIdentifier
        - retirementTypeCode
        - retirementTypeDescription
        - subaccountId
        - subaccountName
        - vintageEnd
        - vintageStart
      properties:
        accountId:
          type: string
          description: The account identifier
          example: '55'
        beneficialOwner:
          type: string
          description: The beneficial owner
          example: Acme Corp.
        certificateSerialNumberRange:
          type: string
          description: The certificate serial number range
          example: TIGR-1234-GT-SM-08-2024-321-1 to 66
        certificateStatus:
          type: string
          description: 'The certificate status: see documentation for possible values'
          example: RETIRED
        countryIso2Code:
          type: string
          description: The country to which resource belongs as an ISO-2 code
          example: GT
        creditType:
          type: string
          description: 'The credit type: see documentation for possible values'
          example: TIGR
        fuelTypeCode:
          type: string
          description: 'The fuel type code: see documentation for possible values'
          example: HRR
        fuelTypeDescription:
          type: string
          description: 'The fuel type description: see documentation for possible values'
          example: Hydroelectric - Run-of-River
        quantity:
          type: number
          description: The holding quantity
          example: '55'
        resourceName:
          type: string
          description: The resource name
          example: Acme Hydro Unit 1
        resourceProgramAssignedIdentifier:
          type: string
          description: The resource identifier
          example: '1234'
        retireDate:
          type: string
          format: date-time
          description: The retire date
          example: '2024-01-24T03:01:57.82Z'
        retirementDetails:
          type: string
          description: Additional retirement details
          example: Retired for Green Energy Program
        retirementReasonCode:
          type: string
          description: 'The retirement reason code: see documentation for possible values'
          example: '7'
        retirementReasonDescription:
          type: string
          description: >-
            The retirement reason description: see documentation for possible
            values
          example: Meet Corporate Renewable Energy Goals
        retirementTypeCode:
          type: string
          description: 'The retirement type code: see documentation for possible values'
          example: OTH
        retirementTypeDescription:
          type: string
          description: >-
            The retirement type description: see documentation for possible
            values
          example: On Behalf of Corporate Retirement
        subaccountId:
          type: string
          description: The subaccount identifier
          example: '99'
        subaccountName:
          type: string
          description: The subaccount name
          example: Acme Retirements
        vintageEnd:
          type: string
          format: date-time
          description: The vintage end
          example: '2024-08-31T00:00:00Z'
        vintageStart:
          type: string
          format: date-time
          description: The vintage start
          example: '2024-08-01T00:00:00Z'
      title: Holding
      description: Holding information
    ODataEnvelopeOfCorporateEntities:
      type: object
      properties:
        '@count':
          type: integer
          format: int32
          description: The total number of results (only present if requested)
        value:
          type: array
          description: Rows of information
          items:
            $ref: '#/components/schemas/CorporateEntities'
      title: ODataEnvelopeOfCorporateEntities
      description: Container for OData-like rows of information
    ODataEnvelopeWithTotalCountOfHolding:
      type: object
      required:
        - countExceeded
        - value
      properties:
        '@count':
          type: integer
          format: int32
        countExceeded:
          type: boolean
        totalCount:
          type: integer
          format: int32
        value:
          type: array
          items:
            $ref: '#/components/schemas/Holding'
      title: ODataEnvelopeWithTotalCountOfHolding
    Pong:
      type: object
      required:
        - pong
      properties:
        pong:
          type: string
          format: date-time
          description: The current time on the server
          example: '2024-10-31T17:58:38.066Z'
      title: Pong
      description: Response indicating server health
    RequestContainerOfRetireRequest:
      type: object
      properties:
        requests:
          type: array
          description: List of requests
          items:
            $ref: '#/components/schemas/RetireRequest'
      title: RequestContainerOfRetireRequest
      description: Container for requests
    RequestContainerOfSubaccountCreateRequest:
      type: object
      properties:
        requests:
          type: array
          description: List of requests
          items:
            $ref: '#/components/schemas/SubaccountCreateRequest'
      title: RequestContainerOfSubaccountCreateRequest
      description: Container for requests
    ResponseContainerOfRetireResponse:
      type: object
      required:
        - submissionId
      properties:
        responses:
          type: array
          description: List of responses
          items:
            $ref: '#/components/schemas/RetireResponse'
        submissionId:
          type: string
          description: Submission identifier for issue investigation
      title: ResponseContainerOfRetireResponse
      description: Container for responses
    ResponseContainerOfSubaccountCreateResponse:
      type: object
      required:
        - submissionId
      properties:
        responses:
          type: array
          description: List of responses
          items:
            $ref: '#/components/schemas/SubaccountCreateResponse'
        submissionId:
          type: string
          description: Submission identifier for issue investigation
      title: ResponseContainerOfSubaccountCreateResponse
      description: Container for responses
    RetireRequest:
      type: object
      required:
        - certificateSerialNumberRange
        - quantity
        - reasonCode
        - retirementTypeCode
        - subaccountId
        - year
      properties:
        certificateSerialNumberRange:
          type: string
          description: >-
            The certificate serial number range: certificate ranges as returned
            by the holdings call, may not be combined with other ranges, even if
            contiguous
          example: TIGR-1234-GT-SM-08-2024-321-1 to 55
        correlationId:
          type: string
          description: >-
            Correlation identifier: an opaque value that will be returned in the
            responses and error messages to correlate the response or error with
            the corresponding request
          example: '1'
        details:
          type: string
          description: >-
            Additional details, may be required in some cases: see documentation
            for more information
          example: Retired for Green Energy Program
        emailNotification:
          type: string
          description: The e-mail address for notification
          example: jdoe@acmecorp.com
        onBehalfOfCorporateEntityId:
          type: integer
          format: int32
          description: >-
            On Behalf Of Corporate Entity Id: see documentation for allowed
            values
          example: '99'
        quantity:
          type: number
          description: The quantity of the transaction
          example: '55'
        reasonCode:
          type: string
          description: 'The retire reason code: see documentation for allowed values'
          example: '7'
        retirementCertificateType:
          type: string
          description: 'Retirement certificate type: see documentation for allowed values'
          example: TIGR
        retirementTypeCode:
          type: string
          description: 'The retirement type code: GRN, BBO, OTH'
          example: OTH
        subaccountId:
          type: string
          description: The subaccount identifier
          example: '99'
        year:
          type: integer
          format: int32
          description: 'The year attribute: see documentation for allowed values'
          example: '2024'
      title: RetireRequest
      description: Request to retire credits
    RetireResponse:
      type: object
      required:
        - certificateSerialNumberRange
        - quantity
        - reasonCode
        - retirementTypeCode
        - subaccountId
        - transferId
        - year
      properties:
        certificateSerialNumberRange:
          type: string
          description: >-
            The certificate serial number range: certificate ranges as returned
            by the holdings call, may not be combined with other ranges, even if
            contiguous
          example: TIGR-1234-GT-SM-08-2024-321-1 to 55
        correlationId:
          type: string
          description: >-
            Correlation identifier: an opaque value that will be returned in the
            responses and error messages to correlate the response or error with
            the corresponding request
          example: '1'
        details:
          type: string
          description: >-
            Additional details, may be required in some cases: see documentation
            for more information
          example: Retired for Green Energy Program
        emailNotification:
          type: string
          description: The e-mail address for notification
          example: jdoe@acmecorp.com
        onBehalfOfCorporateEntityId:
          type: integer
          format: int32
          description: >-
            On Behalf Of Corporate Entity Id: see documentation for allowed
            values
          example: '55'
        quantity:
          type: number
          description: The quantity of the transaction
          example: '55'
        reasonCode:
          type: string
          description: 'The retire reason code: see documentation for allowed values'
          example: '7'
        retirementCertificateType:
          type: string
          description: 'Retirement certificate type: see documentation for allowed values'
          example: TIGR
        retirementTypeCode:
          type: string
          description: 'The retirement type code: GRN, BBO, OTH'
          example: OTH
        subaccountId:
          type: string
          description: The subaccount identifier
          example: '99'
        transferId:
          type: string
          description: The transfer identifier
          example: '7654'
        year:
          type: integer
          format: int32
          description: 'The year attribute: see documentation for allowed values'
          example: '2024'
      title: RetireResponse
      description: Response to an retire request
    SubaccountCreateRequest:
      type: object
      required:
        - name
      properties:
        additionalDetails:
          type: string
          description: The subaccount additional details
          example: Acme Retirements
        alias:
          type: string
          description: The subaccount alias
          example: Acme Retirements
        correlationId:
          type: string
          description: >-
            Correlation identifier: an opaque value that will be returned in the
            responses and error messages to correlate the response or error with
            the corresponding request
          example: '1'
        name:
          type: string
          description: The subaccount name
          example: Acme Retirements
      title: SubaccountCreateRequest
      description: Request to create a subaccount
    SubaccountCreateResponse:
      type: object
      required:
        - name
        - subaccountId
      properties:
        additionalDetails:
          type: string
          description: The subaccount additional details
          example: Acme Retirements
        alias:
          type: string
          description: The subaccount alias
          example: Acme Retirements
        correlationId:
          type: string
          description: >-
            Correlation identifier: an opaque value that will be returned in the
            responses and error messages to correlate the response or error with
            the corresponding request
          example: '1'
        name:
          type: string
          description: The subaccount name
          example: Acme Retirements
        subaccountId:
          type: string
          description: The subaccount identifier
          example: '99'
      title: SubaccountCreateResponse
      description: Response to a subaccount creation request