Skip to main content
API docs by Redocly

Puro.earth MyPuro API (1.0.0)

Download OpenAPI specification:Download

Puro.earth Oy: tech-support@puro.earth URL: https://puro.earth

Authorization

The MyPuro portal API uses role-based access control (RBAC) to assign and manage rights for users. If a request is made by a user who lacks the needed authorization, the request will instead return either an HTTP 403 Forbidden or HTTP 404 Not Found response.

Not Found responses are reserved for cases where the application cannot determine whether the resource exists or whether the user is not able to interact with it. In endpoints that list multiple resources, only those the user is authorized to view will be returned.

Account Holders

List account holders

Authorizations:
API
query Parameters
limit
integer [ 1 .. 100 ]

How many items to return at one time (max 100)

offset
integer >= 0

How many items to skip

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "data": [
    ]
}

Get account holder by id

Authorizations:
API
path Parameters
accountHolderId
required
string <uuid>

The id of the account holder to retrieve

Responses

Response samples

Content type
application/json
{
  • "accountHolderId": "f4826423-21b9-4ee0-905d-311e758ee750",
  • "name": "Acme Inc.",
  • "businessId": "FI12345671",
  • "address": {
    },
  • "registeredOn": "2024-12-13T09:53:26.760Z"
}

Accounts

List accounts

Authorizations:
API
query Parameters
accountHolderId
string <uuid>

The id of the account holder

limit
integer [ 1 .. 100 ]

How many items to return at one time (max 100)

offset
integer >= 0

How many items to skip

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "data": [
    ]
}

Create a new account

Authorizations:
API
header Parameters
Idempotency-Key
required
string

A client-side provided unique key to allow idempotently calling this API endpoint. The value must match the pattern: ^[\w-]{1,64}$.

Request Body schema: application/json
required

The data to create the account with.

name
required
string [ 1 .. 100 ] characters

The name of the account

parentAccountNumber
required
string or null <uuid>

The account number of the parent, or null when the account does not have a parent.

accountHolderId
required
string <uuid>

The ID of the account holder this account is part of.

Responses

Request samples

Content type
application/json
{
  • "name": "Default Account",
  • "parentAccountNumber": "f4826423-6423-4ee0-905d-311e758ee750",
  • "accountHolderId": "f4826423-6423-4ee0-905d-311e758ee750"
}

Response samples

Content type
application/json
{
  • "accountNumber": "f4826423-6423-4ee0-905d-311e758ee750"
}

Get account by id

Authorizations:
API
path Parameters
accountNumber
required
string <uuid>

The account number of the account to retrieve

Responses

Response samples

Content type
application/json
{
  • "accountNumber": "f4826423-21b9-4ee0-905d-311e758ee750",
  • "name": "Default Account",
  • "parentAccountNumber": "1e54f53b-57cb-4f65-adb1-77b0e1e33ce2",
  • "accountHolderId": "f4826423-905d-4ee0-4ee0-311e758ee750",
  • "isActive": true
}

Updates account details

Authorizations:
API
path Parameters
accountNumber
required
string <uuid>

The account number of the account to update

Request Body schema: application/json
required

The data to update the account with.

accountName
string

The name of the account

isActive
string

Whether the account is active. Inactive accounts cannot be used for many operations, such as transferring assets.

Responses

Request samples

Content type
application/json
{
  • "accountName": "Default Account",
  • "isActive": true
}

Response samples

Content type
application/json
{
  • "accountName": "Default Account",
  • "isActive": true
}

List certificates of an account

Authorizations:
API
path Parameters
accountNumber
required
string <uuid>

The account number of the account to retrieve the balance for

query Parameters
limit
integer [ 1 .. 100 ]

How many items to return at one time (max 100)

offset
integer >= 0

How many items to skip

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "data": [
    ]
}

Production facilities

Get production facility by code

Authorizations:
API
path Parameters
productionFacilityCode
required
string

The code of the production facility to retrieve

Responses

Response samples

