# Welcome to the Thallo API Programmatic access to carbon credits
Thallo logo
## Thallo API Carbon-as-a-Service is a single API solution that gives businesses instant access to millions of carbon credits across the entire carbon market. It allows businesses to easily and automatically embed high-quality, verified carbon credits into their products and services, with just a few lines of code. It allows you to programmatically access Thallo's aggregated carbon credit market, pulling the rich details of carbon offset projects from multiple registries into one standard and easy to consume format. The Thallo API allows you to purchase carbon credits by the tonne and retire down to the gram with one simple request. ## Thallo Account and API Key You will need an API key in order to access the API. If you already have a Thallo account please contact your account manager to retrieve your API key. If you do not have a Thallo account please contact [sales@thallo.io](mailto:sales@thallo.io?subject=Thallo%20account%20with%20API%20access) to open an account and get your API key. ## Thallo SDK If you are using an NPM compatible framework/runtime, such as [Node.js](https://nodejs.org/), Thallo recommend using our [Thallo SDK](https://github.com/thallo-io/thallo-exchange-npm-sdk/) NPM library. ## Thallo API Direct Access If you cannot use NPM or do not wish to use the Thallo SDK, you can achieve all of your carbon credit business goals by accessing the Thallo API directly. This documentation will walk you through all of the available endpoints and best practices to allow you to embed carbon into your existing products, systems and services. # Quick Start {% hint style="info" %} Use the [Thallo SDK](https://github.com/thallo-io/thallo-exchange-npm-sdk/) NPM library to integrate at lightning speed ⚡ {% endhint %} ## Example Code The full working code for this example can be found [here](https://github.com/thallo-io/thallo-api-example). In this example we do the following: 1. Get the market data, this contains sell orders for specific projects and vintages, including quantity available and the price per tonne. 2. Get the rich project data for all projects that have credits for sale. 3. Find a project that has been implemented in Sierra Leone. 4. Ensure the price is within your defined boundaries. 5. Purchase 1 whole tonne and retire 20 grams of the credits in one atomic action. > The purchase will only be made if you do not have 20 grams for this project and vintage available in your CaaS inventory ```ts // get market data const marketData = (await httpClient.get('/api/market')).data // get project ids so we can get the project details const projectIds = marketData.projects.map((project: { project_id: string }) => project.project_id) // we should cache the project data as it doesn't change often const projects = (await httpClient.get('/api/projects', { params: { project_ids: projectIds } })).data.projects // select project from Sierra Leone const selectedProject = projects.filter((project: { location: string }) => project.location === 'SL')[0] // get sell order for this project const vintage = marketData.projects.filter((project: { project_id: string }) => project.project_id === selectedProject.project_id)[0] .vintages[0] const sellOrder = vintage.sell_orders[0] // ensure the price is less than the max we're comfortable paying e.g. $10.45 if (BigNumber.from(sellOrder.price_cents).gt(1045)) { throw new Error('Sell order price too high') } // request retirement const retirementRequestId = (await httpClient.post('api/caas/request-retirement', { quantity_grams: '20', vintage_id: vintage.vintage_id, sell_order_id: sellOrder.sell_order_id, expected_price_cents: sellOrder.price_cents, })).data.retirement_request_id // get retirement details const retirement = (await httpClient.post('api/retirement', { params: { id: retirementRequestId } })).data ``` # Market Get all of the available sell orders on the market in real-time ## Overview Access the Thallo market data via API. The screenshot below is of the marketplace user interface which shows the same data as this endpoint returns:
Thallo marketplace
## Example cURL Request ```sh curl --request GET 'https://${BASE_URL}/api/market?page=1&per_page=20' \ --header 'Authorization: Bearer ${API_KEY}' ``` ## Endpoint Specification ## Get market data `GET` `/api/market` Get all of the available sell orders on the market in real-time #### Query Parameters | Name | Type | Description | | --------- | ------ | -------------------------------------------------------------------------------------------- | | page | number | For pagination. Which page would you like to be returned? The default value is 1. | | per\_page | number | For pagination. How many `project` results you would like per page. The default value is 20. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------- | | Authorization\* | string | `Bearer ${API_KEY}` | {% tabs %} {% tab title="200: OK " %} `price_cents` is per tonne. 1 tonne is 1,000,000 grams. Purchases are always made in whole tonnes. Prices are in USD cents. {% tabs %} {% tab title="Example" %} ```json { "projects": [ { "project_id": "003g3ghxs84jlgw5pi", "vintages": [ { "vintage_id": "004fdpkssx2zi9vodm", "vintage_year": 2019, "sell_orders": [ { "sell_order_id": "006mcfdyidljqj9bs1", "quantity_grams": "1000000", "price_cents": "1500" } ] } ] } ], "pagination": { "per_page": 20, "total_pages": 5, "total_items": 100, "current_page": 1, "previous_page": 1, "next_page": 1 } } ``` {% endtab %} {% tab title="Schema" %} ```typescript { projects: Array<{ project_id: string vintages: Array<{ vintage_id: string vintage_year: number sell_orders: Array<{ sell_order_id: string quantity_grams: string price_cents: string }> }> }> pagination: { per_page: number total_pages: number total_items: number current_page: number previous_page: number next_page: number } } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="401: Unauthorized Your API key is unrecognized or inactive" %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 401, "message": "Unauthorized" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="403: User does not have `API User` role." %} {% tabs %} {% tab title="Example" %} ```json { "error": "Forbidden", "message": "Permission denied according to assigned roles.", "statusCode": 403 } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string error: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500: Server error An unexpected error has occurred on the server." %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 500, "message": "Internal server error" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ## Enriching With Project Data The market data changes frequently and this endpoint returns the up-to-date market data upon each call. However the data about the carbon offset projects remains relatively static and therefore this data is available in a separate [Project Details](/api-endpoints/projects) endpoint in order to keep the market data endpoint lightweight. Use the `project_id`s returned in the market data and call the [Project Details](/api-endpoints/projects) endpoint to retrieve the details of each project. {% hint style="success" %} Thallo recommend you cache this project data locally to speed up your application and reduce unnecessary traffic. {% endhint %} # Project Details Get detailed project and vintage data ## Overview Access details about carbon offset projects and their vintages. The screenshot below is of the project detail screen which shows similar data as this endpoint returns:
Project data page
## Example cURL Request ```sh curl --request GET 'https://${BASE_URL}/api/projects?project_ids[]=003q81qxjb6rru572v&project_ids[]=0037yhin9rxb2v8coh' \ --header 'Authorization: Bearer ${API_KEY}' ``` ## Endpoint Specification ## Get project data `GET` `/api/projects` Get detailed project and vintage data for multiple projects #### Query Parameters | Name | Type | Description | | ------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------- | | project\_ids\[]\* | string\[] | You may specify this query parameter multiple times to retrieve data for multiple projects. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------- | | Authorization\* | string | `Bearer ${API_KEY}` | {% tabs %} {% tab title="200: OK " %} {% tabs %} {% tab title="Example" %} ```json { "projects": [ { "project_id": "003s9eb104zcu2gclk", "project_name": "Example Hydro project", "type": "Hydro", "location": "TD", "registry_project_url": "https://example.com/", "sdgs": [ "Life Below Water", "Gender Equality", "Infrastructure", "Quality Education", "Zero Hunger", "Health and Well Being", "No Poverty", "Water Benefit", "Economic Growth" ], "registry_id": "005h8koa2ioo0qgq3x", "registry_name": "BioCarbon Registry", "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.", "vintages": [ { "vintage_id": "004bjccxq1p4j6f954", "vintage_year": 2014, "registry_vintage_url": "https://example.com/" }, { "vintage_id": "0042g006orga6wll64", "vintage_year": 2019, "registry_vintage_url": "https://example.com/" }, { "vintage_id": "004wk8qmn51yjftw7g", "vintage_year": 2020, "registry_vintage_url": "https://example.com/" } ] } ] } ``` {% endtab %} {% tab title="Schema" %} ```typescript { projects: Array<{ project_id: string project_name: string type: string location: string registry_project_url: string sdgs: Array registry_id: string registry_name: string description: string vintages: Array<{ vintage_id: string vintage_year: number registry_vintage_url: string }> }> } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="401: Unauthorized Your API key is unrecognized or inactive" %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 401, "message": "Unauthorized" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="403: User does not have `API User` role." %} {% tabs %} {% tab title="Example" %} ```json { "error": "Forbidden", "message": "Permission denied according to assigned roles.", "statusCode": 403 } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string error: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500: Server error An unexpected error has occurred on the server." %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 500, "message": "Internal server error" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ## Project Data ### Registry Ids and Names Thallo will return both the `registry_id` and the `registry_name` for convenience. Please note the registry name is a label and may change, however the registry id will remain static. #### Value Values
registry_id Value from APIregistry_name Vale from API
005h8koa2ioo0qgq3xBioCarbon Registry
005yuwbp97mxjnk122Puro.earth
005a86q13pgj9c3612Gold Standard
005y75kep1v7snof1xAmerican Carbon Registry
0050yd569dw0qbw5oyVERRA
0056bnn0ernrsikdbrUNFCCC Clean Development Mechanism
0057qpby5eqk470eucCercarbono / EcoRegistry
005oymz2l3624dokjfClimate Action Reserve
005r76093fm1wjqd13Plan Vivo
005yuwbp97mxjnklnzGlobal Carbon Council
005vgugi19i1pqveb6Centigrade
005c5sqk87b8fdjtmvSocial Carbon
Easy to copy values ``` 005h8koa2ioo0qgq3x BioCarbon Registry 005yuwbp97mxjnk122 Puro.earth 005a86q13pgj9c3612 Gold Standard 005y75kep1v7snof1x American Carbon Registry 0050yd569dw0qbw5oy VERRA 0056bnn0ernrsikdbr UNFCCC Clean Development Mechanism 0057qpby5eqk470euc Cercarbono / EcoRegistry 005oymz2l3624dokjf Climate Action Reserve 005r76093fm1wjqd13 Plan Vivo 005yuwbp97mxjnklnz Global Carbon Council 005vgugi19i1pqveb6 Centigrade 005c5sqk87b8fdjtmv Social Carbon ```
### Sustainable Development Goals (SDGs) #### What are SDGs? The 17 Sustainable Development Goals (SDGs) are an urgent call for action by all countries - developed and developing - in a global partnership. They recognize that ending poverty and other deprivations must go hand-in-hand with strategies that improve health and education, reduce inequality, and spur economic growth – all while tackling climate change and working to preserve our oceans and forests. [Read more](https://sdgs.un.org/goals). A carbon project can satisfy none, one or multiple SDGs during its implementation, which indicates additional co-benefits beyond carbon reduction or removal. #### Valid Values | Value from API | UN Link | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `No Poverty` | [Goal 1](https://sdgs.un.org/goals/goal1) | | `Zero Hunger` | [Goal 2](https://sdgs.un.org/goals/goal2) | | `Health and Well Being` | [Goal 3](https://sdgs.un.org/goals/goal3) | | `Quality Education` | [Goal 4](https://sdgs.un.org/goals/goal4) | | `Gender Equality` | [Goal 5](https://sdgs.un.org/goals/goal5) | | `Water Benefit` | [Goal 6](https://sdgs.un.org/goals/goal6) | | `Clean Energy` | [Goal 7](https://sdgs.un.org/goals/goal7) | | `Economic Growth` | [Goal 8](https://sdgs.un.org/goals/goal8) | | `Infrastructure` | [Goal 9](https://sdgs.un.org/goals/goal9) | | `Reduced Inequalities` | [Goal 10](https://sdgs.un.org/goals/goal10) | | `Sustainable Cities` | [Goal 11](https://sdgs.un.org/goals/goal11) | | `Responsible Consumption and Production` | [Goal 12](https://sdgs.un.org/goals/goal12) | | `Climate Action` | [Goal 13](https://sdgs.un.org/goals/goal13) | | `Life Below Water` | [Goal 14](https://sdgs.un.org/goals/goal14) | | `Life On Land` | [Goal 15](https://sdgs.un.org/goals/goal15) | | `Peace and Justice` | [Goal 16](https://sdgs.un.org/goals/goal16) | | `Partnerships for the Goals` | [Goal 17](https://sdgs.un.org/goals/goal17) |
Easy to copy values ``` No Poverty Zero Hunger Health and Well Being Quality Education Gender Equality Water Benefit Clean Energy Economic Growth Infrastructure Reduced Inequalities Sustainable Cities Responsible Consumption and Production Climate Action Life Below Water Life On Land Peace and Justice Partnerships for the Goals ```
### Project Types Project types are not standardized across registries, however, Thallo map these values into a single set of project types to allow you to easily filter and analyze projects regardless of which registry they originate from. #### Valid Values | Value from API | | ---------------------------------------------------- | | `Afforestation, Reforestation & Restoration` | | `Agricultural Methane Recovery` | | `Avoided Deforestation` | | `Biochar` | | `Bioenergy Carbon Capture & Storage` | | `Biogas` | | `Biomass` | | `Boreholes` | | `Brick Manufacturing` | | `Carbonated Building Materials` | | `Cement & Concrete` | | `Cookstoves` | | `Direct Air Capture` | | `Domestic Energy Efficiency` | | `Domestic Fuel Efficiency - Biodigesters` | | `Domestic Fuel Efficiency - Lighting` | | `Energy Efficiency` | | `Enhanced Oil Recovery` | | `Enhanced Weathering` | | `Feed Additives` | | `Fuel Switch` | | `Fugitive Emissions` | | `Geologically Stored` | | `Geothermal` | | `Grasslands` | | `Hydro` | | `Improved Forest Management` | | `Industrial Energy Efficiency` | | `Irrigation` | | `Landfill Gas` | | `Mangroves` | | `Metal production` | | `Methane Capture` | | `N2O from Adipic Acid` | | `N2O from Nitric Acid` | | `Non-Oil Recycling` | | `Oil Recycling` | | `Other transport` | | `Ozone Depleting Substances` | | `Peatlands` | | `REDD+` | | `Regenerative Agriculture` | | `Renewables` | | `Seagrass & Seaweeds` | | `Soil Amendment based on Carbon Storage Methodology` | | `Solar` | | `Sulphur Emissions` | | `Synthetic Fuels` | | `Waste Heat Recovery` | | `Water` | | `Water Filters` | | `Wetland Restoration` | | `Wind` | | `Wooden Building Materials` | | `Woody Biomass Burial` |
Easy to copy values ``` Afforestation, Reforestation & Restoration Agricultural Methane Recovery Avoided Deforestation Biochar Bioenergy Carbon Capture & Storage Biogas Biomass Boreholes Brick Manufacturing Carbonated Building Materials Cement & Concrete Cookstoves Direct Air Capture Domestic Energy Efficiency Domestic Fuel Efficiency - Biodigesters Domestic Fuel Efficiency - Lighting Energy Efficiency Enhanced Oil Recovery Enhanced Weathering Feed Additives Fuel Switch Fugitive Emissions Geologically Stored Geothermal Grasslands Hydro Improved Forest Management Industrial Energy Efficiency Irrigation Landfill Gas Mangroves Metal production Methane Capture N2O from Adipic Acid N2O from Nitric Acid Non-Oil Recycling Oil Recycling Other transport Ozone Depleting Substances Peatlands REDD+ Regenerative Agriculture Renewables Seagrass & Seaweeds Soil Amendment based on Carbon Storage Methodology Solar Sulphur Emissions Synthetic Fuels Waste Heat Recovery Water Water Filters Wetland Restoration Wind Wooden Building Materials Woody Biomass Burial ```
### Project Locations Thallo follow the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard for 2 letter country codes. #### Valid Values | Value from API | Country | | -------------- | ----------------------------------------------------------------- | | AD | ![](/files/qmTxfvNg4Y6VwlNHD5Ek) Andorra | | AE | ![](/files/RYfxcE6d7vJ94LLzOKgC) United Arab Emirates | | AF | ![](/files/iJL61EULbVmLoKH7mLLY) Afghanistan | | AG | ![](/files/lRWEGglOUWjAzY5052A9) Antigua and Barbuda | | AI | ![](/files/jkddXiR2mbM8r7Zxw6Ld) Anguilla | | AL | ![](/files/KIpsz4WMSLq6pOrl6w4G) Albania | | AM | ![](/files/3f5cXvf2qLANmHIgcmEr) Armenia | | AO | ![](/files/FGihHnyZ5HKhqShMcqqW) Angola | | AR | ![](/files/IokhlilO7PPQx4MXynZh) Argentina | | AS | ![](/files/q2x9IvTd058dzqecr1Iv) American Samoa | | AT | ![](/files/gfRwaEyDW9M5F2pRNGdm) Austria | | AU | ![](/files/dmE252Qe07tkmVjwVvyM) Australia | | AW | ![](/files/jIJ3INbkSIctt9XngHgm) Aruba | | AX | ![](/files/gks9O0VIHJi41iB2qXOp) Åland Islands | | AZ | ![](/files/BcuTGeczDJgnZmRxxsjE) Azerbaijan | | BA | ![](/files/K34RuLbgHNCgGOXIj9na) Bosnia and Herzegovina | | BB | ![](/files/pjT4w4Jk9U7Cs0gFhenM) Barbados | | BD | ![](/files/jAfeBk7LQNQTSj8TpRkG) Bangladesh | | BE | ![](/files/d9BbBJuX7moPrQLBtWwU) Belgium | | BF | ![](/files/CuFUYvFa9zFPTcnFJygp) Burkina Faso | | BG | ![](/files/EvzSeYuXFZbrqp0yk7wu) Bulgaria | | BH | ![](/files/ET3DGEyWDXlMWWiXVV91) Bahrain | | BI | ![](/files/rUsyNotFcpHI6YpyJYt2) Burundi | | BJ | ![](/files/xaGcjQEZHDeOpvXuqvNs) Benin | | BL | ![](/files/XePPgfk39ztIOMvBG7Iv) Saint Barthélemy | | BM | ![](/files/r6mSX4mYvHLaWjXLTJJ3) Bermuda | | BN | ![](/files/jl0bqYeJJ78onhaYjLjT) Brunei Darussalam | | BO | ![](/files/KZn665RZAUg3ZmRI2Lqh) Bolivia | | BQ | ![](/files/O8egfqH8zF7TB5h7CJPq) Bonaire, Sint Eustatius and Saba | | BR | ![](/files/okQY93ElXKnfN3eI7Pkj) Brazil | | BS | ![](/files/zs6gnKMLWr2rEXhD8yb3) Bahamas | | BT | ![](/files/1qpyQZEvZAJcpzPH6nps) Bhutan | | BW | ![](/files/IZFZAeF3bqWxg5NBfCAw) Botswana | | BY | ![](/files/k9FqzHtSEA9i9gQGIdne) Belarus | | BZ | ![](/files/HMIFFsStScPj7HsTAcFB) Belize | | CA | ![](/files/KxFxuoxnzkwoCiWIXhsT) Canada | | CC | ![](/files/XasBfhNDn3w9SvlS7yIL) Cocos (Keeling) Islands | | CD | ![](/files/2JjsilbeWnxkupi46nGD) Democratic Republic of the Congo | | CF | ![](/files/jNRUvFJulwZL5motg5i0) Central African Republic | | CG | ![](/files/JQ732SUZ7rcaXIoyTRJx) Congo | | CH | ![](/files/VAldKElgbukQcn10Gl9V) Switzerland | | CK | ![](/files/BjnqqD86LgKMaAfy2Kgr) Cook Islands | | CL | ![](/files/OIhK8FyTLcaZDxusqTPz) Chile | | CM | ![](/files/0STquoMHqRJyfdafkEtO) Cameroon | | CN | ![](/files/ZjQf6eJRNr1UN1LoSDOJ) China | | CO | ![](/files/m3iFODXtTywoEt58bVvE) Colombia | | CR | ![](/files/CenX6S12lKA2RuVNFQoK) Costa Rica | | CU | ![](/files/fkSgpSx1cjgZNpYLhDHF) Cuba | | CW | ![](/files/s7U02ApY1x1OW7IIkyCp) Curaçao | | CX | ![](/files/XzPKzk52tYftAOV9AgHY) Christmas Island | | CY | ![](/files/qxlndQrfSqXiQ1oQzcAH) Cyprus | | CZ | ![](/files/ukuksCLe0vl4QT44eLFI) Czechia | | DE | ![](/files/eybg1o9bopfcsboJma4y) Germany | | DJ | ![](/files/zorGpf0wb4jmB29AzRUC) Djibouti | | DK | ![](/files/25f34mWoH6khP4DoQTkB) Denmark | | DM | ![](/files/SozbkjHTNEa2daJYCqw9) Dominica | | DO | ![](/files/fRZUKwDVotbHWVAUNllH) Dominican Republic | | DZ | ![](/files/RE8k1bUEiaJ45vQ1BEN9) Algeria | | EC | ![](/files/KFrrBXv6GNg5iSZOGEYe) Ecuador | | EE | ![](/files/6eXshQxrvQVRRkkmRnGw) Estonia | | EG | ![](/files/gZnluRsmJsAFaxvF1S2G) Egypt | | EH | ![](/files/vauLWGwPPafroV2IOJui) Western Sahara | | ER | ![](/files/4dUxrDgXy34ZzJYyr476) Eritrea | | ES | ![](/files/S3nvkj2cUs57XksNnowV) Spain | | ET | ![](/files/S0z3TuDJtANt78J84GrS) Ethiopia | | FI | ![](/files/Hj7PO61VsJnK2WwwM9gZ) Finland | | FJ | ![](/files/G04vzYeAexnhbIJ2Duiv) Fiji | | FK | ![](/files/WJV6O3vl5uCdLsNj0Hzs) Falkland Islands | | FM | ![](/files/gZjQxOTSlPT0L8yyDFN7) Micronesia | | FO | ![](/files/rwvlR1M3q6u8fInxnZcP) Faroe Islands | | FR | ![](/files/u7N8L3Cb85AyeU7JEVR6) France | | GA | ![](/files/AUJ8LPXrlLymYUFK3XeY) Gabon | | GB | ![](/files/qPQ4p2oHoEkiuisy4dsO) United Kingdom | | GD | ![](/files/ajWiMk6mlhOCVl99ykxI) Grenada | | GE | ![](/files/PDdBChjrKcV7V8OFlVMi) Georgia | | GG | ![](/files/poFya3WWb2aJS3js222p) Guernsey | | GH | ![](/files/m9WN0gDRLety8WaKoltx) Ghana | | GI | ![](/files/HW0Xu6BFGZSmc2Im8gmN) Gibraltar | | GL | ![](/files/DgsMMyo7a5tb53Ym3WqD) Greenland | | GM | ![](/files/MFgFZMhlKGKE7JtGYeql) Gambia | | GN | ![](/files/2zFFEIPWUKAKVcVBxC3h) Guinea | | GQ | ![](/files/JaCJsPZE4S0Zke5gkfkv) Equatorial Guinea | | GR | ![](/files/dvkhZGKXtc89cto22x94) Greece | | GT | ![](/files/y1jTiKjMjsMjus1T2DIr) Guatemala | | GU | ![](/files/LuxoID60eUj7axbEeqoq) Guam | | GW | ![](/files/JsbCmotCekZAmbLFNIHZ) Guinea-Bissau | | GY | ![](/files/he7FRPPL3QMpxetp8tTa) Guyana | | HK | ![](/files/yu4kCzYaG6YdXVjLneWh) Hong Kong | | HN | ![](/files/6KxzQ4NManiz9RkWeIfI) Honduras | | HR | ![](/files/uxCI2ayj0kcWMK0H30QW) Croatia | | HT | ![](/files/vv3cD6RDcTblqbDXZLAh) Haiti | | HU | ![](/files/7RljKMOPIH6NhqEsyJDZ) Hungary | | ID | ![](/files/goCfbtfImrNvBIovokkJ) Indonesia | | IE | ![](/files/LFFBprb3xsLOXpbivb6d) Ireland | | IL | ![](/files/qcZk9EaxzbqOeEyibINm) Israel | | IM | ![](/files/AkSMcIoMQZAw43AgScoB) Isle of Man | | IN | ![](/files/chIsD4mzP9sUQk69dnRT) India | | IO | ![](/files/7KCnI2hJy1ymQLzFYJte) British Indian Ocean Territory | | IQ | ![](/files/lucqq4ahMeRSsulgOt6V) Iraq | | IR | ![](/files/LRrD8h1EnrelfKiDXd4F) Iran | | IS | ![](/files/qFj5VEKlcDKT1bLl2In7) Iceland | | IT | ![](/files/jkPv0n4Ax7ZKdVO9nEtB) Italy | | JE | ![](/files/IzPaRfo4Nanj9HswJaNG) Jersey | | JM | ![](/files/3UnuTdwOgc9Xy2iDSv61) Jamaica | | JO | ![](/files/eLBi0gBNGa1wEypUYt80) Jordan | | JP | ![](/files/YKAzO8EyDM99Ad5wTU1Z) Japan | | KE | ![](/files/QfbIH20PnZHAW0Wphwar) Kenya | | KG | ![](/files/SVEDcOSXmaLmYJq9ZT2H) Kyrgyzstan | | KH | ![](/files/MZ77S8jSruFUH5If4u9R) Cambodia | | KI | ![](/files/I59bgGPJRnj5dW8ehlLK) Kiribati | | KM | ![](/files/ZO99PjYH58oRSSMewMk5) Comoros | | KN | ![](/files/vuJWD6oQOnsS8ASF5vSJ) Saint Kitts and Nevis | | KP | ![](/files/mUqPVlYiq0XuQ2T8VSim) North Korea | | KR | ![](/files/4rJxdbKcQ49hjRfORvIi) South Korea | | KW | ![](/files/go8k1D1XiR2gQdAKbAdU) Kuwait | | KY | ![](/files/jpDIrDGu5PVy2s5sjdcN) Cayman Islands | | KZ | ![](/files/RFB5rikW5UVBoe7UBvz2) Kazakhstan | | LA | ![](/files/iYSHV2xCqMJ2F9mTV9Ki) Lao People's Democratic Republic | | LB | ![](/files/ECqniSAWzw2RhM6ukKGs) Lebanon | | LC | ![](/files/rk55oIm5Dj1gOPPV5nl0) Saint Lucia | | LI | ![](/files/QBtxHTVm5u7orJiv5rAr) Liechtenstein | | LK | ![](/files/nXrzbg8rJ9TvkwjPe3su) Sri Lanka | | LR | ![](/files/WoDWvOaFH4ev4G6nOQKt) Liberia | | LS | ![](/files/dVAcV7rUUN8h6HEhxoPy) Lesotho | | LT | ![](/files/t2nCYdWIo6G6ecjy437Q) Lithuania | | LU | ![](/files/59rmmjY7Q05oaArjRc43) Luxembourg | | LV | ![](/files/sqLMjZLP4ECeBrIWOQqD) Latvia | | LY | ![](/files/JxZ7RLrhpXWHzsKnYR2N) Libya | | MA | ![](/files/bHtXS9alOuuRU9HMp7Ud) Morocco | | MC | ![](/files/dR4DeVxc0ks7zv4hOrxg) Monaco | | MD | ![](/files/EU0qT9ctohmZatJW7H5Q) Moldova | | ME | ![](/files/801OqKoFlJIKKZMRG8gf) Montenegro | | MG | ![](/files/2eWpichPEdPsd18PZoeh) Madagascar | | MH | ![](/files/rLfBFA6INlERHjjByQNQ) Marshall Islands | | MK | ![](/files/Ktk7n1cMM60pE7QH42F9) North Macedonia | | ML | ![](/files/J6oaDFldTl6EV955nvxL) Mali | | MM | ![](/files/981ApiohucnnzcxtYx5d) Myanmar | | MN | ![](/files/u9GFeyrO0Stbpoa4Mdvo) Mongolia | | MO | ![](/files/mKqFv48VaHOzjvOlX50k) Macao | | MP | ![](/files/YjVQGbl2YCAUH4JClZMq) Northern Mariana Islands | | MQ | ![](/files/BW4G1owF8VQetdd1t5qG) Martinique | | MR | ![](/files/sGftI8aNIRWDl7jSA5WW) Mauritania | | MS | ![](/files/8Zq388MBDqxfaxmhXVPW) Montserrat | | MT | ![](/files/pNTSFgc9hTIRAsdpMRGq) Malta | | MU | ![](/files/G56bVDmEwc5bHyUae42A) Mauritius | | MV | ![](/files/kFHvDGLkNyllDnDrjas3) Maldives | | MW | ![](/files/nK6vWo20Xad8zSW0KnaP) Malawi | | MX | ![](/files/g7SOFuA0176k8jhtkseZ) Mexico | | MY | ![](/files/O2GRwQLCtO9xBK9919FA) Malaysia | | MZ | ![](/files/C3AMPMnSKBSDmY7RDncM) Mozambique | | NA | ![](/files/0OH139VklJOncb05wS81) Namibia | | NE | ![](/files/MWVtKl0CG1ZjZHYtNIOc) Niger | | NF | ![](/files/ECWnzatI7du2UZOkZGKE) Norfolk Island | | NG | ![](/files/byRqmUlDap3Rawe1nqEv) Nigeria | | NI | ![](/files/hllKva5aqMGR05bSKFEB) Nicaragua | | NL | ![](/files/FrDgNVSKKIbbnjFHu5O8) Netherlands | | NO | ![](/files/KN5zdKkg0pkRoNlN9fGg) Norway | | NP | ![](/files/EaB7k0J2klVoNdOC3ixV) Nepal | | NR | ![](/files/Wivr3RPHss9f5U4yB5xJ) Nauru | | NU | ![](/files/9tI5RTxiwXLBBYdMlmi2) Niue | | NZ | ![](/files/Gj7jdckKIjXQNYBOPgVv) New Zealand | | OM | ![](/files/Ih0iwtedo9OvfnEHXO6U) Oman | | PA | ![](/files/zyscRwoZyTWhMd4joHy5) Panama | | PE | ![](/files/5Kxcjmu382iCJ1dHLhAW) Peru | | PF | ![](/files/zt7a4tbsype9k8pSCNHL) French Polynesia | | PG | ![](/files/diBjtFy8i7ZbLa3pv5dO) Papua New Guinea | | PH | ![](/files/Mg1XhNTHk2B0bksZZZcR) Philippines | | PK | ![](/files/5mRtoesDw82e6Fbhl0wJ) Pakistan | | PL | ![](/files/Loucmk5PbVDyqEO8oyx0) Poland | | PN | ![](/files/vJA7YjZlwWfnigvugmmT) Pitcairn | | PR | ![](/files/Irp7qSYtN8g7E0wGftvx) Puerto Rico | | PS | ![](/files/KtKireaGQSG281nBAJ8q) Palestine, State of | | PT | ![](/files/BT9IblHGoS7VYeM7OqXH) Portugal | | PW | ![](/files/owfojuoRTo4Gwo9qazgj) Palau | | PY | ![](/files/Hl8cfOKLfEYSmPDaTFPd) Paraguay | | QA | ![](/files/7xXeyDFHrphOkWlfgGQL) Qatar | | RO | ![](/files/fLsbO4SCXEmJgCx4L5hZ) Romania | | RS | ![](/files/85bFGWIJNHuWjhtgtLSZ) Serbia | | RU | ![](/files/Bl0pLeG7kZ8tVRJyV1O5) Russian Federation | | RW | ![](/files/KHEOHg96PRjFlz9wj6O1) Rwanda | | SA | ![](/files/7QAryZe5wN1GLPLPy82H) Saudi Arabia | | SB | ![](/files/tsuVXCYjbgQCmb5ZF39c) Solomon Islands | | SC | ![](/files/jh8QsmJf0Jy4m5zzOndO) Seychelles | | SD | ![](/files/hY7T5TmTf2QHE5Jx2HL0) Sudan | | SE | ![](/files/1uhfdbDIIMnTo2F43Bul) Sweden | | SG | ![](/files/Zb0d5cJGrcrM7M3vkHIB) Singapore | | SI | ![](/files/SvPLLRVaI4Ad0Fh51m9U) Slovenia | | SK | ![](/files/G6tuv01QEpq91dabGFrl) Slovakia | | SL | ![](/files/QlAE4jnWxG4KdHtGFtXB) Sierra Leone | | SM | ![](/files/QqEI7W712NbSoYUWD71l) San Marino | | SN | ![](/files/aVKly62kIIdKydv7pvsH) Senegal | | SO | ![](/files/yaf4RoARlUwsKcXi9xYN) Somalia | | SR | ![](/files/3bX5jHjfVH04rZ8YFoaV) Suriname | | SS | ![](/files/upTD928GDkiz1jxoEHVu) South Sudan | | ST | ![](/files/i9eQtpF5etQW66D4J6OY) Sao Tome and Principe | | SV | ![](/files/BTHCfEin8SsDSwc7cfab) El Salvador | | SX | ![](/files/2KExYojaqygPF8OyWn9E) Sint Maarten | | SZ | ![](/files/pQ0Ud4oYoy5sRrpiSQjN) Eswatini | | TD | ![](/files/tErs6vrCoFDtBzE7tETv) Chad | | TL | ![](/files/DSnLMPFWNAlwoetUWd1V) Timor-Leste | | TN | ![](/files/ScKfRVppmkYZGeFiDaEg) Tunisia | | TR | ![](/files/0qAvLk6Wva3bjtbitfHu) Türkiye | | TT | ![](/files/tIlc8EgqFFJPe5ACSq7J) Trinidad and Tobago | | UG | ![](/files/eMUybeIsDqNtoBpSOy0H) Uganda | | UA | ![](/files/o9qXDG0K4m4xrfceDvsb) Ukraine | | US | ![](/files/XDe21IZORpN3PRrUNeHU) United States of America | | UY | ![](/files/vBcj9OyCtfDTZY5hpYQp) Uruguay | | VC | ![](/files/GHi1Znnlpnmlu6fXZXTX) Saint Vincent and the Grenadines | | VE | ![](/files/4A760j8NQvsID7REsSSM) Venezuela | | VG | ![](/files/Pqe8sveY79ASeOv6iHxl) Virgin Islands (British) | | VI | ![](/files/mzIAirPM7GHpBmxlPQIl) Virgin Islands (U.S.) | | VN | ![](/files/zbYqUpkpR8YrEhSRI08a) Viet Nam | | VU | ![](/files/F6x2DO3J7IR5luZN05ov) Vanuatu | | WS | ![](/files/qtntAYZpKSJXtgME88sk) Samoa | | YE | ![](/files/yw1x0fDTZ1rNDPGYSvwj) Yemen | | ZA | ![](/files/Wob9TkhHH2BiDk93P6qg) South Africa | | ZM | ![](/files/rjKUNuWN64nE0MOj9rCI) Zambia | | ZW | ![](/files/hHxvmJuCbuLzXCxlP3eD) Zimbabwe |
Easy to copy values ``` AD Andorra AE United Arab Emirates AF Afghanistan AG Antigua and Barbuda AI Anguilla AL Albania AM Armenia AO Angola AR Argentina AS American Samoa AT Austria AU Australia AW Aruba AX Åland Islands AZ Azerbaijan BA Bosnia and Herzegovina BB Barbados BD Bangladesh BE Belgium BF Burkina Faso BG Bulgaria BH Bahrain BI Burundi BJ Benin BL Saint Barthélemy BM Bermuda BN Brunei Darussalam BO Bolivia BQ Bonaire, Sint Eustatius and Saba BR Brazil BS Bahamas BT Bhutan BW Botswana BY Belarus BZ Belize CA Canada CC Cocos (Keeling) Islands CD Democratic Republic of the Congo CF Central African Republic CG Congo CH Switzerland CK Cook Islands CL Chile CM Cameroon CN China CO Colombia CR Costa Rica CU Cuba CW Curaçao CX Christmas Island CY Cyprus CZ Czechia DE Germany DJ Djibouti DK Denmark DM Dominica DO Dominican Republic DZ Algeria EC Ecuador EE Estonia EG Egypt EH Western Sahara ER Eritrea ES Spain ET Ethiopia FI Finland FJ Fiji FK Falkland Islands FM Micronesia FO Faroe Islands FR France GA Gabon GB United Kingdom GD Grenada GE Georgia GG Guernsey GH Ghana GI Gibraltar GL Greenland GM Gambia GN Guinea GQ Equatorial Guinea GR Greece GT Guatemala GU Guam GW Guinea-Bissau GY Guyana HK Hong Kong HN Honduras HR Croatia HT Haiti HU Hungary ID Indonesia IE Ireland IL Israel IM Isle of Man IN India IO British Indian Ocean Territory IQ Iraq IR Iran IS Iceland IT Italy JE Jersey JM Jamaica JO Jordan JP Japan KE Kenya KG Kyrgyzstan KH Cambodia KI Kiribati KM Comoros KN Saint Kitts and Nevis KP North Korea KR South Korea KW Kuwait KY Cayman Islands KZ Kazakhstan LA Lao People's Democratic Republic LB Lebanon LC Saint Lucia LI Liechtenstein LK Sri Lanka LR Liberia LS Lesotho LT Lithuania LU Luxembourg LV Latvia LY Libya MA Morocco MC Monaco MD Moldova ME Montenegro MG Madagascar MH Marshall Islands MK North Macedonia ML Mali MM Myanmar MN Mongolia MO Macao MP Northern Mariana Islands MQ Martinique MR Mauritania MS Montserrat MT Malta MU Mauritius MV Maldives MW Malawi MX Mexico MY Malaysia MZ Mozambique NA Namibia NE Niger NF Norfolk Island NG Nigeria NI Nicaragua NL Netherlands NO Norway NP Nepal NR Nauru NU Niue NZ New Zealand OM Oman PA Panama PE Peru PF French Polynesia PG Papua New Guinea PH Philippines PK Pakistan PL Poland PN Pitcairn PR Puerto Rico PS Palestine, State of PT Portugal PW Palau PY Paraguay QA Qatar RO Romania RS Serbia RU Russian Federation RW Rwanda SA Saudi Arabia SB Solomon Islands SC Seychelles SD Sudan SE Sweden SG Singapore SI Slovenia SK Slovakia SL Sierra Leone SM San Marino SN Senegal SO Somalia SR Suriname SS South Sudan ST Sao Tome and Principe SV El Salvador SX Sint Maarten SZ Eswatini TD Chad TL Timor-Leste TN Tunisia TR Türkiye TT Trinidad and Tobago UA Ukraine US United States of America UY Uruguay VC Saint Vincent and the Grenadines VE Venezuela VG Virgin Islands (British) VI Virgin Islands (U.S.) VN Viet Nam VU Vanuatu WS Samoa YE Yemen ZA South Africa ZM Zambia ZW Zimbabwe ```
# Carbon-as-a-Service Carbon-as-a-Service is an API solution that allows businesses to embed digital carbon credits across their products and services. # Request Retirement Retire credits by the gram and automatically top-up inventory if required {% hint style="success" %} Thallo removes the necessity for you to manually manage your carbon credit inventory, the Thallo system will take care of this for you. {% endhint %} {% hint style="danger" %} Calling this endpoint with a `sell_order_id` can cause carbon credits to be purchased from the market. **These purchases are final** and will be added to your monthly invoice. Use caution when building your logic and ensure accidental purchases cannot happen. {% endhint %} {% hint style="warning" %} Retirement requests cannot be undone. {% endhint %} ## Example cURL Request ```sh curl --request POST 'https://${BASE_URL}/api/caas/request-retirement' \ --header 'Authorization: Bearer ${API_KEY}' \ --header 'Content-Type: application/json' \ --data-raw '{ "quantity_grams": "20", "vintage_id": "004l7azww8l14bnxio", "sell_order_id": "006qhwycj9iruixah7", "expected_price_cents": "1023", "external_id": "a114f6ba-d7e4-40ad-aae2-8630bc2a7379", "should_retire_external_customer": true, "external_retiree_id": "7eece928-5a7a-4591-800a-4859635e4037", "external_retiree_name": "Alice Bob", "external_retiree_tax_id": "AB123456D", "external_retiree_location": "GB" }' ``` ## Endpoint Specification ## Retire credits by the gram and automatically top-up inventory if required `POST` `/api/caas/request-retirement` Earmark credits for retirement by the gram. Optionally include a `sell_order_id` and Thallo will automatically purchase the minimum amount of credits required to fulfil the retirement request, rounded up to the nearest whole tonne. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------- | | Authorization\* | string | Bearer API\_KEY | | Content-Type\* | string | application/json | #### Request Body | Name | Type | Description | | ------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | vintage\_id\* | string |

