Skip to main content
API docs by Redocly

Puro.earth Sales Channel Services (2.9.1)

Download OpenAPI specification:Download

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

Authorization

The Sales Channel Services 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.

Authentication

List API keys of the current user

Lists information on all API keys attached to the current user.

This can be used to discover unused API keys and delete those which are not in use anymore. It is strongly recommended to delete all such unused API keys, as they are sensitive secrets which are a security liability when left around lingering.

Authorizations:
AzureAdB2cbasic

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an API key for the current user

Creates a new API key for the current user. The API key will have the same rights as the user who created it.

The API key can be used to authenticate using basic-auth, where the username is the API token ID and the password is the API token passphrase.

Please store the API id-passphrase combination somewhere secure, as you will not be able to recover the passphrase.

Authorizations:
AzureAdB2cbasic

Responses

Response samples

Content type
application/json
{
  • "id": "cl0s639m50000q6xd99vv2gqs",
  • "createdOn": "2000-01-01T00:00:00.000Z",
  • "expiresAt": "2000-01-01T00:00:00.000Z",
  • "passphrase": "aad75005-ed0e-4a29-934a-9cd99bccf7bc"
}

Delete an API key

Deletes the API key with the given ID.

Authorizations:
AzureAdB2cbasic
path Parameters
apiKeyId
required
string

The ID of the API key to be deleted.

Responses

Response samples

Content type
application/json
{
  • "id": "cl0s639m50000q6xd99vv2gqs"
}

User Services

Get the sales channel binding of the currently authenticated user

Authorizations:
AzureAdB2cbasic

Responses

Response samples

Content type
application/json
{
  • "userId": "cl6aq4et20000mcxd38uh9w24",
  • "salesChannelId": "cl6aq6sxp0004snxd516by16w",
  • "roles": [
    ]
}

Get the sales channel binding of a user

Authorizations:
AzureAdB2cbasic
path Parameters
userId
required
string

The ID of the user to fetch the saleschannel roles for.

Responses

Response samples

Content type
application/json
{
  • "userId": "cl6aq4et20000mcxd38uh9w24",
  • "salesChannelId": "cl6aq6sxp0004snxd516by16w",
  • "roles": [
    ]
}

Bind a user to a sales channel

Authorizations:
AzureAdB2cbasic
path Parameters
userId
required
string

The ID of the user to create the binding for.

salesChannelId
required
string

The sales channel to bind the user to

Responses

Response samples

Content type
application/json
{
  • "userId": "cl6aq4et20000mcxd38uh9w24",
  • "salesChannelId": "cl6aq6sxp0004snxd516by16w",
  • "roles": [
    ]
}

Unbind a user from a sales channel

Authorizations:
AzureAdB2cbasic
path Parameters
userId
required
string

The ID of the user to remove the binding from.

salesChannelId
required
string

The sales channel to unbind the user from

Responses

Response samples

Content type
application/json
{
  • "userId": "cl6aq4et20000mcxd38uh9w24",
  • "salesChannelId": "cl6aq6sxp0004snxd516by16w",
  • "roles": [
    ]
}

Grant a user a role

Authorizations:
AzureAdB2cbasic
path Parameters
userId
required
string

The ID of the user to grant the role to.

salesChannelId
required
string

The sales channel to grant the user the role on.

query Parameters
role
required
string
Enum: "TRADERONBOARDERPROPOSAL_VIEWER" "TRADERONBOARDERPROPOSAL_ACCEPTER" "TRADER_ADMINISTRATOR" "TRADER_VIEWER" "ROLE_ADMINISTRATOR" "ASSET_VIEWER" "ASSET_OFFRAMPER" "TRANSACTION_ADMINISTRATOR" "PRODUCTIONFACILITY_VIEWER" "SUPPLIER_VIEWER" "EVENT_VIEWER"

Responses

Response samples

Content type
application/json
{
  • "userId": "cl6aq4et20000mcxd38uh9w24",
  • "salesChannelId": "cl6aq6sxp0004snxd516by16w",
  • "role": "TRADERONBOARDERPROPOSAL_VIEWER"
}