Content type
application/json
{
  • "productionFacilityCode": "123ABC",
  • "name": "Biochar facility",
  • "accountHolderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "methodologyCode": "C030000000",
  • "methodologyName": "Biochar",
  • "address": {
    },
  • "geographicalLocation": {
    },
  • "dateOfCommissioning": "2024-10-01",
  • "registeredOn": "2024-10-01T00:00:00Z",
  • "facilityStatus": "ACTIVE"
}

List production facilities

Authorizations:
API
query Parameters
accountHolderId
string <uuid>

The id of the account holder.

limit
integer [ 1 .. 100 ]

How many items to return at one time (max 100)

offset
integer >= 0

How many items to skip

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "data": [
    ]
}

Transactions

Get transactions by id

Authorizations:
API
path Parameters
transactionId
required
string <uuid>

The id of the transaction to retrieve

Responses

Response samples

Content type
application/json
{
  • "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "volume": 100,
  • "unitPrice": 279.99,
  • "totalPrice": "27999.00",
  • "currency": "EUR",
  • "sourceAccountNumber": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "destinationAccountNumber": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "createdOn": "2019-08-24T14:15:22Z",
  • "completedOn": "2019-08-24T14:15:22Z",
  • "type": "Issuance",
  • "state": "CREATED",
  • "bundles": [
    ],
  • "labels": [
    ],
  • "offtakeAgreementId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "retirementDetails": {
    }
}

List transactions

Authorizations:
API
query Parameters
accountHolderId
string <uuid>

The id of the account holder.

limit
integer [ 1 .. 100 ]

How many items to return at one time (max 100)

offset
integer >= 0

How many items to skip

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "data": [
    ]
}

Create transfer

Authorizations:
API
header Parameters
Idempotency-Key
required
string

A client-side provided unique key to allow idempotently calling this API endpoint. The value must match the pattern: ^[\w-]{1,64}$.

Request Body schema: application/json
required
One of
transferType
required
string
Enum: "EXTERNAL" "INTERNAL"

Is the transfer INTERNAL between the Account Holder's own accounts, or EXTERNAL transfer to another Account Holder.

sourceAccountNumber
required
string <uuid4>

The account sending the CORCs.

destinationAccountNumber
required
string <uuid4>

The account receiving the CORCs.

required
Array of objects (PostCertificateBundle)

Certificate bundles and amounts to transfer.

additionalNotes
required
string <= 1000 characters

Additional notes about the transaction.

buyersEmail
required
string\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]...

This email address will receive a summary of the information you fill in this form.

offtakeAgreementId
string
Default: null

Enter the reference number for the offtake agreement if one exists and has been reported to Puro.earth. This will help ensure that your transaction is properly tracked and aligned with the agreement details.

unitPrice
required
string <decimal> ^\d+\.\d{1,2}$

Price per unit.

currency
required
string
Enum: "EUR" "USD"

The currency for the transaction.

Responses

Request samples

Content type
application/json
Example
{
  • "transferType": "EXTERNAL",
  • "sourceAccountNumber": "a14e8d63-9a77-4cf9-8350-bc2fd4b47b7c",
  • "destinationAccountNumber": "f94a1207-4a59-4e7d-b795-7698113b126e",
  • "bundles": [
    ],
  • "additionalNotes": "Assets issued for the production period of 2022-01-01 till 2022-12-31.",
  • "buyersEmail": "john.doe@puro.earth",
  • "offtakeAgreementId": "cl16h6x6h0026brxdt3q7870l",
  • "unitPrice": "10.12",
  • "currency": "EUR"
}

Response samples

Content type
application/json
{
  • "transactionId": "3fa85f64-5717-4562-b3fc-2c123f03afa6"
}

Create retirement

Authorizations:
API
header Parameters
Idempotency-Key
required
string

A client-side provided unique key to allow idempotently calling this API endpoint. The value must match the pattern: ^[\w-]{1,64}$.

Request Body schema: application/json
required
sourceAccountNumber
required
string <uuid>

