---
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
  - `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).
  - `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/c24837d75096/schema)