Greenly Transactions API

openapi: 3.2.0
info:
  title: Greenly Carbon Analytics Transactions API
  version: '1.5'
  description: '# Introduction

    The Greenly Carbon Analytics API is a set of RESTful services which enable the enrichment of bank transactions with carbon footprint analytics.'
  contact:
    email: contact@greenly.earth
servers:
- url: https://api.greenly.earth/v1.5
tags:
- name: Transactions
paths:
  /transactions/calculateCarbonFootprints:
    post:
      operationId: CalculateCarbonFootprints
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/CalculateCarbonFootprintsOutput'
                - {}
        '401':
          description: Authentication Failed
        '404':
          description: User not found
        '422':
          description: Input request body does not have the right format
        '500':
          description: An unexpected error occured while processing the request
      description: Calculate the carbon footprints of the input transactions
      summary: Calculate carbon footprints
      tags:
      - Transactions
      security: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculateCarbonFootprintsArgs'
components:
  schemas:
    AlternativeOutput:
      properties:
        recommendedProviders:
          items:
            $ref: '#/components/schemas/RecommendedProviderOutput'
          type: array
          description: List of alternative providers
        ratioEstimatedReduction:
          type:
          - number
          - 'null'
          format: double
          description: 'Estimated average reduction resulting from the suggested low-carbon alternative. Hence a ratio of 0.66 means a reduction

            of 66%, i.e., that the carbon footprint is divided by 3.'
        sources:
          items:
            type: string
          type:
          - array
          - 'null'
          description: A list of url. Can be null.
        description:
          $ref: '#/components/schemas/AlternativeDescriptionTranslations'
        geographicalRestriction:
          allOf:
          - $ref: '#/components/schemas/CountryId'
          description: 'If specified, it means the alternative is valid only for the specified country.

            If null, then the alternative is valid everywhere.'
        isProviderAlternative:
          type: boolean
          description: 'boolean to indicate whether the alternative is a general advice/behaviour alternative or is related to

            a specific alternative provider.'
        id:
          type: string
          description: UUID4 unique identifier of the alternative
      required:
      - recommendedProviders
      - ratioEstimatedReduction
      - sources
      - description
      - geographicalRestriction
      - isProviderAlternative
      - id
      type: object
    CarbonFootprintOutput:
      allOf:
      - $ref: '#/components/schemas/Pick_Transaction.tagValues_'
      - properties:
          cleanedLabel:
            type: string
            description: 'Cleaned label for the transaction. If a specific provider / brand has been

              identified in the transaction label, it will be the name of this provider / brand.

              It might be the same as the input label if no cleaning operations were carried out.'
          alternatives:
            items:
              $ref: '#/components/schemas/AlternativeOutput'
            type: array
            description: 'Populated list of the low-carbon alternatives that are recommended for this particular transaction.

              Optional feature.'
          alternativeIds:
            items:
              $ref: '#/components/schemas/AlternativeId'
            type: array
            description: 'List of the ids of the low-carbon alternatives that are recommended for this particular transaction.

              Optional feature.'
          purchaseCategoryId:
            type: string
            description: 'Id of the category of the transaction (e.g. TELECOM, SUPERMARKET, AUTOBUS).

              The relevant associated information can

              be found in the purchase categories endpoint.'
          isGreen:
            type: boolean
            description: 'Boolean value to indicate whether the transaction is associated with a positive action, i.e., an action

              that has a carbon footprint that is lower than the conventional behavour. This means that the transaction

              has generated a positive amount of avoided CO2eq.'
          transactionId:
            type: string
            description: References the id of the transaction whose carbon footprint it is.
          carbonFootprintEquivalents:
            $ref: '#/components/schemas/CarbonFootprintEquivalents'
          methodology:
            allOf:
            - $ref: '#/components/schemas/Translation'
            description: 'Methodology of the carbon footprint calculation

              Optional feature.'
          carbonFootprint:
            allOf:
            - $ref: '#/components/schemas/Pick_CarbonFootprint.emissionsInKg-or-avoidedEmissionsInKg_'
            description: 'Represents the carbon footprint of a transaction.

              It can be null in the following cases:

              - The transaction could not be categorized

              - The transaction has a positive amount in euros and represents revenues

              - The transaction type is not compatible with carbon footprint analysis'
        required:
        - cleanedLabel
        - purchaseCategoryId
        - isGreen
        - transactionId
        - carbonFootprintEquivalents
        - carbonFootprint
        type: object
    Pick_Transaction.tagValues_:
      properties:
        tagValues:
          items:
            $ref: '#/components/schemas/TagValue'
          type: array
          description: Set of tag values applied to the transaction. These have an influence on carbon footprint calculation.
      required:
      - tagValues
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    RecommendedProviderOutput:
      properties:
        logoUrl:
          type:
          - string
          - 'null'
          description: Url of the provider's logo stored in svg format.
        url:
          type:
          - string
          - 'null'
          description: Url of the recommended provider.
        name:
          type: string
          description: Name of the recommended provider.
      required:
      - logoUrl
      - url
      - name
      type: object
    Translation:
      properties:
        de:
          type: string
        sv:
          type: string
        es:
          type: string
        it:
          type: string
        en:
          type: string
        fr:
          type: string
      type: object
    AlternativeDescriptionTranslations:
      $ref: '#/components/schemas/Translations'
      description: 'Very short intuitive description of the suggested low-carbon advice or provider

        (tweet format with less than 280 characters) in our multilingual format.'
    Record_Language.string_:
      properties:
        en:
          type: string
        fr:
          type: string
        es:
          type: string
        it:
          type: string
        sv:
          type: string
        de:
          type: string
      type: object
      description: Construct a type with a set of properties K of type T
    CalculateCarbonFootprintsArgs:
      properties:
        languages:
          items:
            $ref: '#/components/schemas/Language'
          type: array
          description: 'languages requested for the methodologies.

            If no language is provided we use a default language based on the countryId of the transaction.'
        transactions:
          items:
            $ref: '#/components/schemas/InputTransaction'
          type: array
          description: List of the user transactions.
        userId:
          type: string
          description: Id of the user owning the transactions.
      required:
      - transactions
      type: object
    InputTransaction:
      properties:
        countryCode:
          type: string
          description: "(Optional) A country-code in the ISO 3166-1 alpha-2 format (see list below). In the absence of a country-code\n  the default country code if 'FR'.\nAustria:\tAT\nBelgium:\tBE\nBulgaria:\tBG\nCroatia:\tHR\nCyprus:\tCY\nCzech Republic:\tCZ\nDenmark:\tDK\nEstonia:\tEE\nFinland\tFI\nFrance:\tFR\nGermany:\tDE\nGreece:\tGR\nHungary:\tHU\nIreland, Republic of (EIRE):\tIE\nItaly:\tIT\nLatvia:\tLV\nLithuania: LT\nLuxembourg:\tLU\nMalta:\tMT\nNetherlands:\tNL\nNorway: NO\nPoland:\tPL\nPortugal:\tPT\nRomania:\tRO\nSlovakia:\tSK\nSlovenia:\tSI\nSpain:\tES\nSweden:\tSE\nSwitzerland: CH\nUnited Kingdom:\tGB"
        tagValues:
          items:
            $ref: '#/components/schemas/TagValue'
          type: array
          description: '(Optional) Additional tag values to be applied to the transaction carbon footprint calculation (e.g. ORGANIC for restaurant or supermarket).

            Available tag values per purchase category can be retrieved in the purchase categories endpoint.'
        purchaseCategoryId:
          type: string
          description: '(Optional) PurchaseCategory''s id to bypass the purchase category estimated from the label. The emission coefficient of the input purchase

            category is then used to calculate the carbon footprint (possibly modified by input tagValues), instead of the predicted one.

            The possible purchaseCategory''s ids can be obtained using the purchaseCategories endpoint.


            It is also possible to input a higher level, less precise purchase category (so-called parentPurchase category). The possible parent purchase

            categories are :

            - ''TRANSPORT''

            - ''FOOD''

            - ''SHOPPING''

            - ''SERVICES''

            - ''HOUSING''


            The mapping between the purchase categories and the parent purchase categories can be also found in the purchaseCategories endpoint.'
        mccCode:
          type: string
          description: (Optional) MCC Code (following ISO 18245) which serves as fallback in case the categorization based on the label failed.
        amount:
          type: number
          format: double
          description: 'Amount of the transaction.

            Amount is positive for revenues and negative for purchases.'
        type:
          $ref: '#/components/schemas/TransactionType'
          description: 'The type of the transaction.

            Only the types POINT_OF_SALE, CASH, TRANSFER, DIRECT_DEBIT, DEBIT lead the transaction to be analysed for carbon footprints.'
        label:
          type: string
          description: Transaction raw label.
        amountInEur:
          type: number
          format: double
          description: 'Amount in euros of the transaction.

            Amount is positive for revenues and negative for purchases.'
        id:
          type: string
          description: 'Id of the transaction.

            The transaction will be referenced with this id in

            linked ouputs (such as carbon footprint objects)'
      required:
      - type
      - label
      - id
      type: object
      description: 'Represents a transaction which can be either a bank transaction

        or a cash transaction'
    Opaque_AlternativeId.string_:
      allOf:
      - type: string
      - properties:
          __TYPE__:
            type: string
            enum:
            - AlternativeId
        required:
        - __TYPE__
        type: object
    Translations:
      $ref: '#/components/schemas/Record_Language.string_'
    Pick_CarbonFootprint.emissionsInKg-or-avoidedEmissionsInKg_:
      properties:
        emissionsInKg:
          type: number
          format: double
          description: Emissions generated in kg of CO2 equivalent (all greenhouse gas are converted to CO2).
        avoidedEmissionsInKg:
          type: number
          format: double
          description: 'Emissions avoided in kg of CO2 equivalent (all greenhouse gas are converted to CO2).

            Emissions avoided are calculated in regard to a reference situation that can be found

            in the methodology (e.g. carsharing vs driving solo in your car)'
      required:
      - emissionsInKg
      - avoidedEmissionsInKg
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    Language:
      enum:
      - en
      - fr
      - es
      - it
      - sv
      - de
      type: string
    CalculateCarbonFootprintsOutput:
      items:
        $ref: '#/components/schemas/CarbonFootprintOutput'
      type: array
    CarbonFootprintEquivalents:
      properties:
        avoidedEmissionsInKgEquivalent:
          allOf:
          - $ref: '#/components/schemas/Translation'
          description: intuitive equivalent for the avoided CO2e emissions
        emissionsInKgEquivalent:
          allOf:
          - $ref: '#/components/schemas/Translation'
          description: intuitive equivalent for the emitted CO2e emissions
      required:
      - avoidedEmissionsInKgEquivalent
      - emissionsInKgEquivalent
      type: object
      description: Intuitive illustration of the calculated carbon footprint in terms of day to day actions and objects
    AlternativeId:
      $ref: '#/components/schemas/Opaque_AlternativeId.string_'
    CountryId:
      enum:
      - GB
      - FR
      - ES
      - IT
      - SE
      - DE
      type: string
    TagValue:
      properties:
        value:
          anyOf:
          - type: string
          - type: number
            format: double
          - type: boolean
        tagId:
          type: string
      required:
      - value
      - tagId
      type: object
    TransactionType:
      description: 'The input type is type of the bank transaction and can take any of the following values:

        * CREDIT: Default type when it is not possible to determine the type of a revenue entry.

        * DEBIT: Default type when it is not possible to determine the type of a disbursement of money.

        * DINTEREST: Interest on a bank account.

        * DIVIDEND: Payment of a company to its shareholders.

        * BANK_FEE: Fees on a bank account.

        * DEPOSIT: Deposit of money in an agency.

        * ATM: Withdrawing money from an ATM.

        * POINT_OF_SALE: Payment with a credit card.

        * CREDIT_CARD_PAYMENT: Month-end debit on a deferred card.

        * INTERNAL_TRANSFER: Transfer of money between two bank accounts of the same customer.

        * TRANSFER: Transfer of money between two bank accounts of two different customers.

        * CHECK: Transaction made by check.

        * CASH: Transaction carried out using a physical currency (notes and coins).

        * DIRECT_DEPOSIT: Deposit of money made by a payer directly into the payee''s bank account.

        * DIRECT_DEBIT: Transaction in which one person (or company) withdraws funds from another person''s bank account.

        * OTHER: When a transaction does not correspond to any of these types.


        Only the types POINT_OF_SALE, TRANSFER, DIRECT_DEBIT, DEBIT leads the transaction to be analyzed for carbon footprint.'
      enum:
      - CREDIT
      - DEBIT
      - INTEREST
      - DIVIDEND
      - BANK_FEE
      - DEPOSIT
      - ATM
      - POINT_OF_SALE
      - CREDIT_CARD_PAYMENT
      - INTERNAL_TRANSFER
      - TRANSFER
      - CHECK
      - CASH
      - DIRECT_DEPOSIT
      - DIRECT_DEBIT
      - OTHER
      type: string
  securitySchemes:
    api_key:
      type: apiKey
      name: api-key
      in: header