Endpoints available for ICR App installation and Organization access tokens

Your ICR App can make requests to the following REST endpoints with an installation access token.

Who can use these endpoints

You can use an installation access token to access these endpoints using your ICR App. For more information, see "Authenticating as an ICR App installation."

Organization warehouse

The organization warehouse is where an organization can deposit their credits and give apps access to the warehouse inventory where they can transfer them without asking for permission to do so each time.

But to move credits from the warehouse they first need to be put into the reservation queue, where they are reserved for the app that put them in the queue. This is so that the app can verify off platform data / actions before finalizing a transfer / retirement action. This can be very handy for marketplaces that do not wish to hold the credits themselves and instead use the warehouse system to reserve and transfer the credits when an actual buyer / retiree has been found.

list all credits in the warehouse inventory

Get warehouse inventory

This endpoint returns a paginated list of the organization's warehouse inventory.

GEThttps://api.carbonregistry.com/organizations/{id}/warehouse/inventory

Path parameters

id*string

Header parameters

Response

200

Body

application/json

credits*array of ApiCreditDto (object)

The credits of the organization

organizationId*string

The ID of the organization that owns the warehouse

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/warehouse/inventory', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "credits": [
    {
      "id": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1",
      "inventoryId": "d449c665-3100-40c6-91ad-9d3f0a9fd343",
      "organizationId": "1b0e4f37-59ca-489a-8a23-ee3152812cb8",
      "project": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "fullName": "Project 1",
        "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "num": "713"
      },
      "serialization": "ICR-ISL-354-78040-14-R-0-2021",
      "amount": 7,
      "type": "exPost"
    }
  ],
  "organizationId": "123e4567-e89b-12d3-a456-426614174000"
}

This returns a list of all the credits in the organization's warehouse. Ids for the projects that issued those credits are also in place so using this endpoint in conjunction with the projects or project endpoints is handy.

Callable by any access token with permissions "organization_warehouse:read".

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Second Tab

inventory reservations

Get warehouse reservations

This endpoint returns a paginated list of ALL of the organization's warehouse reservations. Both active, expired and finished.

GEThttps://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations

Path parameters

limit*number

The amount of items to return

page*number

The page to return

id*string

The organization's id

Header parameters

Response

200

Body

application/json

pagination*ApiPaginationDto (object)

reservations*array of ApiReservationDto (object)

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "pagination": {
    "total": 100,
    "currentPage": 1,
    "pageCount": 10,
    "nextPage": 2,
    "prevPage": 0
  },
  "reservations": [
    {
      "id": "d449c665-3100-40c6-91ad-9d3f0a9fd343",
      "creditId": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1",
      "serialization": "ICR-ISL-354-78040-14-R-0-2021",
      "amount": 10,
      "createdAt": "2022-01-01T00:00:00Z",
      "state": "pending",
      "retirementId": "1",
      "updatedAt": "2022-01-01T00:00:00Z",
      "tokenId": "123e4567-e89b-12d3-a456-426614174000",
      "tokenAddress": "0x123456789abcdef",
      "type": "exPost",
      "reservedToDate": "2022-01-01T00:00:00Z",
      "isComplete": true,
      "project": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "fullName": "Project 1",
        "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "num": "713"
      },
      "reserver": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Reserver 1"
      }
    }
  ]
}

Returns a paginated list of all reservations, and the state of those reservations, made against the organization's warehouse.

Callable by any access token with permissions "organization_warehouse:read".

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory/reservations' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

reserve credits

Reserve credits from warehouse

This endpoint reserves credits from the organization warehouse. They are reserved for 10 minutes. In the meantime the reserver can be sure that the credits are available for them. This is especially useful for marketplaces that don't want the extra complexity of custody-ing user's credits.

POSThttps://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations

Path parameters

id*string

Header parameters

Body

application/json

amount*number

The amount of credits to reserve

creditId*string

The id of the credit to reserve

Response

200

Body

application/json

