---
title: "Create attribute"
method: POST
path: "/attributes/{companyId}"
tags: ["Attributes"]
---

# Create attribute

`POST /attributes/{companyId}`

Creates an attribute. If `customId` is omitted, Embat auto-generates one. If an attribute with the given `customId` already exists, its fields are overwritten instead of raising a duplicate error — this endpoint behaves as an upsert. Sending `values` replaces the attribute's full value list, and **omitting `values` on an existing attribute removes all of its current values** — always resend the values you want to keep.

## Path parameters

- `companyId` string, required

## Request body

- PostAttributesRequestSchema
  - `customId` string, nullable — Your own unique ID for the attribute. If omitted, Embat auto-generates one.
  - `source` 'erp' | 'api' | 'embat', required
  - `active` boolean — Whether the attribute is active.
  - `name` string, required — Display name of the attribute.
  - `type` 'list' | 'string' | 'number', required
  - `required` boolean — Whether a value for this attribute should be mandatory wherever it is used. Informational only: this API does not enforce it.
  - `values` AttributesRequestValuesSchema[], nullable — Values available for this attribute (relevant when `type` is `list`). If an attribute with this `customId` already exists, sending `values` **replaces** its current list — any previously stored value not included here is removed. Omitting `values` when creating a new attribute with an existing `customId` also removes all of its current values. An attribute holds at most 5000 values; if the combined total would exceed the limit, the excess new values are silently discarded.
    - `customId` string, required — Your own unique ID for the value, unique within the attribute.
    - `name` string, required — Display name of the value.
    - `parentCustomId` string, nullable — Custom ID of the value of the parent attribute (see the attribute's `parentCustomId`) that this value is nested under. Ignored if the attribute has no `parentCustomId` or no value with this `customId` exists yet on the parent attribute.
  - `parentCustomId` string, nullable — Custom ID of the parent attribute, to nest this attribute under another one (e.g. a "City" attribute nested under "Country"). Must reference an existing attribute.

## Response `200`

Successful Response

- UpsertAttributesResponseSchema
  - `id` string, required — Embat resource ID
  - `customId` string, required — Client-provided custom ID

## Other responses

- `401` — Unauthorized. The bearer token is missing, invalid or expired.
- `404` — Company not found, or `parentCustomId` does not match an existing attribute.
- `422` — Validation Error
- `500` — Unexpected error. Contact support if it persists.

---

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