---
title: "Create Mapping Association"
method: POST
path: "/extensions/roboledger/{graph_id}/operations/create-mapping-association"
tags: ["RoboLedger: Taxonomy & Mapping"]
---

# Create Mapping Association

`POST /extensions/roboledger/{graph_id}/operations/create-mapping-association`

## Request

- Base URL: `https://api.robosystems.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/create-mapping-association`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Link a chart-of-accounts element to a US GAAP reporting concept. One mapping edge per call — use `auto-map-elements` for bulk AI-assisted mapping. Duplicate (from, to, type) tuples return 409. The target must be a leaf concept: a subtotal the statement sums from its children is refused (422). Map before you close: a new arc for an account with landed history in a closed month is refused (422), since the month's stamped statements were computed through the arcs as they stood. To move such an account, pass `replaces_association_id` (its current arc, removed in the same write). A move within the same primary statement is a reclassification and goes through: the stamped statements keep the answer as closed, live renders follow the new arc, and `reclassified_periods` names the months. A move across statements restates net income and is refused, naming the months to reopen latest-first.

**Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.

## Path parameters

- `graph_id` string, required

## Headers

- `Idempotency-Key` string, nullable

## Request body

- CreateMappingAssociationOperation: Create one CoA → reporting-concept mapping edge. This is the iterative, AI-assisted craft path. Each call adds a single association to the target mapping structure. Use `auto-map-elements` to create many at once via the MappingOperator. Reject duplicates: if the (from, to, type) tuple already exists, the call returns 409.
  - `from_element_id` string, required: Source element (typically a CoA element).
  - `to_element_id` string, required: Target element (typically a US GAAP reporting concept).
  - `association_type` 'presentation' | 'calculation' | 'mapping' | 'equivalence': Edge semantics. `mapping` rolls up CoA elements into reporting concepts; `presentation` orders concepts in a structure; `calculation` carries debit/credit weights; `equivalence` is a synonym link.
  - `order_value` number, nullable: Display order within the structure (lower = earlier).
  - `weight` number, nullable: Calculation weight (typically +1.0 or -1.0). Used by calculation linkbases to express signed roll-ups.
  - `confidence` number, nullable: Confidence score (0–1). For AI-suggested mappings: ≥0.90 auto-approved, 0.70–0.89 flagged for review, <0.70 skipped.
  - `suggested_by` string, nullable: Source of the suggestion (e.g., 'mapping_agent', 'user'). Captured for audit; not used by the runtime.
  - `mapping_id` string, required: Target mapping structure ID.
  - `replaces_association_id` string, nullable: The account's current mapping arc in this structure, removed in the same write: a remap in one call. When the account has landed history in a closed month the move is judged as a reclassification: allowed when the new concept sits on the same primary statement as the old one (the stamped statements keep the answer as closed; live renders follow the new arc; `reclassified_periods` names the months), refused when it crosses one.
  - `reason` string, nullable: Why the account is reclassified. Recorded on the new arc beside the months it reaches.

## Response `200`

Successful Response

- OperationEnvelopeAssociationResponse
  - `operation` string, required: Kebab-case operation name
  - `operationId` string, required: op_-prefixed ULID for audit and SSE correlation
  - `status` 'completed' | 'pending' | 'failed', required: Operation lifecycle state
  - `result` AssociationResponse: One edge between two elements within a structure (parent/child presentation, calculation rollup, mapping, equivalence). `association_type` discriminates the edge semantics. Mapping edges are the user-facing path (CoA → reporting concept); presentation / calculation edges express structure layout and roll-ups. `confidence` is set on AI-suggested mappings (≥0.90 auto-approved, 0.70-0.89 flagged for review).
    - `id` string, required
    - `structure_id` string, required
    - `from_element_id` string, required
    - `from_element_name` string, nullable
    - `from_element_qname` string, nullable
    - `to_element_id` string, required
    - `to_element_name` string, nullable
    - `to_element_qname` string, nullable
    - `association_type` string, required
    - `order_value` number, nullable
    - `weight` number, nullable
    - `confidence` number, nullable
    - `suggested_by` string, nullable
    - `approved_by` string, nullable
    - `replaced_association_id` string, nullable: The arc this write removed in the same transaction, when the call named one in `replaces_association_id`.
    - `reclassified_periods` string[]: Closed months whose live statements now read through this arc while their stamped sets keep the answer as closed. Empty unless the write replaced an arc on an account with landed history in a closed month.
  - `at` string, required: ISO-8601 UTC timestamp
  - `createdBy` string, nullable: User ID that initiated the operation
  - `idempotentReplay` boolean: True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

## Other responses

- `400`: Invalid request
- `401`: Authentication required
- `403`: Access denied
- `404`: Resource not found
- `409`: Idempotency-Key conflict — key reused with different body
- `422`: Validation error
- `429`: Rate limit exceeded
- `500`: Internal server error

---

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