id*string

The unique identifier of the reservation, used to finish / cancel it

creditId*string

The unique identifier of the credit

serialization*string

The serialization of the reservation

amount*number

The amount reserved

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "amount": 10,
      "creditId": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1"
    }),
});
const data = await response.json();

Response

{
  "id": "d449c665-3100-40c6-91ad-9d3f0a9fd343",
  "creditId": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1",
  "serialization": "ICR-ISL-354-78040-14-R-0-2021",
  "amount": 10
}

Reserving credits from a warehouse for later transfer. They are reserved for up to 10 minutes before they are moved back into the warehouse.

Callable by any access token with permissions "organization_warehouse:write".

cURL

curl -X 'POST' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory/reservations' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 10,
  "creditId": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1"
}'

Typescript

specific reservation

Get warehouse reservation

This endpoint returns a specific warehouse reservation. It can be used to check if a reservation is still active or not.

GEThttps://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations/{reservationId}

Path parameters

id*string

The organization's id

reservationId*string

The reservation id

Header parameters

Response

200

Body

application/json

id*string

The unique identifier of the reservation, used to finish / cancel it

creditId*string

The unique identifier of the credit

serialization*string

The serialization of the reservation

amount*number

The amount reserved

createdAt*string (date-time)

The creation date of the reservation

updatedAt*string (date-time)

The update date of the reservation

tokenId*string

The token ID of the reservation

tokenAddress*string

The token address of the reservation

type*enum

The type of the reservation

exPostexAnte

reservedToDate*string (date-time)

The reserved to date of the reservation

isComplete*boolean

The completion status of the reservation

project*all of

The project of the reservation

reserver*all of

The reserver of the reservation

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations/{reservationId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "id": "d449c665-3100-40c6-91ad-9d3f0a9fd343",
  "creditId": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1",
  "serialization": "ICR-ISL-354-78040-14-R-0-2021",
  "amount": 10,
  "createdAt": "2022-01-01T00:00:00Z",
  "updatedAt": "2022-01-01T00:00:00Z",
  "tokenId": "123e4567-e89b-12d3-a456-426614174000",
  "tokenAddress": "0x123456789abcdef",
  "type": "exPost",
  "reservedToDate": "2022-01-01T00:00:00Z",
  "isComplete": true,
  "project": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "fullName": "Project 1",
    "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
    "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e"
  },
  "reserver": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Reserver 1"
  }
}

Gets a specific reservation made.

Callable by any access token with permissions "organization_warehouse:read".

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory/reservations/{RESERVATION_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

cancel specific reservation

Cancel warehouse reservation

This endpoint cancels a specific warehouse reservation. If the reservation is active the credits will be immediately made available in the organization's warehouse.

DELETEhttps://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations/{reservationId}

Path parameters

id*string

reservationId*string

Header parameters

Response

200

Body

application/json

id*string

The unique identifier of the reservation, used to finish / cancel it

creditId*string

The unique identifier of the credit

serialization*string

The serialization of the reservation

amount*number

The amount reserved

createdAt*string (date-time)

The creation date of the reservation

updatedAt*string (date-time)

The update date of the reservation

tokenId*string

The token ID of the reservation

tokenAddress*string

The token address of the reservation

type*enum

The type of the reservation

exPostexAnte

reservedToDate*string (date-time)

The reserved to date of the reservation

isComplete*boolean

The completion status of the reservation

project*all of

The project of the reservation

reserver*all of

The reserver of the reservation

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations/{reservationId}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

{
  "id": "d449c665-3100-40c6-91ad-9d3f0a9fd343",
  "creditId": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1",
  "serialization": "ICR-ISL-354-78040-14-R-0-2021",
  "amount": 10,
  "createdAt": "2022-01-01T00:00:00Z",
  "updatedAt": "2022-01-01T00:00:00Z",
  "tokenId": "123e4567-e89b-12d3-a456-426614174000",
  "tokenAddress": "0x123456789abcdef",
  "type": "exPost",
  "reservedToDate": "2022-01-01T00:00:00Z",
  "isComplete": true,
  "project": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "fullName": "Project 1",
    "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
    "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e"
  },
  "reserver": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Reserver 1"
  }
}

