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

get

This endpoint returns an organization

Path parameters

idstringRequired

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Responses

200Success

application/json

createdAtstring · date-timeRequired

The creation date of the organization

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

updatedAtstring · date-timeRequired

The update date of the organization

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

fullNamestringRequired

The full name of the organization

Example: Organization 1

countryCodestringRequired

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

Example: US

citystringOptional

The city of the organization

Example: New York

zipstringOptional

The zip code of the organization

Example: 10001

physicalAddressstringOptional

The physical address of the organization

Example: 123 Main St

registrationNumberstringOptional

The registration number of the organization

Example: 123456

websitestringOptional

The website of the organization

Example: http://example.com

logostringRequired

The logo of the organization

Example: logo.png

idstringRequired

The ID of the organization

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

typestring · enumRequired

The type of the organization

Example: projectProponentPossible values:

isPublicbooleanRequired

The public status of the organization

Example: true

urlstringRequired

The api URL of the organization

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

get

/organizations/{id}

HTTPcURLJavaScriptPython

GET /organizations/{id} HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

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

get

This endpoint returns an organization's public evm addresses

Path parameters

idstringRequired

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Responses

200Success

application/json

createdAtstring · date-timeRequired

The creation date of the organization

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

updatedAtstring · date-timeRequired

The update date of the organization

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

fullNamestringRequired

The full name of the organization

Example: Organization 1

countryCodestringRequired

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

Example: US

citystringOptional

The city of the organization

Example: New York

zipstringOptional

The zip code of the organization

Example: 10001

physicalAddressstringOptional

The physical address of the organization

Example: 123 Main St

registrationNumberstringOptional

The registration number of the organization

Example: 123456

websitestringOptional

The website of the organization

Example: http://example.com

logostringRequired

The logo of the organization

Example: logo.png

idstringRequired

The ID of the organization

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

typestring · enumRequired

The type of the organization

Example: projectProponentPossible values:

isPublicbooleanRequired

The public status of the organization

Example: true

urlstringRequired

The api URL of the organization

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

get

/organizations/{id}/addresses

HTTPcURLJavaScriptPython

GET /organizations/{id}/addresses HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

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

get

This endpoint returns a list of the organization's inventory

Path parameters

idstringRequired

Query parameters

developmentstringOptional

If defined returns the development inventory

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Responses

200Success

application/json

organizationIdstringRequired

The ID of the organization

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

get

/organizations/{id}/inventory

HTTPcURLJavaScriptPython

GET /organizations/{id}/inventory HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

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

post

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

Path parameters

actionstring · enumRequired

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

Possible values:

idstringRequired

The ID of the organization

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

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Body

application/json

creditIdstringRequired

The ID of the token credit

Example: exPost-2-0x1234567890abcdef

amountnumberRequired

The amount of the token credit

Example: 100

toOrganizationIdstringOptional

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

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

toAddressstringOptional

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

Example: 0x1234567890abcdef

Responses

200Success

application/json

actionstring · enumRequired

Action of the credit request

Possible values:

typestring · enumRequired

Type of the credit request

Possible values:

idstringRequired

ID of the credit request

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

toAddressstringOptional

Address of the recipient of the credit request

Example: 0x1234567890abcdef

createdAtstring · date-timeRequired

Timestamp of when the credit request was created

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

updatedAtstring · date-timeRequired

Timestamp of when the credit request was last updated

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

tokenIdstringRequired

ID of the token associated with the credit request

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

tokenAddressstringRequired

Address of the token associated with the credit request

Example: 0x1234567890abcdef

creditIdstringRequired

ID of the credit associated with the credit request

Example: exPost-2-0x1234567890abcdef

serializationstringRequired

Serialization of the credit request

Example: serialization

vintagestringRequired

The vintage year of the credit

Example: 2020

amountnumberRequired

Amount of the credit request

Example: 1000

fromOrganizationIdstringRequired

ID of the organization sending the credit request

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

toOrganizationIdstringOptional

ID of the organization receiving the credit request

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

txIdstringOptional

ID of the transaction associated with the credit request

Example: 0x1234567890abcdef

statestring · enumRequired

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

Possible values:

retirementIdstringOptional

The retirement ID of the reservation

Example: 1

retirementReasonstringOptional

Reason for retirement of the credit request

Example: reason

retirementCommentstringOptional

Comment for retirement of the credit request

Example: comment

beneficiaryNamestringOptional

Name of the beneficiary of the credit request

Example: John Doe

post

/organizations/{id}/inventory/action/{action}

HTTPcURLJavaScriptPython

POST /organizations/{id}/inventory/action/{action} HTTP/1.1
Host: api.carbonregistry.com
Content-Type: application/json
Accept: */*
Content-Length: 253

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

200Success

{
  "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": 1,
    "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

get

This endpoint returns an organization's transaction

Path parameters

idstringRequired

transactionIdstringRequired

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Responses

200Success

application/json

actionstring · enumRequired

Action of the credit request

Possible values:

typestring · enumRequired

Type of the credit request

Possible values:

idstringRequired

ID of the credit request

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

toAddressstringOptional

Address of the recipient of the credit request

Example: 0x1234567890abcdef

createdAtstring · date-timeRequired

Timestamp of when the credit request was created

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

updatedAtstring · date-timeRequired

Timestamp of when the credit request was last updated

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

tokenIdstringRequired

ID of the token associated with the credit request

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

tokenAddressstringRequired

Address of the token associated with the credit request

Example: 0x1234567890abcdef

creditIdstringRequired

ID of the credit associated with the credit request

Example: exPost-2-0x1234567890abcdef

serializationstringRequired

Serialization of the credit request

Example: serialization

vintagestringRequired

The vintage year of the credit

Example: 2020

amountnumberRequired

Amount of the credit request

Example: 1000

fromOrganizationIdstringRequired

ID of the organization sending the credit request

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

toOrganizationIdstringOptional

ID of the organization receiving the credit request

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

txIdstringOptional

ID of the transaction associated with the credit request

Example: 0x1234567890abcdef

statestring · enumRequired

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

Possible values:

retirementIdstringOptional

The retirement ID of the reservation

Example: 1

retirementReasonstringOptional

Reason for retirement of the credit request

Example: reason

retirementCommentstringOptional

Comment for retirement of the credit request

Example: comment

beneficiaryNamestringOptional

Name of the beneficiary of the credit request

Example: John Doe

get

/organizations/{id}/transactions/{transactionId}

HTTPcURLJavaScriptPython

GET /organizations/{id}/transactions/{transactionId} HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

{
  "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": 1,
    "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

get

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

Path parameters

idstringRequired

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Responses

200Success

application/json

serializationstringRequired

The serialization string representing the credit to be transfered

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

amountnumberRequired

The amount of credits sent to your address

Example: 1000

transactionIdstringRequired

The onchain transaction hash

Example: 0xcc73d182db1f36dbadf14205de7d543cfd1343396b50d34c768529aaab46a1c0

get

/organizations/{id}/friendbot

HTTPcURLJavaScriptPython

GET /organizations/{id}/friendbot HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

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