Remove a role from a user

Authorizations:
AzureAdB2cbasic
path Parameters
userId
required
string

The ID of the user to remove the binding from.

salesChannelId
required
string

The sales channel to unbind the user from.

query Parameters
role
required
string
Enum: "TRADERONBOARDERPROPOSAL_VIEWER" "TRADERONBOARDERPROPOSAL_ACCEPTER" "TRADER_ADMINISTRATOR" "TRADER_VIEWER" "ROLE_ADMINISTRATOR" "ASSET_VIEWER" "ASSET_OFFRAMPER" "TRANSACTION_ADMINISTRATOR" "PRODUCTIONFACILITY_VIEWER" "SUPPLIER_VIEWER" "EVENT_VIEWER"

Responses

Response samples

Content type
application/json
{
  • "userId": "cl6aq4et20000mcxd38uh9w24",
  • "salesChannelId": "cl6aq6sxp0004snxd516by16w",
  • "role": "TRADERONBOARDERPROPOSAL_VIEWER"
}

Sales Channel Services V1

List trader onboarding proposals

Authorizations:
AzureAdB2cbasic

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Accept a trader onboarding proposal

Authorizations:
AzureAdB2cbasic
path Parameters
traderOnboardingProposalId
required
string

The ID of the trader onboarding proposal to be accepted

Responses

Response samples

Content type
application/json
{
  • "id": "cl1bv7mkq00342qxd0fdt8ko7",
  • "name": "ACME Corp Oy",
  • "businessId": "FI-123123123",
  • "onboardedTraderId": "clcf0shsw026jxdhy4iweinr1",
  • "status": "ACCEPTED"
}

Reject a trader onboarding proposal

Rejects a trader onboaring proposal. A rejected trader onboarding proposal cannot be accepted until the account holder who wants to be onboarded re-submits their request to be onboarded.

Authorizations:
AzureAdB2cbasic
path Parameters
traderOnboardingProposalId
required
string

The ID of the trader onboarding proposal to be accepted

Responses

Response samples

Content type
application/json
{
  • "id": "cl1bv7mkq00342qxd0fdt8ko7",
  • "name": "ACME Corp Oy",
  • "businessId": "FI-123123123",
  • "status": "REJECTED",
  • "onboardedTraderId": "string"
}

Create a trader

Authorizations:
AzureAdB2cbasic
header Parameters
Idempotency-Key
required
string^[\w-]{1,64}$

A client-side provided unique key to allow idempotently calling this API endpoint.

Request Body schema: application/json
required
businessId
required
string

The business ID of the trader.

name
required
string

The name of the trader.

required
object

The address of the legal entity which is being registered as a trader.

Responses

Request samples

Content type
application/json
{
  • "businessId": "FI-12341234",
  • "name": "ACME Corp",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "id": "cl1bv7mkq00342qxd0fdt8ko7",
  • "businessId": "FI-12341234",
  • "name": "ACME Corp"
}

List traders

Authorizations:
AzureAdB2cbasic

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update meta-data from an existing trader

Updates a subset of the fields of an existing trader.

Patch requests follow JSON Merge Patch (RFC7396), omit fields from the request which should be left unchanged.

Authorizations:
AzureAdB2cbasic
path Parameters
traderId
required
string

The ID of the trader to be updated.

Request Body schema: application/json
required
businessId
string

The business ID of the trader.

name
string

The name of the trader.

object

Responses

Request samples

Content type
application/json
{
  • "businessId": "FI-12341234",
  • "name": "ACME Corp",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "id": "cl1bv7mkq00342qxd0fdt8ko7",
  • "businessId": "FI-12341234",
  • "name": "ACME Corp",
  • "address": {
    }
}

Read one trader

Authorizations:
AzureAdB2cbasic
path Parameters
traderId
required
string

The ID of the trader to get the details from.

Responses

Response samples

Content type
application/json
{
  • "id": "cl1bv7mkq00342qxd0fdt8ko7",
  • "businessId": "FI-12341234",
  • "name": "ACME Corp"
}