Cancels an outstanding reservation your app made.

Callable by any access token with permissions "organization_warehouse:write".

cURL

curl -X 'DELETE' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory/reservations/{RESERVATION_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

finish outstanding reservation

Finish warehouse reservation

This endpoint finishes a specific warehouse reservation. This moves the credits out of the organization's warehouse and into the receiver's wallet, either as retired credits or the credits themselves.

POSThttps://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations/{reservationId}/{action}

Path parameters

id*string

The organization's id

reservationId*string

The reservation id

action*enum

The action to take

retiretransfertransfer_retire

Header parameters

Body

application/json

priceInfoall of

Price information for the transfer. If the transfer / retirement is caused by a purchase, this is required.

receiverIdstring

The id of organization that will be receiving the credits

receiverAddressstring

The wallet address that will be receiving the credits

transferCommentstring

Comment for the transfer

retirementDataall of

Retirement data - only required if action is transfer_retire or retire

Response

200

Body

application/json

boolean

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations/{reservationId}/{action}', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

false

This can only be called withing 10minutes from the creation of the reservation.

Callable by any access token with permissions "organization_warehouse:write".

cURL

curl -X 'POST' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory/reservations/{RESERVATION_ID}/{ACTION}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16' \
  -H 'Content-Type: application/json' \
  -d '{
  "receiverId": "123e4567-e89b-12d3-a456-426614174000",
  "receiverAddress": "0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1",
  "transferComment": "This is a comment",
  "retirementData": {
    "reason": "Retirement reason",
    "beneficiaryName": "John Doe",
    "comment": "This is a comment"
  }
}'

Typescript

Organization info

Metadata for organization.

organization info

Get an organization

This endpoint returns an organization

GEThttps://api.carbonregistry.com/organizations/{id}

Path parameters

id*string

Header parameters

Response

200

Body

application/json

createdAt*string (date-time)

The creation date of the organization

updatedAt*string (date-time)

The update date of the organization

fullName*string

The full name of the organization

countryCode*string

The ISO 3166-1 alpha-2 country code of the organization

citystring

The city of the organization

zipstring

The zip code of the organization

physicalAddressstring

The physical address of the organization

registrationNumberstring

The registration number of the organization

websitestring

The website of the organization

logo*string

The logo of the organization

id*string

The ID of the organization

organizationIndustriesall of

The industries of the organization

type*enum

The type of the organization

projectProponentprojectDevelopermarketParticipantothervalidationBody

isPublic*boolean

The public status of the organization

url*string

The api URL of the organization

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "createdAt": "2022-01-01T00:00:00Z",
  "updatedAt": "2022-01-01T00:00:00Z",
  "fullName": "Organization 1",
  "countryCode": "US",
  "city": "New York",
  "zip": "10001",
  "physicalAddress": "123 Main St",
  "registrationNumber": "123456",
  "website": "http://example.com",
  "logo": "logo.png",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationIndustries": {
    "code": "IND1",
    "name": "Industry 1"
  },
  "type": "projectProponent",
  "isPublic": true,
  "url": "https://api.carbonregistry.com/app/organizations/123e4567-e89b-12d3-a456-426614174000"
}

Gets base information on a specific organization.

Callable by any access token with permissions "organization_info:read".

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

organization addresses

Get an organization's public evm addresses

This endpoint returns an organization's public evm addresses

GEThttps://api.carbonregistry.com/organizations/{id}/addresses

Path parameters

id*string

Header parameters

Response

200

Body

application/json

createdAt*string (date-time)

The creation date of the organization

updatedAt*string (date-time)

The update date of the organization

fullName*string

The full name of the organization

countryCode*string

