---
title: "simulateOutboundMapping"
method: POST
path: "/v1/integrations/{integrationId}/outbound/mapping-simulation"
tags: ["integrations"]
---

# simulateOutboundMapping

`POST /v1/integrations/{integrationId}/outbound/mapping-simulation`

## Request

- Base URL: `https://integration-toolkit.sls.epilot.io`
- URL: `https://integration-toolkit.sls.epilot.io/v1/integrations/{integrationId}/outbound/mapping-simulation`
- Auth: HTTP bearer

Preview a poll delivery's `jsonata_expression` without saving or
enqueueing anything. The expression is checked and evaluated exactly
as at enqueue time: the same length, syntax and binding checks, the
same `$env`/`$mapValue`/`$mapKey` bindings resolved server-side from
the org's non-secret environment variables and key/value maps, the
same evaluation limits, and the same rule that the output must be a
JSON object.

Provide exactly one input: `payload` (an event to map as-is), or
`event_id` (with `event_catalog_event`) to load a historical
event-catalog event and hydrate it exactly as enqueue does — the
preview is then exact, and the hydrated event is echoed as `input`.

Mapping failures are a `200` with `valid: false` and an `error`;
`4xx` is reserved for malformed requests. Requires the
`integration:view` grant.

## Path parameters

- `integrationId` string, uuid, required

## Request body

- SimulateOutboundMappingRequest: Exactly one of `payload` or `event_id` is required. `event_id` needs `event_catalog_event` to name the event it belongs to.
  - `jsonata_expression` string, required: The poll mapping expression to preview
  - `payload` object: A standardized event-catalog event to map as-is
  - `event_id` string: Id of a historical event-catalog event to load, hydrate and map
  - `event_catalog_event` string: Event-catalog event name of `event_id` (required with `event_id`)

## Response `200`

Simulation outcome (mapping failures included)

- SimulateOutboundMappingResponse
  - `valid` boolean, required: Whether the expression produced a deliverable payload
  - `output` object: The payload a consumer would receive — present when valid
  - `error` OutboundMappingSimulationError
    - `code` 'syntax_error' | 'unknown_binding' | 'evaluation_error' | 'timeout' | 'invalid_output' | 'expression_too_long', required: `syntax_error` — the expression does not parse; `unknown_binding` — it reads a `$` name that is never bound; `evaluation_error` — it failed while evaluating; `timeout` — it exceeded the evaluation time or depth limit; `invalid_output` — it did not return a JSON object; `expression_too_long` — it exceeds 10,000 characters
    - `message` string, required: Human-readable explanation
    - `position` integer: Character position of the failure in the expression, when known
  - `mapping_version` string, required: The `mapping_version` messages mapped by this expression carry
  - `input` object: The hydrated event the expression ran against — present when `event_id` was used

## Other responses

- `400`: Bad request. `message` says what is wrong. A request refused by the request validation, before any handler ran, also carries `status: 400` and the raw validation errors under `error`.
- `401`: Unauthorized: the request carries no bearer token. The API gateway answers `{"message": "Unauthorized"}`. A token that is present but invalid or expired is refused with 403, not 401.
- `403`: Forbidden: the token lacks a permission the operation requires, or it is invalid or expired — the API gateway refuses those with `{"message": "Forbidden"}` before the request reaches the API.
- `404`: Resource not found
- `500`: Internal Server Error

## Changes

- **2026-09-29** `710e61b8d1f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/epilot/apis/integration-toolkit-api/changes/v1/integrations/:integrationId/outbound/mapping-simulation/post.md)

---

[API](https://skmtc.dev/epilot/apis/integration-toolkit-api.md) - [All operations](https://skmtc.dev/epilot/apis/integration-toolkit-api/llms.txt) - [OpenAPI document](https://skmtc.dev/epilot/apis/integration-toolkit-api/revisions/7d07c4eb8d37?raw)