---
title: "Create a new mapping table"
method: POST
path: "/v1/mapping-tables"
tags: ["Mapping Tables"]
---

# Create a new mapping table

`POST /v1/mapping-tables`

Create a new mapping table. Requires MANAGE_MAPPING_TBLS system access right. If `guid` is
provided, it is used as the table GUID; otherwise a new GUID is generated. Table name and GUID
must be unique (name comparison is case-insensitive).

## Request body

- object
  - `name` string, required — Mapping table name (cannot be empty).
  - `description` string — Mapping table description.
  - `flags` integer — Mapping table flags (bit 0 - numeric keys).
  - `elements` MappingTableElement[] — Table elements. Replaces all existing elements when provided.
    - `key` string, required — Element key. For tables with numeric keys flag set, key is parsed as integer (decimal, or hexadecimal with `0x` prefix) and stored in decimal form.
    - `value` string — Mapped value.
    - `description` string — Element description.
  - `guid` string, uuid — Optional table GUID.

## Response `201`

Mapping table created successfully.

- MappingTable
  - `id` integer — Mapping table ID.
  - `guid` string, uuid — Mapping table GUID.
  - `name` string — Mapping table name.
  - `description` string — Mapping table description.
  - `flags` integer — Mapping table flags (bit 0 - numeric keys).
  - `elements` MappingTableElement[]
    - `key` string, required — Element key. For tables with numeric keys flag set, key is parsed as integer (decimal, or hexadecimal with `0x` prefix) and stored in decimal form.
    - `value` string — Mapped value.
    - `description` string — Element description.

## Other responses

- `400` — Invalid request (missing or empty name, invalid field type, or value too long).
- `401` — Unauthorized.
- `403` — Access denied.
- `409` — Mapping table with same name or GUID already exists.
- `500` — Database failure.

## Changes

- **2026-09-30** `d3ebef46a35c` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/netxms/apis/netxms-api/changes/v1/mapping-tables/post.md)

---

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