The ISO 3166-1 alpha-2 country code of the organization

citystring

The city of the organization

zipstring

The zip code of the organization

physicalAddressstring

The physical address of the organization

registrationNumberstring

The registration number of the organization

websitestring

The website of the organization

logo*string

The logo of the organization

id*string

The ID of the organization

organizationIndustriesall of

The industries of the organization

type*enum

The type of the organization

projectProponentprojectDevelopermarketParticipantothervalidationBody

isPublic*boolean

The public status of the organization

url*string

The api URL of the organization

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/addresses', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "createdAt": "2022-01-01T00:00:00Z",
  "updatedAt": "2022-01-01T00:00:00Z",
  "fullName": "Organization 1",
  "countryCode": "US",
  "city": "New York",
  "zip": "10001",
  "physicalAddress": "123 Main St",
  "registrationNumber": "123456",
  "website": "http://example.com",
  "logo": "logo.png",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationIndustries": {
    "code": "IND1",
    "name": "Industry 1"
  },
  "type": "projectProponent",
  "isPublic": true,
  "url": "https://api.carbonregistry.com/app/organizations/123e4567-e89b-12d3-a456-426614174000"
}

Gets the public evm addresses of an organization. Mainly used for getting addresses to deposit credits into.

Callable by any access token with permissions "organization_info:read".

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/addresses' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

organization stakeholders

Get organization members

This endpoint returns a organization members / stakeholders

GEThttps://api.carbonregistry.com/organizations/{id}/members

Path parameters

id*string

Header parameters

Response

200

Body

application/json

isStakeAccepted*boolean

Whether the stakeholder has accepted the stake or not

organizationId*string

The ID of the organization

permissions*array of enum

The permissions of the stakeholder

roles*array of string

The roles of the stakeholder

createdAt*string (date-time)

The date and time the stakeholder was created

updatedAt*string (date-time)

The date and time the stakeholder was last updated

user*all of

The user associated with the stakeholder

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/members', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

[
  {
    "isStakeAccepted": true,
    "organizationId": "123e4567-e89b-12d3-a456-426614174000",
    "permissions": [
      "VIEW",
      "WRITE",
      "ADMIN"
    ],
    "roles": [
      {}
    ],
    "createdAt": "2022-01-01T00:00:00.000Z",
    "updatedAt": "2022-01-01T00:00:00.000Z",
    "user": {
      "email": "[e-mail]",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "profiles": {
        "countryCode": "US",
        "fullName": "John Doe",
        "profilePicture": "https://example.com/profile.jpg",
        "createdAt": "2022-01-01T00:00:00.000Z",
        "updatedAt": "2022-01-01T00:00:00.000Z",
        "roles": "user",
        "gender": "male",
        "phoneNumber": "[phone]"
      }
    }
  }
]

Gets the stakeholders of an organization.

Callable by any access token with permissions "organization_members:read".

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/members' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

Organization retirements

For getting information on retirements made / held by organizations.

list organization retirements

Get organization retirements

This endpoint returns a paginated list of the organization's retirements

GEThttps://api.carbonregistry.com/organizations/{id}/retirements

Path parameters

limit*number

The amount of items to return

page*number

The page to return

id*string

The organization's Id

Header parameters

Response

200

Body

application/json

pagination*ApiPaginationDto (object)

retirements*array of ApiRetirementDto (object)

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/retirements', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "pagination": {
    "total": 100,
    "currentPage": 1,
    "pageCount": 10,
    "nextPage": 2,
    "prevPage": 0
  },
  "retirements": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "reason": "Reached retirement age",
      "comment": "Congratulations on your retirement!",
      "beneficiary": "John Doe",
      "organizationId": "123e4567-e89b-12d3-a456-426614174000",
      "serialization": "ICR-ISL-354-78040-14-R-0-2021",
      "vintage": "2020",
      "amount": 1000,
      "project": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "fullName": "Project 1",
        "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "num": "713"
      }
    }
  ]
}

