> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datanumia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API usage

## API Security and Authentication

The brAIn API suite is secured using AWS Cognito. All API calls require authentication to ensure secure and authorized access to data and functionalities.

### Authentication Flow: OAuth 2.0 Client Credentials Grant

Partners and their applications will authenticate with the brAIn APIs using the OAuth 2.0 Client Credentials Grant flow. This flow is suitable for server-to-server communication where the client application itself is authenticating.

To obtain an access token (JWT), you must make a POST request to the token endpoint:

### Token Endpoint URL QA

[https://auth-recometrics-partners.qa.datanumia.com/oauth2/token](https://auth-recometrics-partners.qa.datanumia.com/oauth2/token)

### Token example QA

```json theme={null}
curl -s -H "Content-Type: application/x-www-form-urlencoded" -X POST -u 'xxx:yyy' https://auth-recometrics-partners.qa.datanumia.com/oauth2/token \
 --data-urlencode 'grant_type=client_credentials' --data-urlencode 'scope=qa-b2b-brain-user-poolrs/api.read qa-b2b-brain-user-poolrs/api.write'
```

### Token Endpoint URL Prod

[https://auth-recometrics-partners.datanumia.com/oauth2/token](https://auth-recometrics-partners.datanumia.com/oauth2/token)

### Token example PROD

```json theme={null}
curl -s -H "Content-Type: application/x-www-form-urlencoded" -X POST -u 'xxx:yyy' https://auth-recometrics-partners.datanumia.com/oauth2/token \
 --data-urlencode 'grant_type=client_credentials' --data-urlencode 'scope=b2b-brain-user-poolrs/api.read b2b-brain-user-poolrs/api.write'
```

**Request Details:**

HTTP Method: `POST`

**Body Parameters:**

Your unique `client_id` & `client_secret` provided by Datanumia.

### Using the Access Token

Once you receive the access\_token, you must include it in the Authorization header of all subsequent API requests.

Header Name: `Authorization`

Header Value Format: `Bearer [YOUR_ACCESS_TOKEN]`

## API Endpoints Overview

The brAIn API suite is logically separated into distinct services, each accessible via its own base URL and responsible for specific functionalities:

### Simulation API

[https://brain-simulation-api.datanumia.com/v1/advices](url)

This is the core API for energy consulting simulations. It allows partners to submit client and housing characteristics data to receive personalized energy equipment and service recommendations, along with estimated savings (financial, energy, CO2), payback periods, and eligibility scores.

You can access a QA environement at
[https://brain-simulation-api.qa.datanumia.com/v1/advices](url)

This endpoint accepts multiple parameters that allow for fine-tuning the simulation.

**Here are the main input variables:**

| Variable name | Description | Type | Data |
| - | - | - | - |
| AMORTIZATION\_METHOD | Amortization calculation method used for ROI computations | ENUM | Enum: FIXED\_PRICE, PRICE\_EVOLUTION |
| COUNTRY | Country code / country identifier | STRING | ISO-like country string |
| CUSTOMER\_AFFINITY | Customer affinity segment | ENUM | Enum: BUDGET, INVESTMENT, PERFORMANCE |
| DOOR\_COST | Estimated door replacement/insulation cost | DECIMAL | € |
| DOOR\_HEATING\_CONSUMPTION\_SAVINGS\_RATE | Expected heating savings rate from door work | DECIMAL | Ratio (0–1) |
| DOOR\_TO\_INSULATE\_QUANTITY | Number of doors to insulate/replace | INT | ≥ 0 |
| DOOR\_TARGET\_MATERIAL\_TYPE | Target door material | ENUM | Enum: PVC, ALU |
| DOOR\_TARGET\_TYPE | Target door type | ENUM | Enum: UNGLAZED\_DOOR, SEMI\_GLAZED\_DOOR, FULLY\_GLAZED\_DOOR |
| ELECTRIC\_VEHICLE\_BATTERY\_CAPACITY | EV battery capacity | DECIMAL | kWh |
| ELECTRIC\_VEHICLE\_HOUSING\_RECHARGE\_PRICE | Home charging electricity price for EV | DECIMAL | € |
| ELECTRIC\_VEHICLE\_PUBLIC\_CHARGING\_PRICE | Public charging electricity price for EV | DECIMAL | €/kWh |
| ELECTRIC\_VEHICLE\_RECHARGE\_BREAKDOWN | Charging distribution (home/public) | OBJECT | HOUSING : DECIMAL, FREE : DECIMAL, PUBLIC : DECIMAL |
| ELECTRIC\_VEHICLE\_RECHARGE\_PERCENTAGE | Charging share assumption | DECIMAL | Ratio / % |
| ELECTRIC\_VEHICLE\_RECHARGE\_TIME | Target recharge time | DECIMAL | minutes |
| ELECTRICITY\_CO2\_EMISSION\_FACTOR | Electricity CO2 emission factor | DECIMAL | kg/kWh |
| ELECTRICITY\_PRICE | Electricity unit price | DECIMAL | €/kWh |
| ELECTRICITY\_POINT\_OF\_DELIVERY | Electricity meter identifier | STRING | Identifier |
| ELECTRICITY\_SELLING\_PRICE | Electricity resale price | DECIMAL | €/kWh |
| GAS\_CO2\_EMISSION\_FACTOR | Gas CO2 emission factor | DECIMAL | kg/kWh |
| GAS\_PRICE | Gas unit price | DECIMAL | €/kWh |
| HEAT\_PUMP\_REQUIRED\_ELECTRICITY\_POWER | Required electrical power for heat pump | DECIMAL | kW |
| HEAT\_PUMP\_SUBVENTION | Heat pump subsidy | DECIMAL | € |
| ENEDIS\_CLIENT\_CONSENT | Customer consent for Enedis data usage | BOOL | true / false |
| HOUSING\_ALTITUDE | Housing altitude | INT | meters |
| HOUSING\_ATTIC\_SURFACE | Attic surface | DECIMAL | m² |
| HOUSING\_ATTIC\_TYPE | Attic type | ENUM | Enum: CONVERTED, LOST, NONE |
| HOUSING\_BASE\_TEMPERATURE | Base calculation temperature | INT | °C |
| HOUSING\_CEILING\_HEIGHT | Average ceiling height | DECIMAL | meters |
| HOUSING\_CONSTRUCTION\_YEAR | Construction year | INT | YYYY |
| HOUSING\_DOOR\_RENOVATED | Doors renovated | BOOL | true / false |
| HOUSING\_ELECTRIC\_CONNECTION | Electrical connection type | ENUM | Enum: SINGLE\_PHASE, THREE\_PHASE |
| HOUSING\_EVSE\_MAX\_POWER | Max EV charging power | DECIMAL | kW |
| HOUSING\_EVSE\_TYPE | EV charging equipment type | ENUM | Enum: NONE, HOUSING\_PLUG, REINFORCED\_PLUG, STATION |
| HOUSING\_FUEL\_PRICE | Heating fuel unit price | DECIMAL | €/L |
| HOUSING\_HEATING\_SEASON\_OUTDOOR\_TEMPERATURE | Outdoor temperature during heating season | DECIMAL | °C |
| HOUSING\_HEATING\_SETPOINT\_TEMPERATURE | Heating temperature setpoint | DECIMAL | °C |
| HOUSING\_INDOOR\_ROOF\_SURFACE | Indoor roof surface | DECIMAL | m² |
| HOUSING\_INSULATION\_FACTOR | Global insulation factor | DECIMAL | W/(m³.°C) |
| HOUSING\_INSULATION\_LEVEL | Global insulation level | ENUM | Enum: NEW\_BUILDING, EXCELLENT, GOOD, NORMAL, OLD\_BUILDING |
| HOUSING\_INSULATION\_WORK\_PERFORMED | Global insulation work performed | BOOL | true / false |
| HOUSING\_JOINERY\_HEATING\_CONSUMPTION\_SAVINGS\_MAX\_RATE | Max savings rate from joinery | DECIMAL | Ratio (0–1) |
| HOUSING\_JOINERY\_INSULATION\_SUBVENTION | Joinery insulation subsidy | DECIMAL | € |
| HOUSING\_LAST\_YEAR\_ELECTRICITY\_CONSUMPTION | Electricity consumption last year | DECIMAL | kWh |
| HOUSING\_LAST\_YEAR\_GAS\_HEATING\_CONSUMPTION | Gas heating consumption last year | DECIMAL | kWh |
| HOUSING\_LAST\_YEAR\_GAS\_SANITARY\_HOT\_WATER\_CONSUMPTION | Gas hot water consumption last year | DECIMAL | kWh |
| HOUSING\_LAST\_YEAR\_MAX\_POWER | Max power reached last year | DECIMAL | kW |
| HOUSING\_LAST\_YEAR\_SUMMER\_AVERAGE\_DAILY\_ELECTRICITY\_CONSUMPTION | Avg daily summer consumption | DECIMAL | kWh |
| HOUSING\_MAXIMUM\_ROOF\_EXPLOITABLE\_LENGTH | Max exploitable roof length | DECIMAL | meters |
| HOUSING\_MAXIMUM\_ROOF\_EXPLOITABLE\_PERCENTAGE | Max usable roof share | DECIMAL | Ratio / % |
| HOUSING\_MAXIMUM\_ROOF\_EXPLOITABLE\_WIDTH | Max exploitable roof width | DECIMAL | meters |
| HOUSING\_MUNICIPALITY\_DENSITY\_TYPE | Municipality density type | ENUM | Enum: MAJOR\_URBAN\_CENTRE, MIDDLE\_URBAN\_CENTRE, SMALL\_TOWN, URBAN\_BELT, RURAL\_TOWN, RURAL\_AREA\_WITH\_DISPERSED\_SETTLEMENTS, RURAL\_AREA\_WITH\_VERY\_DISPERSED\_SETTLEMENTS |
| HOUSING\_NUMBER\_OF\_ROOMS | Number of rooms | INT | ≥ 1 |
| HOUSING\_OCCUPATION\_STATUS | Occupation status | ENUM | Enum: OWNER, TENANT |
| HOUSING\_ORIENTATION | Main orientation | ENUM | Enum: EAST, WEST, NORTH, SOUTH, SOUTH\_EAST, SOUTH\_WEST, NORTH\_EAST, NORTH\_WEST |
| HOUSING\_OUTDOOR\_ROOF\_SURFACE | Outdoor roof surface | DECIMAL | m² |
| HOUSING\_PRINCIPAL\_HEATING\_DISTRIBUTION\_SYSTEM | Heating distribution system | ENUM | Enum: UNDERFLOOR\_HEATING, RADIATOR, HEAT\_PUMP, OTHER |
| HOUSING\_PRINCIPAL\_HEATING\_DISTRIBUTION\_SYSTEM\_ENERGY\_SOURCE | Distribution energy source | ENUM | Enum: ELECTRICITY, HIGH\_TEMPERATURE\_WATER, LOW\_TEMPERATURE\_WATER, OTHER |
| HOUSING\_PRINCIPAL\_HEATING\_PRODUCTION\_SYSTEM | Heating production system | ENUM | Enum: BOILER, HEAT\_PUMP, RADIATOR, OTHER |
| HOUSING\_PRINCIPAL\_HEATING\_PRODUCTION\_SYSTEM\_AGE | Heating system age | DECIMAL | years |
| HOUSING\_PRINCIPAL\_HEATING\_PRODUCTION\_SYSTEM\_COP | Heating system COP | DECIMAL | Unitless |
| HOUSING\_PRINCIPAL\_HEATING\_PRODUCTION\_SYSTEM\_ENERGY\_SOURCE | Heating energy source | ENUM | Enum: GAS, ELECTRICITY, FUEL, OTHER |
| HOUSING\_PRINCIPAL\_HEATING\_SYSTEM\_SURFACE | Heated surface | DECIMAL | m² |
| HOUSING\_PRINCIPAL\_HEATING\_SYSTEM\_VOLUME | Heated volume | DECIMAL | m³ |
| HOUSING\_REQUIRED\_ELECTRICITY\_HEATING\_POWER | Required heating electrical power | DECIMAL | kW |
| HOUSING\_REQUIRED\_HEATING\_POWER\_PER\_SQUARE\_METER | Required heating power per m² | DECIMAL | W |
| HOUSING\_RESIDENCE\_TYPE | Residence type | ENUM | Enum: MAIN, SECONDARY |
| HOUSING\_ROOF\_LENGTH | Roof length | DECIMAL | meters |
| HOUSING\_ROOF\_RENOVATED | Roof renovated | BOOL | true / false |
| HOUSING\_ROOF\_SLOPE | Roof slope | DECIMAL | degrees |
| HOUSING\_ROOF\_WIDTH | Roof width | DECIMAL | meters |
| HOUSING\_SANITARY\_HOT\_WATER\_MANAGEMENT | Central hot water management | BOOL | true / false |
| HOUSING\_SANITARY\_HOT\_WATER\_PRODUCTION\_SYSTEM\_ENERGY\_SOURCE | Hot water energy source | ENUM | Enum: GAS, ELECTRICITY, FUEL, OTHER |
| HOUSING\_SHUTTERS\_RENOVATED | Shutters renovated | BOOL | true / false |
| HOUSING\_SUBSCRIBED\_POWER | Subscribed electrical power | INT | kVA |
| HOUSING\_SUBSCRIBED\_POWER\_TARGET | Target subscribed power | INT | kVA |
| HOUSING\_SWIMMING\_POOL\_PRESENCE | Swimming pool presence | BOOL | true / false |
| HOUSING\_TOTAL\_SURFACE | Total living surface | DECIMAL | m² |
| HOUSING\_TYPE | Housing type | ENUM | Enum: APARTMENT, HOUSE |
| HOUSING\_WALL\_RENOVATED | Wall renovated | BOOL | true / false |
| HOUSING\_WINDOWS\_RENOVATED | Windows renovated | BOOL | true / false |
| HOUSING\_YEARLY\_BOILER\_CONSUMPTION | Boiler energy consumption | DECIMAL | kWh |
| HOUSING\_YEARLY\_BOILER\_CONSUMPTION\_COST | Boiler yearly cost | DECIMAL | € |
| HOUSING\_YEARLY\_BOILER\_FUEL\_CONSUMPTION | Boiler fuel consumption | DECIMAL | L |
| HOUSING\_YEARLY\_ELECTRICITY\_CONSUMPTION\_COST | Yearly electricity cost | DECIMAL | € |
| HOUSING\_YEARLY\_ELECTRICITY\_SUBSCRIPTION\_COST | Yearly subscription cost | DECIMAL | € |
| HOUSING\_YEARLY\_ELECTRICITY\_TOTAL\_COST | Total yearly electricity cost | DECIMAL | € |
| HOUSING\_YEARLY\_HEATING\_CONSUMPTION | Yearly heating consumption | DECIMAL | kWh |
| HOUSING\_YEARLY\_HEATING\_CONSUMPTION\_COST | Yearly heating cost | DECIMAL | € |
| HOUSING\_ZIP\_CODE | Postal code | STRING | 5 digits (FR) |
| MECHANICAL\_VENTILATION\_SYSTEM\_TYPE | Ventilation system type | ENUM | Enum: SINGLE\_FLOW, DOUBLE\_FLOW, NONE |
| MECHANICAL\_VENTILATION\_SYSTEM\_INSTALLATION\_SUBVENTION | Ventilation subsidy | DECIMAL | € |
| PATIO\_DOOR\_COST | Patio door cost | DECIMAL | € |
| PATIO\_DOOR\_HEATING\_CONSUMPTION\_SAVINGS\_RATE | Patio door savings rate | DECIMAL | Ratio (0–1) |
| PATIO\_DOOR\_TO\_INSULATE\_QUANTITY | Patio door quantity | INT | ≥ 0 |
| PATIO\_DOOR\_TARGET\_MATERIAL\_TYPE | Patio door material | ENUM | Enum: PVC, ALU |
| PATIO\_DOOR\_CASEMENT\_QUANTITY | Patio door casement quantity | INT | ≥ 0 |
| RECHARGED\_VEHICLE\_BATTERY\_CAPACITY | Recharged vehicle battery capacity | DECIMAL | kWh |
| REFERENCE\_COOLING\_TEMPERATURE | Reference cooling temperature | INT | °C |
| REPLACE\_THERMAL\_VEHICLE\_WITH\_ELECTRIC\_VEHICLE\_SUBVENTION | EV replacement subsidy | DECIMAL | € |
| ROAD\_TYPE\_BREAKDOWN | Road type distribution | OBJECT | Distribution by type of road of journeys made by car over one year (sum between 0 & 1). CITY : DECIMAL, COUNTRYSIDE : DECIMAL, HIGHWAY : DECIMAL |
| ROOF\_INSULATION\_SUBVENTION | Roof insulation subsidy | DECIMAL | € |
| SOLAR\_PANEL\_INSTALLATION\_SUBVENTION | Solar panel subsidy | DECIMAL | € |
| SOLAR\_PANEL\_INSTALLATION\_ZONE | PV installation zone | ENUM | Enum: ROOF, NONE |
| SOLAR\_PANEL\_INSTALLATION\_ZONE\_TARGET | Target PV installation zone | ENUM | Enum: ROOF, NONE |
| SOLAR\_PANEL\_SELF\_CONSUMPTION\_RATE | Self-consumption rate | DECIMAL | Ratio (0–1) |
| SOLAR\_PANEL\_TYPE | Solar panel type | ENUM | Enum: PHOTOVOLTAIC, NONE |
| SHUTTER\_COST | Shutter cost | DECIMAL | € |
| SHUTTER\_HEATING\_CONSUMPTION\_SAVINGS\_RATE | Shutter savings rate | DECIMAL | Ratio (0–1) |
| SHUTTER\_TO\_INSULATE\_QUANTITY | Shutter quantity | INT | ≥ 0 |
| SHUTTER\_TARGET\_MATERIAL\_TYPE | Shutter material | ENUM | Enum: PVC, ALU |
| SHUTTER\_TARGET\_TYPE | Shutter type | ENUM | Enum: SWING\_SHUTTER, ROLLING\_SHUTTER, LOUVERED\_SHUTTER |
| THERMAL\_VEHICLE\_ENERGY\_COST | Thermal vehicle energy cost | DECIMAL | €/L |
| UPGRADE\_EVSE\_SUBVENTION | EVSE upgrade subsidy | DECIMAL | € |
| VEHICLE\_CONSUMPTION\_BREAKDOWN | Vehicle consumption breakdown | OBJECT | CITY : DECIMAL, COUNTRYSIDE : DECIMAL, HIGHWAY : DECIMAL |
| VEHICLE\_CONSUMPTION\_BREAKDOWN\_TARGET | Vehicle consumption breakdown target | OBJECT | CITY : DECIMAL, COUNTRYSIDE : DECIMAL, HIGHWAY : DECIMAL |
| VEHICLE\_ENERGY\_SOURCE | Vehicle energy source | ENUM | Enum: PETROL, DIESEL, ELECTRICITY, OTHER |
| VEHICLE\_REGISTRATION\_YEAR | Registration year | INT | YYYY |
| VEHICLE\_TYPE | Vehicle type | ENUM | Enum: MINI\_CITY\_CAR, CITY\_CAR, COMPACT, FAMILY\_SEDAN, ROAD\_SEDAN, MONOSPACE, SUV, LUDOSPACE, NONE |
| VEHICLE\_TYPE\_TARGET | Target vehicle type | ENUM | Enum: MINI\_CITY\_CAR, CITY\_CAR, COMPACT, FAMILY\_SEDAN, ROAD\_SEDAN, MONOSPACE, SUV, LUDOSPACE, NONE |
| VEHICLE\_YEARLY\_CONSUMPTION | Yearly vehicle consumption | DECIMAL | L |
| VEHICLE\_YEARLY\_TRAVELLED\_DISTANCE | Yearly travelled distance | DECIMAL | km |
| VEHICLE\_YEARLY\_TRAVELLED\_DISTANCE\_BREAKDOWN | Travel distance breakdown | OBJECT | CITY : INT, COUNTRYSIDE : INT, HIGHWAY : INT |
| WALL\_INSULATION\_SUBVENTION | Wall insulation subsidy | DECIMAL | € |
| WINDOW\_COST | Window cost | DECIMAL | € |
| WINDOW\_HEATING\_CONSUMPTION\_SAVINGS\_RATE | Window savings rate | DECIMAL | Ratio (0–1) |
| WINDOW\_CASEMENT\_QUANTITY | Window casement quantity | INT | ≥ 0 |
| WINDOW\_TO\_INSULATE\_QUANTITY | Window quantity | INT | ≥ 0 |
| WINDOW\_TARGET\_MATERIAL\_TYPE | Window material | ENUM | Enum: ALU, PVC |

### Administration API

[brain-admin-api.datanumia.com](url)

This API is dedicated to the management of client data and custom variables. It allows partners to retrieve, create, update, and delete client profiles. It also handles the configuration and retrieval of custom parameters specific to each commercial partner (e.g., tariff rates,electrcity price...).

### Biling

[brain-billing-api.datanumia.com](url)

This API provides functionalities for tracking and administration of billing related to the recometrics service usage. It allows Datanumia and potentially partners to monitor API consumption, generate billing reports, and manage subscription details.

A comprehensive Swagger (OpenAPI) specification for all Recometrics APIs is available at the bottom of this documentation. This specification provides detailed information on all endpoints, models, and authentication mechanisms, allowing for easy exploration and testing.