The account from where the CORCs will be retired.

offtakeAgreementId
string

Enter the reference number for the offtake agreement if one exists and has been reported to Puro.earth. This will help us help ensure that your transaction is properly tracked and aligned with the agreement details.

required
Array of objects (PostCertificateBundle)

Certificate bundles and amounts to retire.

unitPrice
required
string <decimal> ^\d+\.\d{1,2}$

Price per unit.

currency
required
string
Enum: "EUR" "USD"

The currency for the transaction.

beneficiaryName
required
string <= 150 characters

The beneficiary entity name. Examples of beneficiaries might include, but are not limited to: companies, public entities, private or public organizations. The name of the beneficiary will be visible in the public Puro Registry.

beneficiaryLocation
required
string <= 100 characters

Location where the beneficiary is registered.

beneficiaryType
required
string
Enum: "END_CONSUMER" "SUPPLIER"

Choose SUPPLIER, if you are a supplier retiring CORCs issued to you on your own behalf. Otherwise, select END_CONSUMER.

beneficiaryContactPersonEmail
required
string <email> \b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]...

Beneficiary contact person email will receive a summary of the information you have submitted here.

countryOfConsumption
required
string = 2 characters

ISO 3166-1 alpha-2 country code.

usageType
required
string
Enum: "BUNDLED_WITH_PRODUCT_OR_SERVICE" "DISCLOSURE" "GENERIC_COMPENSATION" "OTHER" "SPECIFIC_ACTIVITY_LIKE_FLIGHTS" "SUPPORT"

Usage type refers to the activity the CORCs compensate for. If the list of provided enums doesn't contain usage type relevant to you, choose OTHER.

consumptionPeriodStartDate
required
string <date>

Start date of the consumption period.

consumptionPeriodEndDate
required
string <date>

End date of the consumption period.

beneficiaryHiddenUntil
required
string or null <date>

Beneficiary hidden until.

retirementPurpose
required
string <= 1000 characters

Enter the retirement purpose e.g. “Retired on behalf of X to offset emissions resulting from activities in 2023”. This information will be visible in our public registry.

additionalNotes
string <= 1000 characters
Default: null

Additional notes about the transaction.

Responses

Request samples

Content type
application/json
{
  • "sourceAccountNumber": "a14e8d63-9a77-4cf9-8350-bc2fd4b47b7c",
  • "offtakeAgreementId": "cl16h6x6h0026brxdt3q7870l",
  • "bundles": [
    ],
  • "unitPrice": "10.12",
  • "currency": "EUR",
  • "beneficiaryName": "string",
  • "beneficiaryLocation": "string",
  • "beneficiaryType": "END_CONSUMER",
  • "beneficiaryContactPersonEmail": "john.doe@puro.earth",
  • "countryOfConsumption": "FI",
  • "usageType": "GENERIC_COMPENSATION",
  • "consumptionPeriodStartDate": "2024-01-01",
  • "consumptionPeriodEndDate": "2024-01-31",
  • "beneficiaryHiddenUntil": "2025-12-31",
  • "retirementPurpose": "string",
  • "additionalNotes": "Assets issued for the production period of 2022-01-01 till 2022-12-31."
}

Response samples

Content type
application/json
{
  • "transactionId": "3fa85f64-5717-4562-b3fc-2c123f03afa6"
}

Documents

List documents

Authorizations:
API
query Parameters
limit
integer [ 1 .. 100 ]

How many items to return at one time (max 100)

offset
integer >= 0

How many items to skip

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "data": [
    ]
}

Methodologies

List methodologies

Authorizations:
API
query Parameters
limit
integer [ 1 .. 100 ]

How many items to return at one time (max 100)

offset
integer >= 0

How many items to skip

Responses

Response samples

Content type
application/json
{}

Labels

List labels

Authorizations:
API
query Parameters
limit
integer [ 1 .. 100 ]

How many items to return at one time (max 100)

offset
integer >= 0

How many items to skip

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "data": [
    ]
}