---
title: "Create Viewpoint Mapping"
method: POST
path: "/api/v2/business-mapping/viewpoints/{viewpoint-id}/mappings"
---

# Create Viewpoint Mapping

`POST /api/v2/business-mapping/viewpoints/{viewpoint-id}/mappings`

## Request

- Base URL: `https://api.umbrellacost.io`
- URL: `https://api.umbrellacost.io/api/v2/business-mapping/viewpoints/{viewpoint-id}/mappings`
- Auth: none declared. Required headers: `authorization`, `apikey`

## Path parameters

- `viewpoint-id` string, required

## Headers

- `authorization` string, required
- `apikey` string, required

## Request body

- object
  - `name` string, required: Display name, and the value this mapping contributes to the viewpoint dimension. Names are how split targets and viewpoint filters address a mapping, so keep them unique within a viewpoint.
  - `rules` object[], required: Min 1. The match condition. See above "Rules"
    - `filters` object[], required
      - `field` string, required
      - `values` string[], required
      - `operator` string, required
  - `mappingGroupId` string: Puts the new mapping inside a mapping group (if defined).
  - `split` boolean: Turns this into a split mapping - its cost is redistributed onto other mappings instead of staying here. See Split explanation above.
  - `splitOptions` object: Required when split is truthy.
    - `mappings` string
    - `splitType` string
  - `k8s` boolean: Marks the mapping as a Kubernetes mapping, so its rules are resolved against the K8s dataset.
  - `k8s_config` object: Kubernetes display options
  - `is_group_by` boolean: Makes this a Group By mapping - one bucket per distinct value of group_by_field. See Mapping types above.
  - `group_by_field` string: The dimension to bucket by.
  - `is_telemetry` boolean: Allocates by a Unit Economics pipeline metric instead of by cost ratio.
  - `telemetryConfig` object: { pipelineId, dimension, metric, granularity, includeUnmatched }; granularity is daily (default) or monthly. Not validated on this route — the in-app route requires pipelineId, dimension and metric, and forbids combining is_telemetry with split or is_group_by. The public route enforces none of that, so hold the rule yourself.

## Response `200`

- object
  - `uuid` string
  - `creation_time` string
  - `update_time` string
  - `created_by` string
  - `name` string
  - `account_id` string
  - `account_key` string
  - `division_id` string
  - `split` boolean
  - `splitOptions` string
  - `global` boolean
  - `rules` string

## Other responses

- `201`: Created

---

[API](https://skmtc.dev/umbrellacost/apis/cost-usage.md) - [All operations](https://skmtc.dev/umbrellacost/apis/cost-usage/llms.txt) - [OpenAPI document](https://skmtc.dev/umbrellacost/apis/cost-usage/revisions/c5ae311d18ae?raw)