Gets a paginated list of all retirements made by an organization.

Callable by any access token with permissions "organization_info:read".

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/retirements' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

specific retirement made by organization

Get organization retirement

This endpoint returns a specific organization's retirement

GEThttps://api.carbonregistry.com/organizations/{id}/retirements/{retirementId}

Path parameters

id*string

retirementId*string

Header parameters

Response

200

Body

application/json

id*string

The ID of the retirement

reasonstring

The reason for the retirement

commentstring

A comment about the retirement

beneficiarystring

The name of the retiree

organizationId*string

The ID of the organization associated with the retirement

serializationstring

The serialization of the carbon credits associated with the retirement

vintagestring

The vintage year of the carbon credits associated with the retirement

amount*number

The amount of the retirement

project*all of

The project associated with the carbon credits

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/retirements/{retirementId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "reason": "Reached retirement age",
  "comment": "Congratulations on your retirement!",
  "beneficiary": "John Doe",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "serialization": "ICR-ISL-354-78040-14-R-0-2021",
  "vintage": "2020",
  "amount": 1000,
  "project": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "fullName": "Project 1",
    "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
    "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
    "num": "713"
  }
}

Gets data from a specific retirement made by an organization.

Callable by any access token with permissions "organization_info:read".

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/retirements/{RETIREMENT_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

retirement pdf

Get organization retirement pdf

This endpoint returns a specific organization's retirement as a pdf

GEThttps://api.carbonregistry.com/organizations/{id}/retirements/{retirementId}/pdf

Path parameters

id*string

retirementId*string

Header parameters

Response

200

File content

Body

application/octet-stream

any

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/retirements/{retirementId}/pdf', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Downloads the official retirement pdf.

Callable by any access token with permissions "organization_info:read".

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/retirements/{RETIREMENT_ID}/pdf' \
  -H 'accept: application/octet-stream' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

Organization inventory

This is the main inventory of an organization. Currently only "read" and "read and request" access are available for the inventory. The "read and request" access gives an app the permission to make transfer / retirement requests toward the credits in the organization's inventory.

organization's inventory

Get organization inventory

This endpoint returns a list of the organization's inventory

GEThttps://api.carbonregistry.com/organizations/{id}/inventory

Path parameters

id*string

Query parameters

Header parameters

Response

200

Body

application/json

credits*array of ApiInventoryCreditDto (object)

organizationId*string

The ID of the organization

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/inventory', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "credits": [
    {
      "organizationId": "123e4567-e89b-12d3-a456-426614174000",
      "id": "exPost-2-0x1234567890abcdef",
      "tokenId": "abcdef",
      "tokenAddress": "0x1234567890abcdef",
      "project": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "fullName": "Project 1",
        "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "num": "713"
      },
      "serialization": "ICR-ISL-354-78040-14-R-0-2021",
      "vintage": "2020",
      "supply": 1000,
      "unit": "tonne",
      "amount": 100,
      "type": "exAnte"
    }
  ],
  "organizationId": "123e4567-e89b-12d3-a456-426614174000"
}

This returns all the credits in an organization's inventory.

Callable by any access token with permissions "organization_inventory:read".

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/inventory' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

inventory requests

Get organization inventory requests

This endpoint returns a paginated list of the organization's inventory requests

GEThttps://api.carbonregistry.com/organizations/{id}/inventory/requests

Path parameters

limit*number

The amount of items to return

page*number

The page to return

id*string

The organization's Id

states*array of enum

Header parameters

Response

200

Body

application/json

pagination*ApiPaginationDto (object)

