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

get

/organizations/{id}

Path parameters

idstringrequired

Header parameters

x-icr-api-versionstring · default: 2023-06-16

API version

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.carbonregistry.com/organizations/{id}'

200

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",
  "isPublic": true,
  "url": "https://api.carbonregistry.com/app/organizations/123e4567-e89b-12d3-a456-426614174000",
  "type": "projectProponent",
  "organizationIndustries": {
    "code": "IND1",
    "name": "Industry 1"
  }
}

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

get

/organizations/{id}/addresses

Path parameters

idstringrequired

Header parameters

x-icr-api-versionstring · default: 2023-06-16

API version

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.carbonregistry.com/organizations/{id}/addresses'

200

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",
  "isPublic": true,
  "url": "https://api.carbonregistry.com/app/organizations/123e4567-e89b-12d3-a456-426614174000",
  "type": "projectProponent",
  "organizationIndustries": {
    "code": "IND1",
    "name": "Industry 1"
  }
}

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

get

/organizations/{id}/inventory

Path parameters

idstringrequired

Query parameters

developmentstring

If defined returns the development inventory

Header parameters

x-icr-api-versionstring · default: 2023-06-16

API version

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.carbonregistry.com/organizations/{id}/inventory'

200

200

{
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "credits": [
    {
      "organizationId": "123e4567-e89b-12d3-a456-426614174000",
      "id": "exPost-2-0x1234567890abcdef",
      "tokenId": "abcdef",
      "tokenAddress": "0x1234567890abcdef",
      "serialization": "ICR-ISL-354-78040-14-R-0-2021",
      "vintage": "2020",
      "supply": 1000,
      "unit": "tonne",
      "amount": 100,
      "type": "exAnte",
      "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"
      }
    }
  ]
}

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

post

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

Path parameters

actionstring · enumrequired

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

Options: transfer, retire, transfer_retire, cancel, issuance, receive, claim, create_project, create_vintages

idstringrequired

The ID of the organization

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

Header parameters

x-icr-api-versionstring · default: 2023-06-16

API version

Body

creditIdstringrequired

The ID of the token credit

Example: exPost-2-0x1234567890abcdef

amountnumberrequired

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

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.carbonregistry.com/organizations/{id}/inventory/action/{action}' \
  --header 'Content-Type: application/json' \
  --data '{"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"}}'

200

200

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

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

get

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

Path parameters

idstringrequired

transactionIdstringrequired

Header parameters

x-icr-api-versionstring · default: 2023-06-16

API version

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.carbonregistry.com/organizations/{id}/transactions/{transactionId}'

200

200

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

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.

get

/organizations/{id}/friendbot

Path parameters

idstringrequired

Header parameters

x-icr-api-versionstring · default: 2023-06-16

API version

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.carbonregistry.com/organizations/{id}/friendbot'

200

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