Object mappings
An integration manipulates its own provider objects: a Mondu order, Stripe customer, Sumsub verification case. A mapping durably links one of these objects to the Ormuz object it represents. This link enables reconciliation, operation idempotency, and direct exposure of your business objects in inbound events.
What a mapping is
A mapping associates, for a given integration configuration, a provider object with an Ormuz object:
A mapping links a provider object to the Ormuz object it represents, within the scope of the configuration that created it.
It is not a business object: it is technical correspondence data belonging to the configuration that created it. Two distinct configurations of the same integration do not share mappings, and one integration never sees another's.
Correspondance vs object link
An object mapping and an object link answer two different questions. The mapping asserts technical identity between a provider object and the Ormuz object it represents; it supports correlation, idempotency, and inbound-event resolution.
A object link is instead an explicit relationship created by a process between two objects that remain distinct. It can link two platform objects, a platform object and an extension object, or two extension objects. The link carries a business key selected by the process and never means the two endpoints represent the same resource.
| Mapping | Object link | |
|---|---|---|
| Question | “which Ormuz object represents this provider object?” | “which objects were explicitly linked?” |
| Semantics | Technical identity/correlation | Business or operational relationship |
| Creation | By the integration when it already legitimately holds the target, or through API | By a Core node or the Object Links API |
| Use | Exact resolution and idempotency | Explicit navigation in a process |
Object links are never inferred from mappings. If your process needs a functional relationship between two objects, it must create it explicitly.
How a mapping is established
There is one rule with no exception: a mapping never creates new access; it freezes access already held. An integration may therefore record a mapping only to an object it legitimately held at that moment, namely:
- an object the process passed to it as node input;
an object it just read during this execution through a permission you granted;
an object it just created through the normal path from an object proposal submitted in the process;
an object already targeted by an existing mapping of the same configuration.
Without this rule, an integration could expand access step by step: record a mapping to an object merely seen in received content, use it to read that object, discover other identifiers, and repeat. The platform therefore rejects any mapping whose target was not already legitimately accessible.
It follows that an inbound webhook or scheduled synchronization cannot create any mapping : running outside any process, such a surface holds no business object. In particular, an external reference supplied by the provider is never interpreted as an Ormuz identifier to create a link.
Mappings are therefore established by nodes in your processes when they create the provider object and may also be created explicitly through the API.
What a mapping allows you to reread
Once established, a mapping authorizes reread of its exact target in both directions.
From the external identifier — the common case. Upon receiving an event concerning order
a5f3…, the integration resolves your complete Ormuz order and exposes it as a typed input to the triggered process.From the Ormuz identifier — useful when the provider returns only the reference you previously supplied, for example a list of invoices settled in a payout. This reverse resolution succeeds only if a mapping in the configuration already targets exactly that object; otherwise nothing is resolved.
In both cases, the returned object is the complete public contract, identical to the REST API object. No additional permission is required: the integration is not freely selecting a resource; it requests the target already attached to one of its own objects.
What a mapping does not authorize
no write access — modifying the object requires a write permission granted to a node inside a process;
no search or listing — only the exact target is reachable;
no related objects — a mapping to a contact does not open access to the corresponding company;
no other type — if the expected type does not match the mapping type, resolution is denied;
no other configuration or merchant — scope is strictly that of the configuration that created the mapping.
Uniqueness and conflicts
For a given configuration, an external object can designate only one Ormuz object. Recording the same mapping again has no effect: the operation is idempotent and returns the existing mapping.
Attempting to point an already-associated external object to another target fails explicitly with code
extension_object_mapping_conflict. A conflict is never resolved by silent overwrite: divergence is surfaced for arbitration. The reverse is allowed — several external objects may designate the same Ormuz object.
The target is verified at creation: the type must be addressable, the object must exist, and it must belong to the correct scope.
Lifecycle
A correspondance survives the consent that allowed its creation. Removing the node from the process or revoking the permission used to read the object does not delete the mapping: it continues authorizing reread of its exact target.
This is deliberate — an expiring mapping would make later reconciliation impossible, defeating its purpose — and remains bounded: read-only, exact object, exact configuration. The public API currently exposes no individual mapping deletion. Deleting the integration configuration also ends mappings in that scope.
Review and create through API
Mappings for an integration configuration can be listed and filtered by type and identifier on either side of the link.
GET /v1/extension-configs/exc_123/mappings?external_object_type=order GET /v1/extension-configs/exc_123/mappings?ormuz_object_type=order&ormuz_object_id=ord_123
Each mapping has the following shape.
| Field | Description |
|---|---|
id | Mapping identifier. |
external_object_type | Object type in the external system, as named by the extension (order, buyer…). |
external_object_id | Object identifier in the external system. |
ormuz_object_type | Target Ormuz business-object type (order, company, invoice…). |
ormuz_object_id | Target Ormuz object identifier. |
metadata | Free-form technical information attached to the link. |
A mapping may be created explicitly, for example to attach an object created before the integration was installed:
POST /v1/extension-configs/exc_123/mappings
{
"external_object_type": "order",
"external_object_id": "a5f3",
"ormuz_object_type": "order",
"ormuz_object_id": "ord_123"
}These operations fall under your own administration rights and are not an access path open to integrations themselves. See Integration data access for the complete model.