Organizations

Who can use these endpoints

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

Information

Metadata for an organization.

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

Example: "2022-01-01T00:00:00Z"

updatedAt*string (date-time)

The update date of the organization

Example: "2022-01-01T00:00:00Z"

fullName*string

The full name of the organization

Example: "Organization 1"

countryCode*string

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

Example: "US"

citystring

The city of the organization

Example: "New York"

zipstring

The zip code of the organization

Example: "10001"

physicalAddressstring

The physical address of the organization

Example: "123 Main St"

registrationNumberstring

The registration number of the organization

Example: "123456"

websitestring

The website of the organization

Example: "http://example.com"

logo*string

The logo of the organization

Example: "logo.png"

id*string

The ID of the organization

Example: "123e4567-e89b-12d3-a456-426614174000"

organizationIndustriesall of

The industries of the organization

type*enum

The type of the organization

Example: "projectProponent"

projectProponentprojectDevelopervvbmarketplacebrokerexchangebuyerinsuranceconsultancydataAndAnalyticsmonitoringAndReportingnewsAndMediainvestmentAndFinancingratingsAgencyghgProgramother

isPublic*boolean

The public status of the organization

Example: true

url*string

The api URL of the organization

Example: "https://api.carbonregistry.com/app/organizations/123e4567-e89b-12d3-a456-426614174000"

Request

JavaScriptCurlPython

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

Response

200

