---
title: "simulateMapping"
method: POST
path: "/v1/erp/updates/mapping_simulation"
tags: ["erp"]
---

# simulateMapping

`POST /v1/erp/updates/mapping_simulation`

Test mapping configuration by transforming a payload using the provided mapping rules without persisting data.

Supports both v1.0 (object-based) and v2.0 (event-based) mapping formats.
See documentation at /docs/MAPPING_V2.md for detailed v2.0 format specification.

## Request body

- MappingSimulationRequest
  - `mapping_configuration` union, required
    - IntegrationConfigurationV1
      - `version` '1.0' — Mapping specification version
      - `mapping` object, required
        - `objects` object, required — [v1.0] Object type mappings
    - IntegrationConfigurationV2
      - `version` '2.0', required — Mapping specification version
      - `mapping` object, required
        - `events` object, required — [v2.0] Event type mappings
  - `object_type` string, required — Type of the object/event being mapped. For v1.0: must match a key in mapping_configuration.mapping.objects For v2.0: must match a key in mapping_configuration.mapping.events
  - `format` 'json' | 'xml', required — Format of the payload data
  - `payload` union, required — The object data payload - can be either a serialized string or a direct JSON object
    - string — The serialized object data payload (JSON, XML, etc.) as a string
    - object — Direct JSON object (will be automatically serialized)

## Response `200`

Successfully simulated mapping

- MappingSimulationResponse
  - `entity_updates` EntityUpdate[], required
    - `entity_slug` string, required — The entity type slug
    - `unique_identifiers` object, required — Unique identifier mappings for this entity
    - `attributes` object, required — Mapped attribute values
    - `pricing` object — Present when the entity mapping has a `pricing` block. Echoes the pricing configuration and the data extracted for it, so mapping authors can see what would be sent to the pricing service.
      - `config` object, required — The pricing configuration from the entity mapping
      - `data` object[], required — The pricing input data extracted from the payload
    - `mode` 'upsert' | 'delete' | 'purge', required — Effective operation mode applied to this entity at runtime. `upsert-prune-scope-purge` / `upsert-prune-scope-delete` configurations report `upsert` here, because the individual entities in the payload are upserted — the destructive part of those modes is reported separately in `prune_scope_updates`. For `delete` / `purge`, `attributes` are still mapped and returned but ignored at runtime: only `unique_identifiers` are used to locate the entity to remove.
  - `meter_readings_updates` MeterReadingUpdate[]
    - `meter` object, required
      - `$entity_unique_ids` object, required — Unique identifiers for the meter
    - `meter_counter` object
      - `$entity_unique_ids` object — Unique identifiers for the meter counter
    - `attributes` object, required — Meter reading attributes. Required: external_id, timestamp, source, value. `timestamp` must be ISO 8601 — either `YYYY-MM-DD` or `YYYY-MM-DDTHH:mm:ss` (with optional fractional seconds and optional `Z` / `±HH:mm` timezone offset); non-ISO formats (e.g. `DD.MM.YYYY` or epoch numbers) are rejected and must be converted upstream via a `jsonataExpression` (e.g. `$fromMillis(...)`). Date-only values are normalized to midnight UTC and offset-less date-times are anchored to UTC before being forwarded to the metering API. `source` must be one of: ECP, ERP, 360, journey-submission. `reason` (optional) must be one of: regular, irregular, last, first, meter_change, contract_change, meter_adjustment (or empty/null).
    - `mode` 'upsert' | 'delete', required — Effective operation mode applied to this reading at runtime. `upsert-prune-scope` configurations report `upsert` here — their destructive part is reported separately in `meter_readings_prune_scope_updates`.
  - `prune_scope_updates` EntityPruneScopeUpdate[] — Resolved prune scopes produced by entity mappings using `upsert-prune-scope-purge` / `upsert-prune-scope-delete`. Each entry describes the entities that would be deleted at runtime because they exist in scope but were not part of this payload.
    - `entity_slug` string, required — The entity type that would be pruned
    - `scope` object, required — The scope configuration resolved against the payload
      - `scope_mode` 'relations' | 'query', required — How the entities in scope are found
      - `schema` string — Schema of the related entity defining the scope (`relations` scope_mode only)
      - `unique_ids` object — Resolved unique identifiers of the related scope entity (`relations` scope_mode only)
      - `query` object — Resolved query parameters used to find entities in scope (`query` scope_mode only)
    - `keep_unique_ids` object[], required — Unique identifiers of the entities upserted by this payload. Everything else found in scope would be deleted.
    - `deletion_mode` 'delete' | 'purge', required — `delete` soft deletes the pruned entities, `purge` removes them permanently
  - `meter_readings_prune_scope_updates` MeterReadingPruneScopeUpdate[] — Resolved prune scopes produced by meter reading mappings using `upsert-prune-scope`. Each entry describes the readings that would be deleted at runtime for a meter (+ counter) because they were not part of this payload.
    - `meter` object, required
      - `$entity_unique_ids` object, required — Unique identifiers for the meter
    - `meter_counter` object
      - `$entity_unique_ids` object — Unique identifiers for the meter counter
    - `keep_external_ids` string[], required — External ids of the readings present in this payload. All other readings in scope would be deleted. An empty array means every reading in scope would be deleted.
    - `source` string — When set, only readings with this source are eligible for pruning (e.g. `ERP`)
  - `warnings` MappingSimulationWarning[] — Validation warnings about the configuration (e.g., unique_ids referencing non-indexed fields)
    - `entity_schema` string, required — The entity schema slug where the issue was found
    - `field` string, required — The field name that caused the warning
    - `message` string, required — Description of the validation issue

## Other responses

- `400` — Bad request
- `401` — Unauthorized request
- `422` — Unprocessable entity - mapping configuration or payload validation failed
- `500` — Internal Server Error

---

[API](https://skmtc.net/epilot/apis/integration-toolkit-api.md) · [All operations](https://skmtc.net/epilot/apis/integration-toolkit-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/epilot/integration-toolkit-api/revisions/68961a011db0/schema)