List all listable assets for a trader

Returns all listable assets for a trader. Listable assets are assets which can still be traded, retired or offramped.

Authorizations:
AzureAdB2cbasic
path Parameters
traderId
required
string

The ID of the trader to act upon.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Offramp assets

Starts the process of offramping assets owned by a trader. Invoking this endpoint will create an offramp task, which can be used to track the status of the offramp.

Use the /{taskId} endpoint to track the status of the created task.

Authorizations:
AzureAdB2cbasic
path Parameters
traderId
required
string

The ID of the trader to act upon.

header Parameters
Idempotency-Key
required
string^[\w-]{1,64}$

A client-side provided unique key to allow idempotently calling this API endpoint.

Request Body schema: application/json
required
required
Array of objects non-empty

All assets which are involved in this offramp

Array (non-empty)
start
required
string^([a-zA-Z]|\d|-)+_\d+$

The ID of the first asset included in this bundle.

end
required
string^([a-zA-Z]|\d|-)+_\d+$

The ID of the last asset included in this bundle, inclusive.

Responses

Request samples

Content type
application/json
{
  • "assets": [
    ]
}

Response samples

Content type
application/json
{
  • "taskId": "cl3y5zbkb0062wuxd52u85agi",
  • "status": "PENDING",
  • "idempotencyKey": "cl3y5zbka0036wuxdtoxdl36a",
  • "message": "Task is waiting to be picked up.",
  • "responsePayload": {
    }
}

Get status of an offramp task

Returns the status of an existing offramp task.

Authorizations:
AzureAdB2cbasic
path Parameters
traderId
required
string

The ID of the trader to find the offramp task for.

taskId
required
string

The ID of the task to fetch the status from.

Responses

Response samples

Content type
application/json
{
  • "taskId": "cl3y5zbkb0062wuxd52u85agi",
  • "status": "PENDING",
  • "idempotencyKey": "cl3y5zbka0036wuxdtoxdl36a",
  • "message": "Task is waiting to be picked up.",
  • "responsePayload": {
    }
}

Register a trade

Starts the process of registering a trade between two traders. Invoking this endpoint will create a trade task, which can be used to track the status of the trade.

Authorizations:
AzureAdB2cbasic
path Parameters
traderId
required
string

The ID of the trader who is selling the assets.

header Parameters
Idempotency-Key
required
string^[\w-]{1,64}$

A client-side provided unique key to allow idempotently calling this API endpoint.

Request Body schema: application/json
required
buyerId
required
string

The ID of the trader who is buying the assets.

required
Array of objects non-empty

All assets which are involved in this trade

currency
required
string
Enum: "EUR" "USD"

The currency of the monetary value of this trade.

Responses

Request samples

Content type
application/json
{
  • "buyerId": "string",
  • "assets": [
    ],
  • "currency": "EUR"
}

Response samples

Content type
application/json
{
  • "taskId": "cl3y5zbkb0062wuxd52u85agi",
  • "status": "PENDING",
  • "idempotencyKey": "cl3y5zbka0036wuxdtoxdl36a",
  • "message": "Task is waiting to be picked up.",
  • "responsePayload": {
    }
}

Get status of a trade task

Returns the status of an existing trade task.

Authorizations:
AzureAdB2cbasic
path Parameters
traderId
required
string

The ID of the trader to find the trade task for.

taskId
required
string

The ID of the task to fetch the status from.

Responses

Response samples

Content type
application/json
{
  • "taskId": "cl3y5zbkb0062wuxd52u85agi",
  • "status": "PENDING",
  • "idempotencyKey": "cl3y5zbka0036wuxdtoxdl36a",
  • "message": "Task is waiting to be picked up.",
  • "responsePayload": {
    }
}

Register a retirement

Starts the process of registering a retirement of assets owned by a trader. Invoking this endpoint will create a retirement task, which can be used to track the status of the retirement.

Use the /{taskId} endpoint to track the status of the created task.