{
  "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's Inventory Accounts

Returns the inventory accounts that this organization owns. Default and subaccounts.

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

Example: "2022-01-01T00:00:00Z"

updatedAt*string (date-time)

The update date of the organization

Example: "2022-01-01T00:00:00Z"

fullName*string

The full name of the organization

Example: "Organization 1"

countryCode*string

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

Example: "US"

citystring

The city of the organization

Example: "New York"

zipstring

The zip code of the organization

Example: "10001"

physicalAddressstring

The physical address of the organization

Example: "123 Main St"

registrationNumberstring

The registration number of the organization

Example: "123456"

websitestring

The website of the organization

Example: "http://example.com"

logo*string

The logo of the organization

Example: "logo.png"

id*string

The ID of the organization

Example: "123e4567-e89b-12d3-a456-426614174000"

organizationIndustriesall of

The industries of the organization

type*enum

The type of the organization

Example: "projectProponent"

projectProponentprojectDevelopervvbmarketplacebrokerexchangebuyerinsuranceconsultancydataAndAnalyticsmonitoringAndReportingnewsAndMediainvestmentAndFinancingratingsAgencyghgProgramother

isPublic*boolean

The public status of the organization

Example: true

url*string

The api URL of the organization

Example: "https://api.carbonregistry.com/app/organizations/123e4567-e89b-12d3-a456-426614174000"

Request

JavaScriptCurlPython

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

Response

200

{
  "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 wallet addresses of an organization. Mainly used for getting addresses to deposit credits into or to get inventory data for subaccounts.

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 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.

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

Example: "123e4567-e89b-12d3-a456-426614174000"

Request

JavaScriptCurlPython

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

Response

200

{
  "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'

Transact with credits in inventory

This endpoint creates a transaction for credits in the organization's inventory

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

Path parameters

action*enum

The action to perform on the token credit, one of transfer, retire, transfer_retire, cancel

transferretiretransfer_retirecancelissuancereceiveclaimcreate_projectcreate_vintages

id*string

The ID of the organization

Example: "123e4567-e89b-12d3-a456-426614174000"

Header parameters

Body

application/json

creditId*string

The ID of the token credit

Example: "exPost-2-0x1234567890abcdef"

amount*number

The amount of the token credit

Example: 100

toOrganizationIdstring

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

Example: "123e4567-e89b-12d3-a456-426614174000"

toAddressstring

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

Example: "0x1234567890abcdef"

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_retirecancelissuancereceiveclaimcreate_projectcreate_vintages

type*enum

Type of the credit request

exAnteexPostretirementCertificate

id*string

ID of the credit request

Example: "123e4567-e89b-12d3-a456-426614174000"

toAddressstring

Address of the recipient of the credit request

Example: "0x1234567890abcdef"

createdAt*string (date-time)

Timestamp of when the credit request was created

Example: "2022-01-01T00:00:00Z"

updatedAt*string (date-time)

Timestamp of when the credit request was last updated

Example: "2022-01-01T00:00:00Z"

tokenId*string

ID of the token associated with the credit request

Example: "123e4567-e89b-12d3-a456-426614174000"

tokenAddress*string

Address of the token associated with the credit request

Example: "0x1234567890abcdef"

creditId*string

ID of the credit associated with the credit request

Example: "exPost-2-0x1234567890abcdef"

serialization*string

Serialization of the credit request

Example: "serialization"

vintage*string

The vintage year of the credit

Example: "2020"

amount*number

Amount of the credit request

Example: 1000

fromOrganizationId*string

ID of the organization sending the credit request

Example: "123e4567-e89b-12d3-a456-426614174000"

toOrganizationIdstring

ID of the organization receiving the credit request

Example: "123e4567-e89b-12d3-a456-426614174000"

project*all of

Project information associated with the credit request

txIdstring

ID of the transaction associated with the credit request

Example: "0x1234567890abcdef"

state*enum

State of the credit request: cancelled | failed | pending_onchain | pending_queue | pending_request | pending_reserved | processed | rejected

processedfailedpending_queuepending_onchainpending_requestrejectedpending_reservedcancelled

transactionDataall of

The data for this transaction

retirementIdstring

The retirement ID of the reservation

Example: "1"

retirementReasonstring

Reason for retirement of the credit request

Example: "reason"

retirementCommentstring

Comment for retirement of the credit request

Example: "comment"

beneficiaryNamestring

Name of the beneficiary of the credit request

Example: "John Doe"

Request

JavaScriptCurlPython

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

Response

200

{
  "action": "transfer",
  "type": "exAnte",
  "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": "processed",
  "transactionData": {
    "creditId": "text",
    "tokenId": "text",
    "amount": 0,
    "serialization": "text"
  },
  "retirementId": "1",
  "retirementReason": "reason",
  "retirementComment": "comment",
  "beneficiaryName": "John Doe"
}

Creates a "transfer" / "retire" / "transfer_retire" transaction and puts it in the processing queue. To monitor the state of the transaction you can query the transaction endpoint.

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

cURL

curl -X 'POST' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/inventory/action/{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

Get an organization's transaction

This endpoint returns an organization's transaction

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

Path parameters

id*string

transactionId*string

Header parameters

Response

200

Body

application/json

action*enum

Action of the credit request

transferretiretransfer_retirecancelissuancereceiveclaimcreate_projectcreate_vintages

type*enum

Type of the credit request

exAnteexPostretirementCertificate

id*string

ID of the credit request

Example: "123e4567-e89b-12d3-a456-426614174000"

toAddressstring

Address of the recipient of the credit request

Example: "0x1234567890abcdef"

createdAt*string (date-time)

Timestamp of when the credit request was created

Example: "2022-01-01T00:00:00Z"

updatedAt*string (date-time)

Timestamp of when the credit request was last updated

Example: "2022-01-01T00:00:00Z"

tokenId*string

ID of the token associated with the credit request

Example: "123e4567-e89b-12d3-a456-426614174000"

tokenAddress*string

Address of the token associated with the credit request

Example: "0x1234567890abcdef"

creditId*string

ID of the credit associated with the credit request

Example: "exPost-2-0x1234567890abcdef"

serialization*string

Serialization of the credit request

Example: "serialization"

vintage*string

The vintage year of the credit

Example: "2020"

amount*number

Amount of the credit request

Example: 1000

fromOrganizationId*string

ID of the organization sending the credit request

Example: "123e4567-e89b-12d3-a456-426614174000"

toOrganizationIdstring

ID of the organization receiving the credit request

Example: "123e4567-e89b-12d3-a456-426614174000"

project*all of

Project information associated with the credit request

txIdstring

ID of the transaction associated with the credit request

Example: "0x1234567890abcdef"

state*enum

State of the credit request: cancelled | failed | pending_onchain | pending_queue | pending_request | pending_reserved | processed | rejected

processedfailedpending_queuepending_onchainpending_requestrejectedpending_reservedcancelled

transactionDataall of

The data for this transaction

retirementIdstring

The retirement ID of the reservation

Example: "1"

retirementReasonstring

Reason for retirement of the credit request

Example: "reason"

retirementCommentstring

Comment for retirement of the credit request

Example: "comment"

beneficiaryNamestring

Name of the beneficiary of the credit request

Example: "John Doe"

Request

JavaScriptCurlPython

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

Response

200

{
  "action": "transfer",
  "type": "exAnte",
  "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": "processed",
  "transactionData": {
    "creditId": "text",
    "tokenId": "text",
    "amount": 0,
    "serialization": "text"
  },
  "retirementId": "1",
  "retirementReason": "reason",
  "retirementComment": "comment",
  "beneficiaryName": "John Doe"
}

Gets a specific transaction.

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

cURL

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

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

Example: "ICR-ALB-355-77993-2-A-0-2023"

amount*number

The amount of credits sent to your address

Example: 1000

transactionId*string

The onchain transaction hash

Example: "0xcc73d182db1f36dbadf14205de7d543cfd1343396b50d34c768529aaab46a1c0"

Request

JavaScriptCurlPython

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

Response

200

{
  "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