---
title: "Create an External Mapping"
method: POST
path: "/organizations/{orgId}/externalmappings"
tags: ["External Mapping"]
---

# Create an External Mapping

`POST /organizations/{orgId}/externalmappings`

Creates a new External Mapping.

This endpoint enables you to create a new External Mapping for the specified Organization. You need to supply a request body with the details of the new External Mapping.

## Path parameters

- `orgId` string, required

## Request body

- ExternalMappingRequest
  - `version` integer — The version number of the entity: - **Create entity:** Not valid for initial insertion of new entity - *do not use for Create*. On initial Create, version is set at 1 and listed in the response. - **Update Entity:** On Update, version is required and must match the existing version because a check is performed to ensure sequential versioning is preserved. Version is incremented by 1 and listed in the response.

## Response `200`

Returns the created External Mapping

- ExternalMappingResponse — Response containing an ExternalMapping entity
  - `id` string, required — The UUID of the entity.
  - `version` integer — The version number: - **Create:** On initial Create to insert a new entity, the version is set at 1 in the response. - **Update:** On successful Update, the version is incremented by 1 in the response.
  - `dtCreated` string, date-time — The DateTime when this item was created *(in ISO-8601 format)*.
  - `dtLastModified` string, date-time — The DateTime when this item was last modified *(in ISO-8601 format)*.
  - `createdBy` string — The ID of the user who created this item.
  - `lastModifiedBy` string — The ID of the user who last modified this item.
  - `m3terEntity` string, required — The name of the m3ter entity that is part of the External Mapping. For example, this could be "Account".
  - `m3terId` string, required — The unique identifier (UUID) of the m3ter entity.
  - `externalSystem` string, required — The name of the external system where the entity you are mapping resides.
  - `externalTable` string, required — The name of the table in the external system where the entity resides.
  - `externalId` string, required — The unique identifier (UUID) of the entity in the external system.
  - `integrationConfigId` string — UUID of the configuration this mapping is for

## Other responses

- `4XX` — Error message
- `5XX` — Error message

---

[API](https://skmtc.net/m3ter-com/apis/m3ter-api.md) · [All operations](https://skmtc.net/m3ter-com/apis/m3ter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/m3ter-com/m3ter-api/versions/ac93d1a9e6d9/schema)