creditRequests*array of ApiCreditRequestDto (object)

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/inventory/requests', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "pagination": {
    "total": 100,
    "currentPage": 1,
    "pageCount": 10,
    "nextPage": 2,
    "prevPage": 0
  },
  "creditRequests": [
    {
      "action": "transfer",
      "type": "exPost",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "toAddress": "0x1234567890abcdef",
      "createdAt": "2022-01-01T00:00:00Z",
      "updatedAt": "2022-01-01T00:00:00Z",
      "tokenId": "123e4567-e89b-12d3-a456-426614174000",
      "tokenAddress": "0x1234567890abcdef",
      "creditId": "exPost-2-0x1234567890abcdef",
      "serialization": "serialization",
      "vintage": "2020",
      "amount": 1000,
      "fromOrganizationId": "123e4567-e89b-12d3-a456-426614174000",
      "toOrganizationId": "123e4567-e89b-12d3-a456-426614174000",
      "project": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "fullName": "Project 1",
        "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "num": "713"
      },
      "txId": "0x1234567890abcdef",
      "state": "Accepted",
      "retirementReason": "reason",
      "retirementComment": "comment",
      "beneficiaryName": "John Doe"
    }
  ]
}

A paginated list of all requests made toward the credits in this particular organization's inventory.

Callable by any access token with permissions "organization_inventory:read".

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/inventory/requests' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

specific inventory request

Get organization inventory request

This endpoint returns a specific organization's inventory request

GEThttps://api.carbonregistry.com/organizations/{id}/inventory/requests/{requestId}

Path parameters

id*string

requestId*string

Header parameters

Response

200

Body

application/json

action*enum

Action of the credit request

transferretiretransfer_retirecancel

type*enum

Type of the credit request

exPostexAnte

id*string

ID of the credit request

toAddressstring

Address of the recipient of the credit request

createdAt*string (date-time)

Timestamp of when the credit request was created

updatedAt*string (date-time)

Timestamp of when the credit request was last updated

tokenId*string

ID of the token associated with the credit request

tokenAddress*string

Address of the token associated with the credit request

creditId*string

ID of the credit associated with the credit request

serialization*string

Serialization of the credit request

vintage*string

The vintage year of the credit

amount*number

Amount of the credit request

fromOrganizationId*string

ID of the organization sending the credit request

toOrganizationIdstring

ID of the organization receiving the credit request

project*all of

Project information associated with the credit request

txIdstring

ID of the transaction associated with the credit request

state*enum

State of the credit request

AcceptedPendingRejected

retirementReasonstring

Reason for retirement of the credit request

retirementCommentstring

Comment for retirement of the credit request

beneficiaryNamestring

Name of the beneficiary of the credit request

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/inventory/requests/{requestId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "action": "transfer",
  "type": "exPost",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "toAddress": "0x1234567890abcdef",
  "createdAt": "2022-01-01T00:00:00Z",
  "updatedAt": "2022-01-01T00:00:00Z",
  "tokenId": "123e4567-e89b-12d3-a456-426614174000",
  "tokenAddress": "0x1234567890abcdef",
  "creditId": "exPost-2-0x1234567890abcdef",
  "serialization": "serialization",
  "vintage": "2020",
  "amount": 1000,
  "fromOrganizationId": "123e4567-e89b-12d3-a456-426614174000",
  "toOrganizationId": "123e4567-e89b-12d3-a456-426614174000",
  "project": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "fullName": "Project 1",
    "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
    "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
    "num": "713"
  },
  "txId": "0x1234567890abcdef",
  "state": "Accepted",
  "retirementReason": "reason",
  "retirementComment": "comment",
  "beneficiaryName": "John Doe"
}

Gets a specific inventory request.