The vintage you would like to retire from. Vintages relate to a single project and so Thallo are able to determine the project you wish to retire from by the vintage\_id alone.

If there are adequate credits for this vintage\_id in your CaaS inventory these credits will be used first. You can omit the sell\_order\_id and expected\_price\_cents parameters as they will be ignored because no purchase is required.

| | quantity\_grams\* | string | The amount of credits, in grams, that you'd like to retire. | | external\_id\* | string |

This value must be unique for every request. If a 200 is returned and param external\_id\_already\_processed in response body is false the value specified in this field in request body can never be used again. This stops accidentally replaying the request multiple times.

If the same value is used after a successful request has been sent, Thallo will return the retirement request id the original request was associated to, the external\_id\_already\_processed property will be set to true so you are aware that no new purchase or retirement was created on this request - it was already processed on a previous request with the same external\_id.

| | sell\_order\_id | string |

Use the sell\_order\_ids from the Market endpoint to indicate which sell order to purchase from, if there are not enough credits in your inventory to fulfil the requirement request.

The vintage the sell order relates to must match the vintage\_id supplied in this request.

WARNING: supplying this parameter can cause carbon credits to be purchased from the market. These purchases are final and will be added to your monthly invoice.

Thallo will only purchase the minimum amount of credits required to fulfil the retirement request rounded up to a whole tonne.

