---
title: "Map a factor to a utility resource"
method: PUT
path: "/factor/entries/{entryId}/utility-resource"
tags: ["Factor Manage"]
---

# Map a factor to a utility resource

`PUT /factor/entries/{entryId}/utility-resource`

Sets which utility resource the factor's rows count under on the Utility page (a manual mapping, which the rule never overwrites, including when the factor is renamed or moved), or with null returns the factor to the rule mapping derived from its category and name. Factors of the organization's own libraries need the organization's write access, and every emission row using the factor is reclassified in the same transaction (200). Factors of public (shared) libraries are mapped for every organization at once: only Greentally platform staff holding the factor_library.write platform capability may do it (anyone else, and every API key, gets 403 PLATFORM_CAPABILITY_REQUIRED), a non-blank reason is required (400 without one), and the change is recorded in the platform audit trail with its before and after mapping (resource, source, library and factor name), the reason and the job. The mapping change commits at once (202) and the rows of every organization using the factor are reclassified in the background, one organization per transaction, by the returned job (GET /factor/utility-reclassify-jobs/{jobId}).

## Path parameters

- `entryId` string, required

## Request body

- FactorEntryUtilityResourceRequest
  - `reason` string — Why the mapping changes. Required and non-blank for a factor of a public library (recorded in the platform audit trail); ignored for the organization's own factors.
  - `utilityResource` 'electricity' | 'natural_gas' | 'lpg' | 'heating_oil' | 'gas_oil' | 'diesel' | 'petrol' | 'water' | 'waste' | 'heat_steam' | 'other', required

## Response `200`

The factor with its new mapping, and how many rows were reclassified.

- FactorEntryUtilityMappingResponse
  - `data` FactorEntryUtilityMapping, required
    - `entry` FactorEntry, required
      - `activityCode` string, required
      - `activityUnit` string, required
      - `canManage` boolean, required
      - `categoryId` string, required
      - `categoryName` string, required
      - `description` string, required
      - `factorValue` number, double, required
      - `id` string, required
      - `metadata` object, required
      - `name` string, required
      - `regionCode` string, required
      - `releaseId` string, required
      - `scope` 0 | 1 | 2 | 3, required
      - `unit` string, required
      - `utilityResource` 'electricity' | 'natural_gas' | 'lpg' | 'heating_oil' | 'gas_oil' | 'diesel' | 'petrol' | 'water' | 'waste' | 'heat_steam' | 'other', required
      - `utilityResourceSource` 'rule' | 'manual', required — rule: derived from the category and name, and re-derived when they change. manual: set with PUT /factor/entries/{entryId}/utility-resource; never overwritten by the rule.
    - `reclassifiedRows` integer, required — Emission rows reclassified (rows using the factor and the non-carbon rows of their documents).

## Other responses

- `202` — A public factor's new mapping; its rows are being reclassified by the returned job.
- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden

## Changes

- **2026-10-02** `766c2a40e369` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/greentally/apis/esgai-api/changes/factor/entries/:entryId/utility-resource/put.md)

---

[API](https://skmtc.dev/greentally/apis/esgai-api.md) · [All operations](https://skmtc.dev/greentally/apis/esgai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/greentally/apis/esgai-api/revisions/5c524454c847?raw)