Authorizations:
AzureAdB2cbasic
path Parameters
traderId
required
string

The ID of the trader who owns the assets which are to be retired.

header Parameters
Idempotency-Key
required
string^[\w-]{1,64}$

A client-side provided unique key to allow idempotently calling this API endpoint.

Request Body schema: application/json
required
beneficiaryName
required
string

The name of the beneficiary of the retirement.

beneficiaryLocation
required
string non-empty

The location of the beneficiary of the retirement.

beneficiaryType
string
Default: "END_CONSUMER"
Enum: "END_CONSUMER" "SUPPLIER"

The type of the beneficiary. END_CONSUMER is an end consumer, SUPPLIER is a CO2 removal method supplier.

beneficiaryHiddenUntil
string or null <date-time>
Default: null

The date until which the beneficiary is hidden.

consumptionCountryCode
required
string[A-Z]{2}

The code of the country in which the to-be retired certificates are consumed.

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

Type of the activity associated with the retirement.

required
object

The period during which the to-be retired assets where used.

retirementPurpose
required
string non-empty

The purpose for which the certificates are retired.

required
Array of objects non-empty

All assets which are involved in this retirement. For all bundles, either all bundles have a monetary unit-price, or none of them do.

currency
required
string or null
Enum: "EUR" "USD"

The currency of the monetary value of this trade.

Responses

Request samples

Content type
application/json
{
  • "beneficiaryName": "ACME Corp Oy",
  • "beneficiaryLocation": "Helsinki",
  • "beneficiaryType": "END_CONSUMER",
  • "beneficiaryHiddenUntil": "2022-01-01T00:00:00.000Z",
  • "consumptionCountryCode": "FI",
  • "usageType": "GENERIC_COMPENSATION",
  • "consumptionPeriod": {
    },
  • "retirementPurpose": "To compensate for flight emissions from business trips in 2022.",
  • "assets": [
    ],
  • "currency": "EUR"
}

Response samples

Content type
application/json
{
  • "taskId": "cl3y5zbkb0062wuxd52u85agi",
  • "status": "PENDING",
  • "idempotencyKey": "cl3y5zbka0036wuxdtoxdl36a",
  • "message": "Task is waiting to be picked up.",
  • "responsePayload": {
    }
}

Get status of a retirement task

Returns the status of an existing retirement task.

Authorizations:
AzureAdB2cbasic
path Parameters
taskId
required
string

The ID of the task to fetch the status from.

traderId
required
string

The ID of the trader to find the retirement task for.

Responses

Response samples

Content type
application/json
{
  • "taskId": "cl3y5zbkb0062wuxd52u85agi",
  • "status": "PENDING",
  • "idempotencyKey": "cl3y5zbka0036wuxdtoxdl36a",
  • "message": "Task is waiting to be picked up.",
  • "responsePayload": {
    }
}

List transactions

Returns all transactions for the sales channel.

Authorizations:
AzureAdB2cbasic

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List methodologies

Returns a list of all methodologies.

Authorizations:
AzureAdB2cbasic

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List credit types

Authorizations:
AzureAdB2cbasic

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Read one production facility

Authorizations:
AzureAdB2cbasic
path Parameters
productionFacilityId
required
string

The ID of the production facility.

Responses

Response samples

Content type
application/json
{
  • "id": "cl1bv7mkq00342qxd0fdt8ko7",
  • "gsrn": "643002406801000015",
  • "code": "ABC123",
  • "name": "Biochar facility",
  • "countryCode": "FI",
  • "methodologyCodes": [
    ]
}

Read one supplier

Authorizations:
AzureAdB2cbasic
path Parameters
supplierId
required
string

The ID of the supplier.

Responses

Response samples

Content type
application/json
{
  • "id": "cl1bv7mkq00342qxd0fdt8ko7",
  • "name": "Biochar facility",
  • "businessId": "FI-12341234"
}

List events

Authorizations:
AzureAdB2cbasic
query Parameters
object
object
$limit
integer >= 1

Responses

Response samples

Content type
application/json
[
  • {
    }
]