| | expected\_price\_cents | string | This is an anti-slippage mechanism. Supply the price retrieved from the [Market](/api-endpoints/market) endpoint to ensure the price on the sell order has not changed since you read the data from the [Market](/api-endpoints/market). | | should\_retire\_external\_customer | boolean |

This indicates whether you want this retirement request to be made under your customer's name. If setting this to true, the quantity\_grams must be a multiple of 1,000,000 (i.e. whole tonnes) and the following parameters must be supplied: external\_retiree\_id, external\_retiree\_name,external\_retiree\_tax\_id, external\_retiree\_location.

When false, you can still supply the external retiree details and they will be displayed in the CaaS Dashboard]\() to indicate which of your users were included in which retirement request.

if true, there will be an individual retirement request on the CaaS Dashboard for that specific request.

| | external\_retiree\_id | string |

The identifier of the retiree in your internal systems.

This may be used in future Thallo features to allow analytics to run against your retirement request calls. This will allow grouping by the external\_retiree\_id to give insight into how your individual customers are utilising the Thallo integration.

If you do not wish to utilize this feature, you can set this to a non-blank string such as 'none'.

| | external\_retiree\_name | string | This is the name of your customer that will appear on the retirement certificate when `should_retire_external_customer` is set to `true` | | external\_retiree\_tax\_id | string | This is the Tax ID of your customer that is used during retirement | | external\_retiree\_location | string | This is the ISO 3166-1 alpha-2 country codes (2 character country codes) | {% tabs %} {% tab title="200: OK Returns the id of the retirement request that the credits have been added to" %} {% tabs %} {% tab title="Example" %} ```json { "retirement_request_id": "00mesxcknwjtz05lez", "external_id_already_processed": false } ``` {% endtab %} {% tab title="Schema" %} ```typescript { retirement_request_id: string external_id_already_processed: boolean } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="401: Unauthorized Your API key is unrecognized or inactive" %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 401, "message": "Unauthorized" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="403: User does not have `API User` role." %} {% tabs %} {% tab title="Example" %} ```json { "error": "Forbidden", "message": "Permission denied according to assigned roles.", "statusCode": 403 } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string error: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="422: Unprocessable Entity There was a problem processing the request" %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 422, "timestamp": "2023-06-11T09:23:27.078Z", "url": "/api/caas/request-retirement", "error": "FRAC_QUANT_INVALID_NUMBER", "message": "quantity_grams value \"abc\" is not a valid number" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number timestamp: string url: string error: string message: string | string[] } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500: Server error An unexpected error has occurred on the server." %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 500, "message": "Internal server error" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ### 422: Unprocessable Entity `error` types
Value from APIDescription
FRAC_QUANT_INVALID_NUMBERquantity_grams is not a valid number
FRAC_QUANT_LESS_THAN_EQ_ZEROquantity_grams must be greater than zero
SELL_ORDER_MISSING_EXP_PRICEIf sell_order_id is provided you must provide expected_price_cents
SELL_ORDER_EXP_PRICE_INVALID_NUMBERexpected_price_cents is not a valid number
SELL_ORDER_EXP_PRICE_LESS_THAN_EQ_ZEROexpected_price_cents must be greater than zero
VINTAGE_ID_NOT_EXISTSvintage_id not found
MISSING_SELL_ORDER_IDNot enough credits in inventory and sell_order_id was not specified so we are unable to purchase more. Please specify a sell_order_id to purchase from.
PRICE_SUPPLIED_DIFF_CURRENT_PRICEexpected_price_cents does not match the price on the sell_order_id. The price may have changed since the market data was last read. Please re-read the market data to get the up to date price for this sell order.
SELL_ORDER_NOT_EXISTSsell_order_id does not exist
SELL_ORDER_NOT_LIVEsell_order_id is no longer live. There are no credits remaining in this sell order or the sell order has been cancelled.
SELL_ORDER_SUPPLY_TOO_LOWsell_order_id does not contain enough credits
VINTAGE_SUPPLIED_DIFF_SELL_ORDER_VINTAGEThe vintage_id does not match the vintage on the specified sell_order_id
PURCHASE_OWN_CREDITSThe sell_order_id relates to a sell order that you own. You cannot buy credits that you already own.
MISSING_RETIREE_IDThe external_retiree_id Should be supplied when should_retire_external_customer is set to true
MISSING_RETIREE_DETAILSThe external_retiree_id, external_retiree_name, external_retiree_tax_id, external_retiree_location should all be either defined or undefined when should_retire_external_customer is false. If should_retire_external_customer is true, all of these values should be defined
### Location Codes: ```typescript { ALAND_ISLANDS = 'AX', ALBANIA = 'AL', ALGERIA = 'DZ', AMERICAN_SAMOA = 'AS', ANDORRA = 'AD', ANGOLA = 'AO', AFGHANISTAN = 'AF', ANGUILLA = 'AI', ANTARCTICA = 'AQ', ANTIGUA_AND_BARBUDA = 'AG', ARGENTINA = 'AR', ARMENIA = 'AM', ARUBA = 'AW', AUSTRALIA = 'AU', AUSTRIA = 'AT', AZERBAIJAN = 'AZ', BAHRAIN = 'BH', BAHAMAS = 'BS', BANGLADESH = 'BD', BARBADOS = 'BB', BELARUS = 'BY', BELGIUM = 'BE', BELIZE = 'BZ', BENIN = 'BJ', BERMUDA = 'BM', BHUTAN = 'BT', BOLIVIA = 'BO', BONAIRE = 'BQ', BOSNIA_AND_HERZEGOVINA = 'BA', BOTSWANA = 'BW', BOUVET_ISLAND = 'BV', BRAZIL = 'BR', BRITISH_INDIAN_OCEAN_TERRITORY = 'IO', BRUNEI_DARUSSALAM = 'BN', BULGARIA = 'BG', BURKINA_FASO = 'BF', BURUNDI = 'BI', CAMBODIA = 'KH', CAMEROON = 'CM', CANADA = 'CA', CAPE_VERDE = 'CV', CAYMAN_ISLANDS = 'KY', CENTRAL_AFRICAN_REPUBLIC = 'CF', CHAD = 'TD', CHILE = 'CL', CHINA = 'CN', CHRISTMAS_ISLAND = 'CX', COCOS_ISLANDS = 'CC', COLOMBIA = 'CO', COMOROS = 'KM', CONGO = 'CG', DEMOCRATIC_REPUBLIC_OF_CONGO = 'CD', COOK_ISLANDS = 'CK', COSTA_RICA = 'CR', IVORY_COAST = 'CI', CROATIA = 'HR', CUBA = 'CU', CURACAO = 'CW', CYPRUS = 'CY', CZECH_REPUBLIC = 'CZ', DENMARK = 'DK', DJIBOUTI = 'DJ', DOMINICA = 'DM', DOMINICAN_REPUBLIC = 'DO', ECUADOR = 'EC', EGYPT = 'EG', EL_SALVADOR = 'SV', EQUATORIAL_GUINEA = 'GQ', ERITREA = 'ER', ESTONIA = 'EE', ETHIOPIA = 'ET', FALKLAND_ISLANDS = 'FK', FAROE_ISLANDS = 'FO', FIJI = 'FJ', FINLAND = 'FI', FRANCE = 'FR', FRENCH_GUIANA = 'GF', FRENCH_POLYNESIA = 'PF', FRENCH_SOUTHERN_TERRITORIES = 'TF', GABON = 'GA', GAMBIA = 'GM', GEORGIA = 'GE', GERMANY = 'DE', GHANA = 'GH', GIBRALTAR = 'GI', GREECE = 'GR', GREENLAND = 'GL', GRENADA = 'GD', GUADELOUPE = 'GP', GUAM = 'GU', GUATEMALA = 'GT', GUERNSEY = 'GG', GUINEA = 'GN', GUINEA_BISSAU = 'GW', GUYANA = 'GY', HAITI = 'HT', HEARD_ISLAND_AND_MCDONALD_ISLANDS = 'HM', HOLY_SEE = 'VA', HONDURAS = 'HN', HONG_KONG = 'HK', HUNGARY = 'HU', ICELAND = 'IS', INDIA = 'IN', INDONESIA = 'ID', IRAN = 'IR', IRAQ = 'IQ', IRELAND = 'IE', ISLE_OF_MAN = 'IM', ISRAEL = 'IL', ITALY = 'IT', JAMAICA = 'JM', JAPAN = 'JP', JERSEY = 'JE', JORDAN = 'JO', KAZAKHSTAN = 'KZ', KENYA = 'KE', KIRIBATI = 'KI', NORTH_KOREA = 'KP', SOUTH_KOREA = 'KR', KUWAIT = 'KW', KYRGYZSTAN = 'KG', LAO_PEOPLES_DEMOCRATIC_REPUBLIC = 'LA', LATVIA = 'LV', LEBANON = 'LB', LESOTHO = 'LS', LIBERIA = 'LR', LIBYA = 'LY', LIECHTENSTEIN = 'LI', LITHUANIA = 'LT', LUXEMBOURG = 'LU', MACAO = 'MO', MACEDONIA = 'MK', MADAGASCAR = 'MG', MALAWI = 'MW', MALAYSIA = 'MY', MALDIVES = 'MV', MALI = 'ML', MALTA = 'MT', MARSHALL_ISLANDS = 'MH', MARTINIQUE = 'MQ', MAURITANIA = 'MR', MAURITIUS = 'MU', MAYOTTE = 'YT', MEXICO = 'MX', MICRONESIA = 'FM', MOLDOVA = 'MD', MONACO = 'MC', MONGOLIA = 'MN', MONTENEGRO = 'ME', MONTSERRAT = 'MS', MOROCCO = 'MA', MOZAMBIQUE = 'MZ', MYANMAR = 'MM', NAMIBIA = 'NA', NAURU = 'NR', NEPAL = 'NP', NETHERLANDS = 'NL', NEW_CALEDONIA = 'NC', NEW_ZEALAND = 'NZ', NICARAGUA = 'NI', NIGER = 'NE', NIGERIA = 'NG', NIUE = 'NU', NORFOLK_ISLAND = 'NF', NORTHERN_MARIANA_ISLANDS = 'MP', NORWAY = 'NO', OMAN = 'OM', PAKISTAN = 'PK', PALAU = 'PW', PALESTINE = 'PS', PANAMA = 'PA', PAPUA_NEW_GUINEA = 'PG', PARAGUAY = 'PY', PERU = 'PE', PHILIPPINES = 'PH', PITCAIRN = 'PN', POLAND = 'PL', PORTUGAL = 'PT', PUERTO_RICO = 'PR', QATAR = 'QA', RÉUNION = 'RE', ROMANIA = 'RO', RUSSIAN_FEDERATION = 'RU', RWANDA = 'RW', SAINT_BARTHÉLEMY = 'BL', SAINT_HELENA = 'SH', SAINT_KITTS_AND_NEVIS = 'KN', SAINT_LUCIA = 'LC', SAINT_MARTIN = 'MF', SAINT_PIERRE_AND_MIQUELON = 'PM', SAINT_VINCENT_AND_THE_GRENADINES = 'VC', SAMOA = 'WS', SAN_MARINO = 'SM', SAO_TOME_AND_PRINCIPE = 'ST', SAUDI_ARABIA = 'SA', SENEGAL = 'SN', SERBIA = 'RS', SEYCHELLES = 'SC', SIERRA_LEONE = 'SL', SINGAPORE = 'SG', SINT_MAARTEN = 'SX', SLOVAKIA = 'SK', SLOVENIA = 'SI', SOLOMON_ISLANDS = 'SB', SOMALIA = 'SO', SOUTH_AFRICA = 'ZA', SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS = 'GS', SOUTH_SUDAN = 'SS', SPAIN = 'ES', SRI_LANKA = 'LK', SUDAN = 'SD', SURINAME = 'SR', SVALBARD_AND_JAN_MAYEN = 'SJ', SWAZILAND = 'SZ', SWEDEN = 'SE', SWITZERLAND = 'CH', SYRIAN_ARAB_REPUBLIC = 'SY', TAIWAN = 'TW', TAJIKISTAN = 'TJ', TANZANIA = 'TZ', THAILAND = 'TH', TIMOR_LESTE = 'TL', TOGO = 'TG', TOKELAU = 'TK', TONGA = 'TO', TRINIDAD_AND_TOBAGO = 'TT', TUNISIA = 'TN', TURKEY = 'TR', TURKMENISTAN = 'TM', TURKS_AND_CAICOS_ISLANDS = 'TC', TUVALU = 'TV', UGANDA = 'UG', UKRAINE = 'UA', UNITED_ARAB_EMIRATES = 'AE', UNITED_KINGDOM = 'GB', UNITED_STATES = 'US', UNITED_STATES_MINOR_OUTLYING_ISLANDS = 'UM', URUGUAY = 'UY', UZBEKISTAN = 'UZ', VANUATU = 'VU', VENEZUELA = 'VE', VIET_NAM = 'VN', BRITISH_VIRGIN_ISLANDS = 'VG', U_S_VIRGIN_ISLANDS = 'VI', WALLIS_AND_FUTUNA = 'WF', WESTERN_SAHARA = 'EH', YEMEN = 'YE', ZAMBIA = 'ZM', ZIMBABWE = 'ZW', } ``` ## Purchases Thallo will purchase carbon credits from the specified `sell_order_id` when there are not enough credits remaining in your CaaS carbon credit inventory for the specified `vintage_id`. This removes the necessity for you to manually manage your inventory, the Thallo system will take care of this for you. This is an example flow of 2 retirement requests made against the same `vintage_id`: 1. Retirement request made with the following parameters: ```json { "quantity_grams": "20", "vintage_id": "004l7azww8l14bnxio", "sell_order_id": "006qhwycj9iruixah7", "expected_price_cents": "1023", "external_retiree_id": "7eece928-5a7a-4591-800a-4859635e4037", "external_id": "f9ff1e64-d578-4370-ae6b-e1e484b7108d" } ``` 2. You currently have zero credits for the project/vintage in your CaaS inventory and so Thallo will purchase one whole tonne from the specified `sell_order_id`. 3. The purchase is added to your monthly invoice and the credit is added to your CaaS inventory. 4. Now you have `1,000,000` grams for this vintage (1 tonne); `20` grams are added to your retirement request for this vintage for this month. Leaving you with `999,980` grams that can be used in future retirement requests for this vintage. 5. The retirement request id for this vintage for this month is returned. 6. You make a new retirement request for the same vintage: ```json { "quantity_grams": "42", "vintage_id": "004l7azww8l14bnxio", "sell_order_id": "006qhwycj9iruixah7", "expected_price_cents": "1023", "external_retiree_id": "7eece928-5a7a-4591-800a-4859635e4037", "external_id": "70b1443e-ce32-45e1-b0a3-4f1981921812" } ``` 7. You currently have `999,980` grams in your Caas inventory for this vintage - enough to fulfil the retirement request so no purchase is required. The `sell_order_id` and `expected_price_cents` are effectively ignored. 8. `42` grams are added to your retirement request for this vintage for this month. Leaving you with `999,938` grams that can be used in future retirement requests for this vintage. ## Anti Slippage It is possible that the price on the sell order changes between you reading the data from the [Market](/api-endpoints/market) and making the retirement request. By supplying the expected price this ensures you will pay the price you expect to pay for the credits. An error will be thrown if the expected price and the price on the sell order do not match. ## Invoicing All purchases are final and will be added to your monthly invoice. ## Processing Retirement Requests Retirement requests are processed once the invoice is settled for a given month. The retirements will then be processed by the [Thallo Two-Way Bridge](https://docs.thallo.io/) so the retirement is reflected on the blockchain as well as the underlying registry. Due to limitations on the underlying registries, retirements can only be processed on whole tonnes. Any remaining grams will be rolled over to next month's retirement request for this project/vintage. # Inventory See credits you own but haven't retired yet ## Overview Get information about the carbon credits you own that haven't been retired yet. You can also see the purchase history of each project/vintage. ## Example cURL Request ```sh curl --request GET 'https://${BASE_URL}/api/inventory?page=1&per_page=20' \ --header 'Authorization: Bearer ${API_KEY}' ``` ## Wallets Your inventory is held in "wallets". Each wallet has a type and is associated to a specific project and vintage. The only wallet type currently supported is `CAAS`, but more wallet types may be added in the future. ### Fractionalised Retirements The wallet data contains the quantity of carbon credits you own, in grams, that haven't yet been retired. This can occur when using the [Request Retirement](/api-endpoints/caas/requestretirement) and passing a value for `quantity_grams` that isn't in whole tonnes i.e. the value doesn't divide evenly by 1,000,000. This is known as a "fractionalised" retirement because you are requesting the retirement of a fraction of a tonne. Purchases are always made in whole tonnes. As an example, if you retire 750,000 (three quarters of a tonne) the system will purchase a whole tonne (1,000,000 grams) but only queue 750,000 grams for retirement. This is due to a limitation on the underlying registries where retirements can only occur in whole tonnes. In this example, you still own the remaining 250,000 grams but they will not be queued for retirement. You can use this end point to view those 250,000 grams. ## When To Use This Endpoint If you always retire in whole tonnes you do not need to use this endpoint as purchases are made on the fly at the same time as retirement so your inventory will always be zero. If you retire in fractions you may wish to check your inventory before purchasing more credits from the market so you use up your inventory first. ## Trade History The trade history supplied with each wallet is useful to see what prices you have paid for these credits in the past. For example, in a scenario where you sell credits to your own customers, you may take the last price paid for a specific project/vintage in order to determine what price to charge your own customers. This is in contrast to when you might use the market data which will have the current price. If we did not supply the trade history you wouldn't know what you paid for the credits and therefore you couldn't be sure what to charge your own customers. ## Endpoint Specification ## Get inventory for tenant `GET` `/api/inventory` Get information about the carbon credits you own that haven't been retired yet. You can also see the purchase history for each project/vintage. #### Query Parameters | Name | Type | Description | | --------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | page | number | For pagination. Which page would you like to be returned? The default value is 1. | | per\_page | number | For pagination. How many `project` results you would like per page. The default value is 20. | | trades\_per\_wallet | number | The number of trades shown per wallet. By default all trades are returned. The array is ordered by most recent trades at the top. | | trade\_type | string | Which types of trade to return. By default all types of trades are shown. Valid values are `BUY` and `SELL`. | | wallet\_min\_quantity | number | Defines the minimum available balance (in grams) a wallet must contain to be returned. By default, this value is 0 so it shows all wallets. Passing a value of 1 will return all non-zero wallets. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------- | | Authorization\* | string | `Bearer ${API_KEY}` | {% tabs %} {% tab title="200: OK " %} `price_cents` is per tonne. 1 tonne is 1,000,000 grams. Purchases are always made in whole tonnes. Prices are in USD cents. `quantity_grams` is the amount of credits, in grams, that you own that has not been retired. If a trade type is `BUY` the `quantity_grams` and `price_cents` is how much you purchased and at what price. If a trade type is `SELL` the `quantity_grams` and `price_cents` is how much you sold and at what price. Selling isn't currently possible for CaaS customers so you would only see `BUY` trade types. This may be a feature we implement in the future. {% tabs %} {% tab title="Example" %} ```json { "projects": [ { "project_id": "003ksr13jstw0zcq8g", "vintages": [ { "vintage_id": "0049zfm3m2vbnpxacv", "wallets": [ { "type": "CAAS", "quantity_grams": "999970", "trades": [ { "execution_date": "2023-08-16T11:16:00.643Z", "quantity_grams": "1000000", "price_cents": "4500", "type": "BUY" }, { "execution_date": "2023-08-16T09:10:12.062Z", "quantity_grams": "10000000", "price_cents": "2450", "type": "SELL" } ] } ] } ] } ], "pagination": { "per_page": 20, "total_pages": 1, "total_items": 1, "current_page": 1, "previous_page": null, "next_page": null } } ``` {% endtab %} {% tab title="Schema" %} ```typescript { projects: Array<{ project_id: string vintages: Array<{ vintage_id: string wallets: Array<{ type: string quantity_grams: string trades: Array<{ execution_date: string quantity_grams: string price_cents: string type: 'BUY' | 'SELL' }> }> }> }> pagination: { per_page: number total_pages: number total_items: number current_page: number previous_page: number next_page: number } } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="401: Unauthorized Your API key is unrecognized or inactive" %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 401, "message": "Unauthorized" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="403: User does not have `API User` role." %} {% tabs %} {% tab title="Example" %} ```json { "error": "Forbidden", "message": "Permission denied according to assigned roles.", "statusCode": 403 } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string error: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500: Server error An unexpected error has occurred on the server." %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 500, "message": "Internal server error" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} # Retirement Get retirement data by id After calling the [Request Retirement](/api-endpoints/caas/requestretirement) endpoint the response will contain a `retirement_request_id` which you can use in this endpoint to get access to the retirement data including status, the retirement certificate etc. ## Example cURL Request ```sh curl --request GET 'https://${BASE_URL}/api/retirement?id=00mj6hrvi6yaapj6nb' \ --header 'Authorization: Bearer ${API_KEY}' ``` ## Endpoint Specification ## Get the retirement request for a specific id `POST` `/api/retirement` See the status and other information about a specific retirement request. #### Query Parameters | Name | Type | Description | | ------------------------------------ | ------ | ------------------------------------------------------------ | | id\* | string | The id of the retirement request you want information about. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------- | | Authorization\* | string | Bearer API\_KEY | {% tabs %} {% tab title="200: OK Returns the information relating to the retirement request if it exists" %} `total_quantity` is the quantity of the retirement request in grams. `retirement_request_items.quantity` is the quantity requested in an individual call to POST `api/caas/request-retirement` in grams. There are 2 types of retirement request: `FRACTIONALISED` and `WHOLE`. For any requests made through the `api/caas/request-retirement` endpoint where the quantity is not whole tonnes, this type will be `FRACTIONALISED`. The `status` can have one of the following values: `OPEN` | `CLOSED` | `IN_PROGRESS` | `COMPLETE` | `NOTHING_TO_PROCESS` See below for more information on `status`. If the `id` supplied in the request does not match one of your retirement requests, the endpoint will throw a `422` error. {% tabs %} {% tab title="Example Retirement Response" %} ```json { "id": "00mj6hrvi6yaapj6nb", "status": "COMPLETE", "total_quantity": "10000000", "type": "WHOLE", "project_id": "003tcfgf70xwtr1dbc", "vintage_id": "004o7rnsz29fptz9uo", "created_at": "2024-02-05T10:51:12.319Z", "retired_at": "2024-02-08T11:46:48.245Z", "retired_serial_numbers": ["123456789", "abc123456"], "thallo_proof_of_retirement_certificate_url": "https://example.com/certificate.png", "should_retire_external_customer": true, "all_invoices_settled": true, "retirement_request_items": [ { "id": "00p6y5rap05wpwt7km", "quantity": "10000000", "created_at": "2024-02-05T10:51:12.319Z", "retiree_name": "Your Customer Ltd", "retiree_tax_id": "123456789", "retiree_country": "GB", "invoice_id": "00iy2jbppp8kwwg7vl", "trade_id": "00gr2tgn2wbq8barqs" } ] } ``` {% endtab %} {% tab title="Schema" %} ```typescript Object<{ id: string status: 'OPEN' | 'CLOSED' | 'IN_PROGRESS' | 'COMPLETE' | 'NOTHING_TO_PROCESS' total_quantity: string type: 'FRACTIONALISED' | 'WHOLE' project_id: string vintage_id: string created_at: string retired_at: string | undefined retired_serial_numbers: string[] | undefined thallo_proof_of_retirement_certificate_url: string | undefined should_retire_external_customer: boolean all_invoices_settled: boolean retirement_request_items: Array<{ id: string quantity: string created_at: string retiree_name: string | undefined retiree_tax_id: string | undefined retiree_country: Locations | undefined invoice_id: string | undefined trade_id: string | undefined }> }> ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="401: Unauthorized Your API key is unrecognized or inactive" %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 401, "message": "Unauthorized" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="403: User does not have `API User` role." %} {% tabs %} {% tab title="Example" %} ```json { "error": "Forbidden", "message": "Permission denied according to assigned roles.", "statusCode": 403 } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string error: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="422: Unprocessable Entity There was a problem processing the request" %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 422, "timestamp": "2023-06-11T09:23:27.078Z", "url": "/api/retirement", "error": "VALIDATION_ERROR", "message": ["id must be a string", "id should not be empty"] } ``` {% endtab %} {% tab title="Example retirement not found" %} ```json { "statusCode": 422, "timestamp": "2023-06-11T09:23:27.078Z", "url": "/api/retirement", "error": "NOT_FOUND", "message": "Retirement request not found with id 00mj6hrvi6yaapj6nh" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number timestamp: string url: string error: string message: string | string[] } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500: Server error An unexpected error has occurred on the server." %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 500, "message": "Internal server error" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ### 200: `status` Values
StatusDescription
OPENmeans that more credits can be added to this retirement request (this is only applicable for retirements where the `type` is `FRACTIONALISED`)
CLOSEDmeans that no additional credits can be added to this retirement request and it is pending settlement of one or more invoices before being set to IN_PROGRESS. This is not an end state.
IN_PROGRESSmeans that the retirement is being processed on the underlying registry and more credits cannot be added to this retirement request.
COMPLETEmeans that the retirement has been processed on the underlying registry and details such as retired_at, retired_serials, thallo_proof_of_retirement_certificate_url will be available.
NOTHING_TO_PROCESSmeans that the retirement request will not be processed as it has been closed and the total_quantity is 0. This happens in the unlikely event a retirement with a type of FRACTIONALISED contained less than 1 whole tonne.
### 422: Unprocessable Entity `error` types
`error`Description
VALIDATION_ERROROne or more validation rules has failed. e.g. id must be a string
NOT_FOUNDRetirement request not found with id 00mj6hrvi6yaapj6nh
# API Key Management ## List API Keys for your User ### Example cURL Request ```sh curl --request GET 'https://${BASE_URL}/api/api-keys' \ --header 'Authorization: Bearer ${API_KEY}' ``` ### Endpoint Specification ## Get your user `GET` `/api/api-keys` Get all of the API keys for your user #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------- | | Authorization\* | string | `Bearer ${API_KEY}` | {% tabs %} {% tab title="200: OK " %} {% tabs %} {% tab title="Example" %} ```json { "api_keys": [ { "id": "00n06yx75dzuxz2lgi", "name": "default api key", "created_at": "2023-06-09T06:34:37.685Z", "is_active": true } ] } ``` {% endtab %} {% tab title="Schema" %} ```typescript { api_keys: Array<{ id: string name: string created_at: string is_active: boolean }> } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="401: Unauthorized Your API key is unrecognized or inactive" %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 401, "message": "Unauthorized" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500: Server error An unexpected error has occurred on the server." %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 500, "message": "Internal server error" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ## Create an API Key {% hint style="info" %} You are allowed to have 2 active API keys per user at any one time {% endhint %} ### Example cURL Request ```sh curl --request POST 'https://${BASE_URL}/api/api-keys' \ --header 'Authorization: Bearer ${API_KEY}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "new api key", "deactivate_current": false }' ``` ### Endpoint Specification ## Create a new API key `POST` `/api/api-keys` Create a new API key and optionally deactivate the API key used to authenticate this request #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------- | | Authorization\* | string | `Bearer ${API_KEY}` | | Content-Type\* | string | application/json | #### Request Body | Name | Type | Description | | ----------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- | | name\* | string | The name associated with the new API key. | | deactivate\_current\* | boolean | Set to true if you wish to deactivate the key you use to authenticate this request. | {% tabs %} {% tab title="200: OK " %} {% tabs %} {% tab title="Example" %} ```json { "api_key": "18077981128785C05993E9C685FD52410BADCD994B3C1D0365A0C7088BA5BAC1" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { api_key: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="401: Unauthorized Your API key is unrecognized or inactive" %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 401, "message": "Unauthorized" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="403: User does not have `API User` role." %} {% tabs %} {% tab title="Example" %} ```json { "error": "Forbidden", "message": "Permission denied according to assigned roles.", "statusCode": 403 } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string error: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="422: Unprocessable Entity There was a problem processing the request" %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 422, "timestamp": "2023-06-11T09:23:27.078Z", "url": "/api/api-keys", "error": "MAX_KEYS_REACHED", "message": "You have reached the maximum active API keys for your user. Maximum: 2" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number timestamp: string url: string error: string message: string | string[] } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500: Server error An unexpected error has occurred on the server." %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 500, "message": "Internal server error" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} #### 422: Unprocessable Entity `error` types
Value from APIDescription
MAX_KEYS_REACHEDYou have reached the maximum active API keys for your user. Maximum: 2
## Deactivate an API Key {% hint style="info" %} It is possible to deactivate the key you use to authenticate the request to deactivate. This is for security purposes should your key be compromised. Be aware that if you deactivate your last key you will need to contact [support@thallo.io](mailto:support@thallo.io?subject=Thallo%20API%20New%20API%20Key%20Request) to request a new one. {% endhint %} ### Example cURL Request ```sh curl --request DELETE 'https://${BASE_URL}/api/api-keys/${API_KEY_ID}' \ --header 'Authorization: Bearer ${API_KEY}' ``` ### Endpoint Specification ## Deactivate an API key `DELETE` `/api/api-keys/${API_KEY_ID}` Deactivate an API key by its id #### Path Parameters | Name | Type | Description | | ---------------------------------------------- | ------ | --------------------------------------------------- | | API\_KEY\_ID\* | string | The id of the API key you would like to deactivate. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------- | | Authorization\* | string | `Bearer ${API_KEY}` | {% tabs %} {% tab title="200: OK There is no body returned from this endpoint" %} {% endtab %} {% tab title="401: Unauthorized Your API key is unrecognized or inactive" %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 401, "message": "Unauthorized" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="422: Unprocessable Entity There was a problem processing the request" %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 422, "timestamp": "2023-06-11T09:23:27.078Z", "url": "/api/api-keys", "error": "API_KEY_NOT_EXISTS", "message": "Api key not found" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number timestamp: string url: string error: string message: string | string[] } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500: Server error An unexpected error has occurred on the server." %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 500, "message": "Internal server error" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} #### 422: Unprocessable Entity `error` types
Value from APIDescription
API_KEY_NOT_EXISTSApi key not found
# How To Authenticate ## API Key Management Please see the [API Key Management](/api-endpoints/apikeymanagement) section for details. ## Authenticating Each request requires that you provide an `Authorization` header with a value in this format: `Bearer API_KEY`. Replace `API_KEY` with your API key. ## Getting your API Key Please see the [Welcome to the Thallo API](/) section for details. # Environments ## URLs Please contact your account manager or [support@thallo.io](mailto:support@thallo.io?subject=Thallo%20API%20Environment%20Access%20Request) to retrieve the base URL. ## Test Environment A sandbox environment is available, please request access from [support@thallo.io](mailto:support@thallo.io?subject=Thallo%20API%20Test%20Environment%20Access%20Request)