> ## Documentation Index > Fetch the complete documentation index at: https://developers.manglai.io/llms.txt > Use this file to discover all available pages before exploring further. # Create or update a consumption record > Creates a new consumption record or updates an existing one. For more information and see how to use this endpoint, see: https://manglai.notion.site/Consumptions-2af89a8b970b806e8359e8446b67f32e ## OpenAPI ````yaml /openapi.json post /api/v1/consumptions openapi: 3.0.3 info: title: Manglai Public API description: Manglai API for Carbon Footprint Management contact: email: admin@manglai.io name: Manglai Support url: https://manglai.io termsOfService: https://manglai.io/privacy version: '1.0' servers: - url: https://www.manglai.io description: Production security: - apiTokenAuth: [] tags: [] paths: /api/v1/consumptions: post: tags: - consumptions summary: Create or update a consumption record description: > Creates a new consumption record or updates an existing one. For more information and see how to use this endpoint, see: https://manglai.notion.site/Consumptions-2af89a8b970b806e8359e8446b67f32e requestBody: required: true content: application/json: schema: type: object required: - id - entityId - categoryId - startDate - endDate - companyId - buildingId - quantity - unitType properties: id: type: string description: Unique identifier (UUID) for the consumption record example: 550e8400-e29b-41d4-a716-446655440000 entityId: type: string description: > Foreign key reference to the source entity (UUID): - **For invoices:** invoice ID from `GET /api/v1/invoices` - **For vehicles:** vehicle ID from `GET /api/v1/vehicles?companyId={companyId}`. The vehicle must exist and be available during the consumption period. - **For surveys:** survey answer ID example: invoice-123-abc categoryId: type: string description: > GHG Protocol category ID (UUID). Call `GET /api/v1/categories?level=subcategory` to obtain the list and send the selected `id`. - Vehicle categories: LAND_TRANSPORTATION, AIR_TRANSPORTATION, MARITIME_TRANSPORTATION, RAIL_TRANSPORTATION, FORESTRY_MACHINERY, FARM_MACHINERY, INDUSTRIAL_MACHINERY example: 668f3fcb-7fb0-4b65-b77d-9303c551632f startDate: type: string format: date-time description: Start date of the consumption period (ISO 8601) example: '2024-01-01T00:00:00.000Z' endDate: type: string format: date-time description: End date of the consumption period (ISO 8601) example: '2024-01-31T23:59:59.999Z' companyId: type: string description: > Company identifier (UUID). Retrieve it via `GET /api/v1/companies` and use the returned `id`. example: 1b1e07a7-083d-4831-a1d2-84b6e93a1572 buildingId: type: string description: > Building identifier (UUID). Call `GET /api/v1/companies/{companyId}/buildings?companyId={companyId}` and use the building `id`. **For vehicle consumptions:** If the vehicle has a `buildingId` assigned, you can use that value. Otherwise, use a building from the company. example: 7fef7760-f9e7-4de9-ae35-8c37db65e4a3 quantity: type: number description: Quantity consumed (e.g., kWh, liters, km) example: 1500.5 unitType: type: string description: > Unit of measurement for the quantity. Common values: kWh, MWh, m3, l, km, kg, mt example: kWh provider: type: string description: > Provider/supplier code. For electricity consumptions call `GET /api/v1/inputs/recommended?companyId={companyId}&types=provider&countryCode={countryCode}` and send the `code`. **Required for vehicle consumptions:** If vehicle `motorType` is `electric` or `hybrid`, this field is mandatory. example: endesa amount: type: number description: Cost amount (excluding taxes if applicable) example: 250.75 totalCost: type: number description: Total cost including all charges example: 312.5 currency: type: string description: Currency code (ISO 4217) example: EUR emissionEntityId: type: string description: > Custom emission factor ID (UUID). Obtain it via `GET /api/v1/emission-factors/custom?companyId={companyId}&entityName={entityName}&countryCode={countryCode}`. example: 218b2369-b86d-4517-a9f0-392d5f9e80e3 countryCode: type: string description: ISO country code (e.g., ES, FR, US) example: ES fuelType: type: string description: > Fuel code. For combustion consumptions call `GET /api/v1/inputs/recommended?companyId={companyId}&types=fuel&countryCode={countryCode}`. For gas leaks use `types=gasLeak`. Send the `code`. **Required for vehicle consumptions:** If vehicle `motorType` is `combustion` or `hybrid`, this field must be provided in `extraData.fuelTypeId` or `extraData.fuelTypeCode`. example: diesel vehicleType: type: string description: > Vehicle type code. **For vehicle consumptions:** This should be included in `extraData.vehicleCategory` with the vehicle category code. Vehicle types: `vehicle`, `machine`, `transport` example: vehicle emission: type: object description: >- Pre-calculated emission data (optional, usually system-calculated) extraData: type: object description: > Additional metadata specific to the consumption type. May include: concept, gdo, renewablePercentage, wasteType, etc. properties: fuelType: type: string fuelTypeId: type: string description: > Fuel type ID (UUID). **For vehicle consumptions with combustion/hybrid motorType:** Required. Use the `id` from `GET /api/v1/inputs/recommended?types=fuel` fuelTypeCode: type: string description: > Fuel type code. **For vehicle consumptions:** Alternative to `fuelTypeId`, use the `code` from the fuel input. vehicleType: type: string vehicleCategory: type: string description: > Vehicle category code. **For vehicle consumptions:** Include the vehicle category code from the vehicle's `vehicleCategoryId`. unit: type: string description: Unit of measurement (same as `unitType` at root level) emission: type: object gdo: type: string renewablePercentage: type: number wasteType: type: string description: > Waste type code. For waste consumptions call `GET /api/v1/inputs/recommended?companyId={companyId}&types=waste&countryCode={countryCode}` and send the `code`. wasteDisposalMethod: type: string description: > Waste disposal method code. Available in the waste inputs response or company waste configuration. attachedFilePath: type: string description: Path to attached file (e.g., invoice PDF) example: gs://bucket/company/invoice.pdf efficiency: type: object description: > Efficiency data (optional). **For vehicle consumptions:** Can include distance and energy consumption data. Structure: `{ distance: number, distanceUnit: string, energy: number, energyUnit: string }` properties: distance: type: number description: Distance traveled (if applicable) distanceUnit: type: string description: Unit for distance (e.g., "km") energy: type: number description: Energy consumed (if applicable) energyUnit: type: string description: Unit for energy (e.g., "kWh", "l") externalId: type: string description: External system identifier for integration purposes example: EXT-2024-001 relationalId: type: string description: Identifier to relate multiple consumptions example: batch-123 updateByExternalId: type: boolean description: > If true, updates existing consumption by externalId instead of id. Useful for integrations that don't know internal IDs. example: false emissionsCategoryIds: type: array description: > Array of category IDs (UUID) for multi-category emissions. Retrieve IDs via `GET /api/v1/categories?level=subcategory`. **For general consumptions (optional):** Used when a consumption should generate emissions in multiple categories (e.g., electricity + energy-related-activities). **For vehicle consumptions (required):** Must always include two categories: - Primary category (same as `categoryId`) - Related activity category: - Electric/Hybrid vehicles: `ENERGY_RELATED_ACTIVITIES` (47cb52b3-02e6-446e-bd70-e46316aa876b) - Combustion vehicles: `FUEL_RELATED_ACTIVITIES` (dd16800c-c79f-4717-9de6-07e15f4ceb64) items: type: string example: - 493782d7-7c17-4ed6-b75c-4fae0e254ff2 - 47cb52b3-02e6-446e-bd70-e46316aa876b isRecalculated: type: boolean description: > If true, bypasses duplicate validation (used for recalculation flows) example: false validation: type: object description: Validation metadata (timestamps, validator info) removedAt: type: string format: date-time description: Soft delete timestamp (null if active) example: null description: Consumption data to be inserted or updated responses: '200': description: Consumption successfully created/updated and emissions calculated content: application/json: schema: type: object properties: status: type: string example: ok isUpdated: type: boolean description: True if an existing record was updated example: false isCreated: type: boolean description: True if a new record was created example: true '400': description: > Bad request — validation errors: - Invalid date range (startDate > endDate) - Missing required fields - Invalid category or building/vehicle IDs '409': description: > Conflict — consumption already exists with same parameters: - Same companyId, buildingId, entityId, categoryId - Same startDate, endDate, quantity, provider Error code: CONSUMPTION_ALREADY_EXIST '422': description: > Unprocessable entity — no valid emission factors found: - Category requires emission factor but none available - Quantity is zero and no emission factor exists Error code: CONSUMPTION_WITHOUT_EMISSIONS_FACTOR '500': description: Internal server error during consumption/emission calculation components: securitySchemes: apiTokenAuth: type: http scheme: bearer bearerFormat: JWT ````