---
title: "Preview an organization operation and obtain a confirmation"
method: POST
path: "/api/v1/organization-operation-previews"
tags: ["Organization operations"]
---

# Preview an organization operation and obtain a confirmation

`POST /api/v1/organization-operation-previews`

## Request

- Base URL: `https://api.mencoro.com`
- URL: `https://api.mencoro.com/api/v1/organization-operation-previews`
- Auth: HTTP bearer

Organization, member and invitation changes need two calls. This one reports the concrete changes, the side effects, the warnings and the conditions, and returns a confirmation valid for five minutes. Send it back in the X-Mencoro-Confirmation header, together with an Idempotency-Key, on the call that performs the operation. Previewing has no effects of any kind.

## Request body

- object
  - `action` 'createOrganization' | 'updateOrganization' | 'archiveOrganization' | 'restoreOrganization' | 'changeMemberRole' | 'suspendMember' | 'reactivateMember' | 'createInvitation' | 'cancelInvitation'
  - `organizationId` string, uuid, nullable: Required for every action except createOrganization.
  - `resourceId` string, uuid, nullable: The member or invitation the action acts on, for the actions that name one.
  - `payload` object: The body you intend to send to the operation itself.

## Response `200`

What the operation would do, plus a confirmation

- object
  - `action` string
  - `organization` object, nullable: The organization the operation acts on. For createOrganization there is none yet, so `id` is null and `name` carries the name you proposed — the preview shows what you are about to create rather than hiding it. Branch on `organization.id`, never on `organization` itself.
    - `id` string, uuid, nullable
    - `name` string
  - `resourceId` string, uuid, nullable: The member or invitation the action acts on; null for the actions that name none.
  - `changes` OperationEffect[]: What the operation itself will do.
    - `code` string, required: Stable machine-readable identifier for this effect
    - `summary` string, required: Human-readable description, safe to show to whoever must approve the operation
    - `targets` string[]
  - `sideEffects` OperationEffect[]: What else it will cause, with the records it will touch in `targets`.
    - `code` string, required: Stable machine-readable identifier for this effect
    - `summary` string, required: Human-readable description, safe to show to whoever must approve the operation
    - `targets` string[]
  - `warnings` OperationEffect[]: How the system behaves around it. Not part of the effects digest: rewording one does not invalidate a confirmation.
    - `code` string, required: Stable machine-readable identifier for this effect
    - `summary` string, required: Human-readable description, safe to show to whoever must approve the operation
    - `targets` string[]
  - `conditions` OperationEffect[]: What must hold for the operation to be allowed.
    - `code` string, required: Stable machine-readable identifier for this effect
    - `summary` string, required: Human-readable description, safe to show to whoever must approve the operation
    - `targets` string[]
  - `actor` object: Who the confirmation is issued to: the user and the API key. It is valid for that pair only.
  - `confirmation` object: The token to send back, the header to send it in, and how long it lives.

## Other responses

- `400`: Unknown action, or a payload the operation does not accept
- `401`: Missing or invalid API key
- `403`: The key lacks a required capability, or its scope is too narrow
- `404`: No organization the caller can access under this id

---

[API](https://skmtc.dev/mencoro/apis/mencoro-api.md) · [All operations](https://skmtc.dev/mencoro/apis/mencoro-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mencoro/apis/mencoro-api/revisions/022b6e82faa4?raw)