OneTrust Carbon Management API

openapi: 3.2.0
info:
  title: ESG Program Reporting & Disclosures Carbon Management API
  version: '1.0'
  contact:
    name: OneTrust Support
    url: https://my.onetrust.com/s/contactsupport
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  description: APIs to manage emission factors and emission transactions.
servers:
- url: https://{hostname}/api/esg-management
  variables:
    hostname:
      default: hostname
      description: The OneTrust hostname such as app.onetrust.com, app-eu.onetrust.com, app-de.onetrust.com, app-uk.onetrust.com, app-apac.onetrust.com, trial.onetrust.com, or uat.onetrust.com.
tags:
- name: Carbon Management
  description: APIs to manage emission factors and emission transactions.
  externalDocs:
    description: OpenAPI 3.0.1 - Download Definition
    url: https://developer.onetrust.com/onetrust/openapi/esg-program-reporting-disclosures.json
paths:
  /v1/emission-factors:
    get:
      operationId: getAllEmissionFactorsBasicEntityDetails
      summary: Get List of Emission Factors
      description: 'Use this API to get list of emission factors.


        ### Example Request


        `GET https://{hostname}/api/esg-management/v1/emission-factors`


        `GET https://trial.onetrust.com/api/esg-management/v1/emission-factors`'
      tags:
      - Carbon Management
      x-onetrust:
        release-status: Deprecated
        spec-label: https://developer.onetrust.com/onetrust/openapi/esg-program-reporting-disclosures.json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BasicEntityDetail'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests
        '500':
          description: Internal Server Error
      deprecated: true
      security:
      - oauth2:
        - ESG_READ
  /v1/entity-types/emission-factors/entities:
    post:
      operationId: addEmissionFactor
      summary: Create Emission Factor
      description: 'Use this API to create emission factor.


        ### Example Request


        `POST https://{hostname}/api/esg-management/v1/entity-types/names/emission-factors/entities`


        `POST https://trial.onetrust.com/api/esg-management/v1/entity-types/names/emission-factors/entities`'
      tags:
      - Carbon Management
      x-onetrust:
        release-status: Deprecated
        spec-label: https://developer.onetrust.com/onetrust/openapi/esg-program-reporting-disclosures.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmissionFactorBaseEntityCreateRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityInformation'
              example:
                id: 6b0bd46b-aa40-45f3-ade3-feac017343f5
                number: 22
                name: ef2
                orgGroupId: 11909a50-593a-4caf-a27b-ff3ba3022f0b
                schemaId: null
                entityType:
                  id: 9f21745d-e4d6-414e-8b0e-7d74a7ae2408
                  name: emission-factors
                  nameKey: EmissionFactor_Key
                  seeded: true
                  moduleName: ESG Management
                  schemaName: null
                workflowAndStage: null
                entityDetail:
                  data:
                    unitOfMeasure: kg
                    intensity: 1
                    source: EPA
                    scope:
                      id: null
                      name: Scope2
                      nameKey: EmissionScope.Scope2
                    orgGroup:
                      id: 11909a50-593a-4caf-a27b-ff3ba3022f0b
                      name: new ESG sheet tenant
                attributes: {}
                auditFields:
                  createdDate: '2023-10-12T11:47:59.707284544'
                  lastUpdatedDate: '2023-10-12T11:47:59.707284544'
                  createdBy:
                    id: 74a84f6e-0f45-4338-9216-c1d3e39f2880
                    name: new ESG sheet tenant
                    email: newesgsheettenant01@g.com
                    initials: NS
                  lastModifiedBy:
                    id: 74a84f6e-0f45-4338-9216-c1d3e39f2880
                    name: new ESG sheet tenant
                    email: newesgsheettenant01@g.com
                    initials: NS
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests
        '500':
          description: Internal Server Error
      deprecated: true
      security:
      - oauth2:
        - ESG
  /v1/entity-types/emission-transactions/entities:
    post:
      operationId: addEmissionTransaction
      summary: Create Emission Transaction
      description: 'Use this API to create emission transaction.


        ### Additional Information


        * Emission Factors names and id list can be obtained using the Retrieve Emission Factors list API. Use the required id to fill the emissionFactorId field in entityDetail.


        ### Example Request


        `POST https://{hostname}/api/esg-management/v1/entity-types/names/emission-transactions/entities`


        `POST https://trial.onetrust.com/api/esg-management/v1/entity-types/names/emission-transactions/entities`'
      tags:
      - Carbon Management
      x-onetrust:
        release-status: Deprecated
        spec-label: https://developer.onetrust.com/onetrust/openapi/esg-program-reporting-disclosures.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmissionTransactionBaseEntityCreateRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityInformation'
              example:
                id: 4917494c-0af9-44b7-a9ee-346210c0b783
                number: 61
                name: transaction-1
                orgGroupId: fbba3c6e-d723-4f05-9ef8-b59f24e1c33d
                schemaId: 33b2382d-b53f-4a23-91ee-4182219f7e54
                entityType:
                  id: 1d672a2a-6279-424a-b12d-50a7346cbfd5
                  name: emission-transactions
                  nameKey: EmissionTransaction_Key
                  seeded: true
                  moduleName: ESG Management
                  schemaName: emission-transactions
                workflowAndStage: null
                entityDetail:
                  data:
                    emissionFactor:
                      id: 7e8327dc-12ec-4aa9-a419-02cd870421db
                      name: a1
                    activityUnit: 3
                    totalCalculatedEmission: 30
                    source: Manual
                    scope:
                      id: null
                      name: Scope1
                      nameKey: EmissionScope.Scope1
                    startDateOfActivity: '2023-11-16T00:00:00Z'
                    endDateOfActivity: '2023-11-17T00:00:00Z'
                    orgGroup:
                      id: fbba3c6e-d723-4f05-9ef8-b59f24e1c33d
                      name: p1.test4
                    emissionUnitOfMeasure: ims
                attributes: {}
                auditFields:
                  createdDate: '2023-11-14T06:36:32.174378137'
                  lastUpdatedDate: '2023-11-14T06:36:32.174378137'
                  createdBy:
                    id: 548b21e7-a7a5-4dfc-9608-1a8dbdcd8308
                    name: p1.test4a demo4a
                    email: p1.test.demo4@gmail.com
                    initials: PD
                  lastModifiedBy:
                    id: 548b21e7-a7a5-4dfc-9608-1a8dbdcd8308
                    name: p1.test4a demo4a
                    email: p1.test.demo4@gmail.com
                    initials: PD
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests
        '500':
          description: Internal Server Error
      deprecated: true
      security:
      - oauth2:
        - ESG
  /v1/entity-types/names/{entityTypeName}/entities/pages:
    post:
      operationId: findAllByTypeAndCriteria
      summary: Get List of Emission Details
      description: 'Use this API to get list of Emission Details by Criteria.


        ### Additional Information


        * Filtering can be added in the request body.


        ### Example Request


        `POST https://{hostname}/api/esg-management/v1/entity-types/names/{entityTypeName}/entities/pages`


        `POST https://trial.onetrust.com/api/esg-management/v1/entity-types/names/{entityTypeName}/entities/pages`'
      tags:
      - Carbon Management
      x-onetrust:
        release-status: Deprecated
        spec-label: https://developer.onetrust.com/onetrust/openapi/esg-program-reporting-disclosures.json
      parameters:
      - name: entityTypeName
        in: path
        description: The name of the entity type.
        required: true
        schema:
          type: string
          example: emission-factors
          enum:
          - emission-factors
          - emission-transactions
      - name: page
        in: query
        description: Results page you want to retrieve (0..N)
        schema:
          type: integer
          default: 0
      - name: size
        in: query
        description: Number of records per page.
        schema:
          type: integer
          default: 10
      - name: sort
        in: query
        schema:
          type: array
          items:
            type: string
            description: 'Sorting criteria in the format: property(,asc|desc)Default sort order is ascending. Multiple sort criteria are supported.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityListRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageEntityInformation'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests
        '500':
          description: Internal Server Error
      deprecated: true
      security:
      - oauth2:
        - ESG_READ