Callable by any access token with permissions "organization_inventory:read".

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/inventory/requests/{REQUEST_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

create an inventory request

Request movements of credits in inventory

This endpoint requests a specific action on credits in the organization's inventory

POSThttps://api.carbonregistry.com/organizations/{id}/inventory/requests/{action}

Path parameters

action*enum

The action to perform on the token credit

transferretiretransfer_retirecancel

id*string

The ID of the organization

Header parameters

Body

application/json

creditId*string

The ID of the token credit

amount*number

The amount of the token credit

toOrganizationIdstring

The ID of the organization receiving the token credit - if not provided, toAddress must be provided

toAddressstring

The address of the organization receiving the token credit - if not provided, toOrganizationId must be provided

retirementDataall of

The retirement data associated with the token credit - only required for retirements

Response

200

Body

application/json

action*enum

Action of the credit request

transferretiretransfer_retirecancel

type*enum

Type of the credit request

exPostexAnte

id*string

ID of the credit request

toAddressstring

Address of the recipient of the credit request

createdAt*string (date-time)

Timestamp of when the credit request was created

updatedAt*string (date-time)

Timestamp of when the credit request was last updated

tokenId*string

ID of the token associated with the credit request

tokenAddress*string

Address of the token associated with the credit request

creditId*string

ID of the credit associated with the credit request

serialization*string

Serialization of the credit request

amount*number

Amount of the credit request

fromOrganizationId*string

ID of the organization sending the credit request

toOrganizationIdstring

ID of the organization receiving the credit request

project*all of

Project information associated with the credit request

txIdstring

ID of the transaction associated with the credit request

state*enum

State of the credit request

AcceptedPendingRejected

retirementReasonstring

Reason for retirement of the credit request

retirementCommentstring

Comment for retirement of the credit request

beneficiaryNamestring

Name of the beneficiary of the credit request

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/inventory/requests/{action}', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "creditId": "exPost-2-0x1234567890abcdef",
      "amount": 100
    }),
});
const data = await response.json();

Response

{
  "action": "transfer",
  "type": "exPost",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "toAddress": "0x1234567890abcdef",
  "createdAt": "2022-01-01T00:00:00Z",
  "updatedAt": "2022-01-01T00:00:00Z",
  "tokenId": "123e4567-e89b-12d3-a456-426614174000",
  "tokenAddress": "0x1234567890abcdef",
  "creditId": "exPost-2-0x1234567890abcdef",
  "serialization": "serialization",
  "amount": 1000,
  "fromOrganizationId": "123e4567-e89b-12d3-a456-426614174000",
  "toOrganizationId": "123e4567-e89b-12d3-a456-426614174000",
  "project": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "fullName": "Project 1",
    "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
    "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e"
  },
  "txId": "0x1234567890abcdef",
  "state": "Accepted",
  "retirementReason": "reason",
  "retirementComment": "comment",
  "beneficiaryName": "John Doe"
}

Creates a "transfer" / "retire" / "transfer_retire" inventory request which the organization's admin can review and accept / decline.

Callable by any access token with permissions "organization_inventory:read_request".

cURL

curl -X 'POST' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/inventory/requests/{REQUEST_ACTION}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16' \
  -H 'Content-Type: application/json' \
  -d '{
  "creditId": "exPost-2-0x1234567890abcdef",
  "amount": 100,
  "toOrganizationId": "123e4567-e89b-12d3-a456-426614174000",
  "toAddress": "0x1234567890abcdef",
  "retirementData": {
    "reason": "Retirement reason",
    "beneficiaryName": "John Doe",
    "comment": "This is a comment"
  }
}'

Typescript

Testing endpoints

friendbot - test credits

Get some credits from the friendbot

This endpoint sends 100 credits to the organization account that owns the calling api key. Only on testnet.

GEThttps://api.carbonregistry.com/organizations/{id}/friendbot

Path parameters

id*string

Header parameters

Response

200

Body

application/json

serialization*string

The serialization string representing the credit to be transfered

amount*number

The amount of credits sent to your address

transactionId*string

The onchain transaction hash

Request

JavaScriptCurl

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/friendbot', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "serialization": "ICR-ALB-355-77993-2-A-0-2023",
  "amount": 1000,
  "transactionId": "0xcc73d182db1f36dbadf14205de7d543cfd1343396b50d34c768529aaab46a1c0"
}

To get some test credits into your organization on the sandbox you can use this endpoint with and organization Id that you control. It will deposit a 100 credits into your organization.

Callable by any access token regardless of permissions.

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/friendbot' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript