Create transactions

POST 
/transactions

Calculates carbon emission for one or more transactions. If the request contains a transaction with an unsupported classification the response still contains that item but without any values returned, except the reference which is echoed back.

Request

Header Parameters

forwarded-partner string

Partner identification in case the request is proxied by another partner

application/json

Body

required

Transaction information required to perform the calculation

transactions

object[]

required

Possible values: >= 1, <= 5000

Array [

reference TransactionReference (string)required

Possible values: non-empty and <= 100 characters

A reference to the transaction this calculation was based on (from request)

classifications

object[]

required

Array [

type stringrequired

Expresses the type of classification. Check /classifications for a list of supported types

id stringrequired

The identifier for the classification within a specific type

]

amount

object

required

Expresses a monetary amount

value numberrequired

Possible values: >= -1000000000 and <= 1000000000

currency CurrencyCode (string)required

Possible values: >= 3 characters and <= 3 characters, Value must match regular expression ^[A-Z]{3}$

Currency in ISO 4217 code format

country stringrequired

Possible values: Value must match regular expression [A-Z]{2}

The country in which the transaction took place following the ISO-3166 alpha-2 convention

date string

Possible values: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

The date when the transaction occurred in YYYY-MM-DD format

]

Responses

200

Transaction response

application/json

Schema

Schema

transactionImpacts

object[]

Array [

oneOf

TransactionCarbonFootprint

CO2e impact for a transaction

co2eEmission

object

required

Expresses the carbon foot print

total numberrequired

The total carbon footprint

socialCostOfCarbon

object

required

The transaction's social cost of carbon (SCC)

total numberrequired

The total social cost for carbon footprint

currency CurrencyCode (string)required

Possible values: >= 3 characters and <= 3 characters, Value must match regular expression ^[A-Z]{3}$

Currency in ISO 4217 code format

reference TransactionReference (string)required

Possible values: non-empty and <= 100 characters

A reference to the transaction this calculation was based on (from request)

classification

object

required

Expresses the classification with an identifier

type stringrequired

Expresses the type of classification. Check /classifications for a list of supported types

id stringrequired

The identifier for the classification within a specific type

spendingAreaId integerrequired

The spending category ID of the transaction, can be retrieved from /categories

docc stringrequired

The Doconomy Category Code used in calculating the footprint

MissingTransactionFootPrint

Expresses why a certain footprint could not be calculated

errorCode stringrequired

Possible values: [INVALID_CLASSIFICATION, CLASSIFICATION_IDENTIFIER_NOT_FOUND, INTERNAL_MAPPING_ERROR]

A technical code expressing the type of failure

errorMessage stringrequired

A more verbose explanation why the calculation of the transaction failed

reference TransactionReference (string)required

Possible values: non-empty and <= 100 characters

A reference to the transaction this calculation was based on (from request)

]

Example (from schema)

{
  "transactionImpacts": [
    {},
    {}
  ]
}

400

Bad request

application/json

Schema

Schema

errors

object[]

required

Errors

Array [

source stringrequired

Possible values: non-empty and <= 100 characters

The application name that generated this error.

reasonCode stringrequired

Possible values: non-empty and <= 100 characters

A unique constant identifying the error case encountered during request processing.

• BAD_REQUEST - Malformed request, please advice the description and details fields for more information
• FORBIDDEN - Insufficient scope to access the resource
• INTERNAL_SERVER_ERROR - Unexpected server error
• METHOD_NOT_ALLOWED - Method not allowed
• UNSUPPORTED_MEDIA_TYPE - Unsupported media type
• SERVICE_UNAVAILABLE - Service is unavailable

description stringrequired

Possible values: <= 1000 characters

Short description of the reasonCode field.

recoverable booleanrequired

Indicates whether this error will always be returned for this request, or retrying could change the outcome.

]

Example (from schema)

{
  "errors": [
    {
      "source": "string",
      "reasonCode": "string",
      "description": "string",
      "recoverable": false
    }
  ]
}

401

Unauthorized client

403

Insufficient scope for accessing this resource

application/json

Schema

Schema

errors

object[]

required

Errors

Array [

source stringrequired

Possible values: non-empty and <= 100 characters

The application name that generated this error.

reasonCode stringrequired

Possible values: non-empty and <= 100 characters

A unique constant identifying the error case encountered during request processing.

• BAD_REQUEST - Malformed request, please advice the description and details fields for more information
• FORBIDDEN - Insufficient scope to access the resource
• INTERNAL_SERVER_ERROR - Unexpected server error
• METHOD_NOT_ALLOWED - Method not allowed
• UNSUPPORTED_MEDIA_TYPE - Unsupported media type
• SERVICE_UNAVAILABLE - Service is unavailable

description stringrequired

Possible values: <= 1000 characters

Short description of the reasonCode field.

recoverable booleanrequired

Indicates whether this error will always be returned for this request, or retrying could change the outcome.

]

Example (from schema)

{
  "errors": [
    {
      "source": "string",
      "reasonCode": "string",
      "description": "string",
      "recoverable": false
    }
  ]
}

405

Method not allowed

application/json

Schema

Schema

errors

object[]

required

Errors

Array [

source stringrequired

Possible values: non-empty and <= 100 characters

The application name that generated this error.

reasonCode stringrequired

Possible values: non-empty and <= 100 characters

A unique constant identifying the error case encountered during request processing.

• BAD_REQUEST - Malformed request, please advice the description and details fields for more information
• FORBIDDEN - Insufficient scope to access the resource
• INTERNAL_SERVER_ERROR - Unexpected server error
• METHOD_NOT_ALLOWED - Method not allowed
• UNSUPPORTED_MEDIA_TYPE - Unsupported media type
• SERVICE_UNAVAILABLE - Service is unavailable

description stringrequired

Possible values: <= 1000 characters

Short description of the reasonCode field.

recoverable booleanrequired

Indicates whether this error will always be returned for this request, or retrying could change the outcome.

]

Example (from schema)

{
  "errors": [
    {
      "source": "string",
      "reasonCode": "string",
      "description": "string",
      "recoverable": false
    }
  ]
}

415

Unsupported media type

application/json

Schema

Schema

errors

object[]

required

Errors

Array [

source stringrequired

Possible values: non-empty and <= 100 characters

The application name that generated this error.

reasonCode stringrequired

Possible values: non-empty and <= 100 characters

A unique constant identifying the error case encountered during request processing.

• BAD_REQUEST - Malformed request, please advice the description and details fields for more information
• FORBIDDEN - Insufficient scope to access the resource
• INTERNAL_SERVER_ERROR - Unexpected server error
• METHOD_NOT_ALLOWED - Method not allowed
• UNSUPPORTED_MEDIA_TYPE - Unsupported media type
• SERVICE_UNAVAILABLE - Service is unavailable

description stringrequired

Possible values: <= 1000 characters

Short description of the reasonCode field.

recoverable booleanrequired

Indicates whether this error will always be returned for this request, or retrying could change the outcome.

]

Example (from schema)

{
  "errors": [
    {
      "source": "string",
      "reasonCode": "string",
      "description": "string",
      "recoverable": false
    }
  ]
}

500

Unexpected server error

application/json

Schema

Schema

errors

object[]

required

Errors

Array [

source stringrequired

Possible values: non-empty and <= 100 characters

The application name that generated this error.

reasonCode stringrequired

Possible values: non-empty and <= 100 characters

A unique constant identifying the error case encountered during request processing.

• BAD_REQUEST - Malformed request, please advice the description and details fields for more information
• FORBIDDEN - Insufficient scope to access the resource
• INTERNAL_SERVER_ERROR - Unexpected server error
• METHOD_NOT_ALLOWED - Method not allowed
• UNSUPPORTED_MEDIA_TYPE - Unsupported media type
• SERVICE_UNAVAILABLE - Service is unavailable

description stringrequired

Possible values: <= 1000 characters

Short description of the reasonCode field.

recoverable booleanrequired

Indicates whether this error will always be returned for this request, or retrying could change the outcome.

]

Example (from schema)

{
  "errors": [
    {
      "source": "string",
      "reasonCode": "string",
      "description": "string",
      "recoverable": false
    }
  ]
}

Loading...