components:
  schemas:
    EntityBasicUserInformation:
      type: object
      properties:
        id:
          description: The unique identifier of the user.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        name:
          description: The full name of the user.
          type: string
          example: First Last
        email:
          description: The email address of the user.
          type: string
          example: user@gmail.com
        initials:
          description: The initials for the first and last name of the user.
          type: string
          example: FL
      example:
        id: c21319953-b4b5-4042-8cb9-b78038cc4c51
        name: Name
    AttributePredicate:
      type: object
      properties:
        field:
          description: The field name used to filter results.
          type: string
        operator:
          description: The relationship that must be met between the field and value.
          type: string
          enum:
          - EQUAL_TO
          - NOT_EQUAL_TO
          - GREATER_THAN
          - LESS_THAN
          - BETWEEN
        value:
          description: The field value used to filter results. If filtering for a range of values, this would be the start of the range and should be used in conjunction with the `toValue` parameter.
          type: array
          items:
            type: string
        toValue:
          description: The field value for the end of the range. This field should be used in conjunction with the `value` parameter.
          type: array
          items:
            type: string
      required:
      - field
    EntityListRequest:
      type: object
      properties:
        queryRequest:
          $ref: '#/components/schemas/EntityQueryRequest'
    EmissionFactorEntityDetailRequest:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/EmissionFactorCreateRequest'
    BasicEntityDetail:
      type: object
      properties:
        id:
          description: The unique identifier of the entity.
          type: string
          format: uuid
          example: c21319953-b4b5-4042-8cb9-b78038cc4c51
        name:
          description: The name of the entity.
          type: string
          example: Emission Factor-1
    AttributeQueryCriteria:
      type: object
      properties:
        filters:
          description: The fields and values used to filter results.
          type: array
          items:
            $ref: '#/components/schemas/AttributePredicate'
          uniqueItems: true
        fullText:
          description: The key terms for the search criteria.
          type: string
          maxLength: 500
          minLength: 0
    EntityRecordAuditInformation:
      type: object
      properties:
        createdDate:
          description: The date and time that the entity was last created.
          type: string
          format: date-time
        lastUpdatedDate:
          description: The date and time that the entity was last updated.
          type: string
          format: date-time
        createdBy:
          $ref: '#/components/schemas/EntityBasicUserInformation'
        lastModifiedBy:
          $ref: '#/components/schemas/EntityBasicUserInformation'
      required:
      - createdDate
    EntityQueryRequest:
      type: object
      properties:
        criteria:
          $ref: '#/components/schemas/AttributeQueryCriteria'
    EmissionTransactionBaseEntityCreateRequest:
      type: object
      properties:
        name:
          description: The name of the entity.
          type: string
          example: air travel
        organization:
          $ref: '#/components/schemas/EntityOrganizationInformation'
        entityDetail:
          $ref: '#/components/schemas/EmissionTransactionEntityDetailRequest'
        attributes:
          type: object
          example:
            textAttributeName:
            - value: Text
            optionBasedAttributeName:
            - id: f2229953-b4b5-4042-8cb9-b78038cc4c46
          additionalProperties:
            type: array
            description: The custom attributes of the entity.
            example:
              textAttributeName:
              - value: Text
              optionBasedAttributeName:
              - id: f2229953-b4b5-4042-8cb9-b78038cc4c46
            items:
              $ref: '#/components/schemas/AttributeValueInformation'
      required:
      - entityDetail
      - organization
    SortObject:
      type: object
      properties:
        empty:
          type: boolean
        sorted:
          type: boolean
        unsorted:
          type: boolean
    EmissionTransactionEntityDetailRequest:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/EmissionTransactionDataCreateRequest'
    EntityOrganizationInformation:
      type: object
      properties:
        id:
          description: The unique identifier of the organization.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        name:
          description: The name of the organization.
          type: string
          example: Business Unit
      example:
        id: f2229953-b4b5-4042-8cb9-b78038cc4c46
        name: Organization Name
      required:
      - id
    AttributeValueInformation:
      type: object
      properties:
        id:
          description: The attribute option GUID.
          type: string
          format: uuid
        value:
          description: The attribute option value.
          type: string
        valueKey:
          description: The attribute option value key for translation.
          type: string
        colorCode:
          description: The attribute option color code.
          type: string
        optionSelectionValue:
          description: The attribute option selection value.
          type: string
      example:
        textAttributeName:
        - value: Text
        optionBasedAttributeName:
        - id: f2229953-b4b5-4042-8cb9-b78038cc4c46
    EntityWorkflowInformation:
      type: object
      properties:
        id:
          description: The unique identifier of the workflow.
          type: string
          format: uuid
          example: b271c01a-89a9-41b1-8185-0a3e2bfdad84
        name:
          description: The name of the workflow.
          type: string
          example: Vendor On-Boarding Workflow
        type:
          description: The type of workflow.
          type: string
          example: Vendor
        workflowMode:
          description: This parameter indicates whether the workflow mode is null, basic, or advanced.
          type: string
          example: BASIC
          enum:
          - ADVANCED, BASIC
        stageId:
          description: The unique identifier of the workflow stage.
          type: string
          format: uuid
          example: 9fc111cb-c379-4f08-8aff-5be954c1a6e6
        stageName:
          description: The name of the workflow stage.
          type: string
          example: Start On-Boarding
      required:
      - id
      - name
      - stageId
      - stageName
      - type
    BasicEntityTypeInformation:
      type: object
      properties:
        id:
          description: The unique identifier for the entity type.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        name:
          description: The name of the entity type.
          type: string
          example: Vendor
        seeded:
          description: This parameter indicates whether the entity type is seeded or custom.
          type: boolean
          example: true
        moduleName:
          description: The name of the module where the entity exists.
          type: string
          example: CustomEntityManagement
        schemaName:
          description: The name of the schema.
          type: string
          example: vendor
      example:
        id: a2319953-b4b5-4042-8cb9-b78038cc4c46
        name: Asset
      required:
      - id
      - name
    EmissionFactorCreateRequest:
      type: object
      properties:
        unitOfMeasure:
          description: The measurement unit for the emission factor.
          type: string
          example: miles
        intensity:
          description: The intensity of the emission factor per unit of the emission transaction.
          type: number
          example: 30
        source:
          description: The source for the emission factor.
          type: string
          example: EPA
        scope:
          description: The scope associated with the emission factor.
          type: string
          enum:
          - SCOPE1
          - SCOPE2
          - SCOPE3
        category:
          description: The category for the emission factor.
          type: string
          example: Business Travel
      required:
      - intensity
      - scope
      - unitOfMeasure
    EmissionFactorBaseEntityCreateRequest:
      type: object
      properties:
        name:
          description: The name of the entity.
          type: string
          example: Air travel
        organization:
          $ref: '#/components/schemas/EntityOrganizationInformation'
        entityDetail:
          $ref: '#/components/schemas/EmissionFactorEntityDetailRequest'
        attributes:
          type: object
          example:
            textAttributeName:
            - value: Text
            optionBasedAttributeName:
            - id: f2229953-b4b5-4042-8cb9-b78038cc4c46
          additionalProperties:
            type: array
            description: The custom attributes of the entity.
            example:
              textAttributeName:
              - value: Text
              optionBasedAttributeName:
              - id: f2229953-b4b5-4042-8cb9-b78038cc4c46
            items:
              $ref: '#/components/schemas/AttributeValueInformation'
      required:
      - entityDetail
      - name
      - organization
    PageableObject:
      type: object
      properties:
        offset:
          type: integer
          format: int64
        sort:
          $ref: '#/components/schemas/SortObject'
        pageNumber:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
        paged:
          type: boolean
        unpaged:
          type: boolean
    PageEntityInformation:
      type: object
      properties:
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        content:
          items:
            $ref: '#/components/schemas/EntityInformation'
          type: array
        number:
          type: integer
          format: int32
        sort:
          $ref: '#/components/schemas/SortObject'
        numberOfElements:
          type: integer
          format: int32
        pageable:
          $ref: '#/components/schemas/PageableObject'
        last:
          type: boolean
        first:
          type: boolean
        empty:
          type: boolean
    EmissionTransactionDataCreateRequest:
      type: object
      properties:
        emissionFactorId:
          description: The unique identifier of the emission factor.
          type: string
          format: uuid
          example: 11909a50-593a-4caf-a27b-ff3ba3022f0b
        activityUnit:
          description: The number of activity units for the emission transaction.
          type: number
          example: 30
        startDateOfActivity:
          description: The activity start date for the emission transaction.
          type: string
          example: 01/20/2022
        endDateOfActivity:
          description: The activity end date for the emission transaction.
          type: string
          example: 01/23/2022
      required:
      - emissionFactorId
    EntityInformation:
      type: object
      properties:
        id:
          description: The unique identifier of the entity.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        number:
          description: The numerical order in which the entity was created.
          type: integer
          format: int64
          example: 1
        name:
          description: The name of the entity.
          type: string
          example: OneTrust
        orgGroupId:
          description: The unique identifier of the organization.
          type: string
          format: uuid
          example: d1119953-b4b5-4042-8cb9-b78038cc2c46
        schemaId:
          description: The unique identifier of the schema.
          type: string
          format: uuid
        entityType:
          $ref: '#/components/schemas/BasicEntityTypeInformation'
        workflowAndStage:
          $ref: '#/components/schemas/EntityWorkflowInformation'
        attributes:
          type: object
          example:
            textAttributeName:
            - value: Text
            optionBasedAttributeName:
            - id: f2229953-b4b5-4042-8cb9-b78038cc4c46
          additionalProperties:
            type: array
            description: The attributes of the entity.
            example:
              textAttributeName:
              - value: Text
              optionBasedAttributeName:
              - id: f2229953-b4b5-4042-8cb9-b78038cc4c46
            items:
              $ref: '#/components/schemas/AttributeValueInformation'
        auditFields:
          $ref: '#/components/schemas/EntityRecordAuditInformation'
      required:
      - entityType
      - id
      - number
      - schemaId
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://{hostname}/api/access/v1/oauth/token
          scopes:
            ESG: ESG read and write scope for external systems
            ESG_READ: ESG read scope for external systems
x-onetrust:
  spec-label: OpenAPI 3.0.1
  links:
  - ESG Program Reporting & Disclosures Knowledge Base: https://my.onetrust.com/s/topic/0TO3q000000JP7TGAW/esg-program-reporting-disclosures
  - '{''ESG Program Reporting & Disclosures Knowledge Base'': ''https://my.onetrust.com/s/topic/0TO3q000000JP7TGAW/esg-program-reporting-disclosures''}'
x-readme:
  explorer-enabled: false
  proxy-enabled: false
  metrics-enabled: false