# Create Custom Entity

Creates a new item for a Custom Entity type, identified by its denominator, from the supplied
JSON object. On success returns `201 Created` with the new resource location in the `Location` header.
## Authentication
Requires a valid API key in the `X-API-KEY` header.
## Headers
### Accept-Language
Culture used to interpret the localized field values supplied in the request body.
- **omitted / null**: tenant's default culture.
- **culture-code** (e.g. `en-US`, `es`): the specified culture.

## Request Body
A single JSON object whose properties match the writable fields published by
`/CustomEntities('{denominator}')/$metadata`. The body is normalized before reaching the
application layer:
- Must be a non-empty JSON object.
- A JSON array is accepted only if it contains exactly one element.
- Values are coerced to CLR primitives (`string`, `long`, `double`, `bool`, `null`),
nested objects and arrays.

## Response
**201 Created** — The `Location` header points to the new resource:
`/CustomEntities('{denominator}')/Item({id})`. No response body.
## Error Responses
- **400 Bad Request** — Payload normalization or validation failure (empty body,
multi-element array, invalid field values, etc.). Validation errors are returned
as `ValidationFailureRepresentation`.
- **401 Unauthorized** — Missing or invalid API key. Returned by the API gateway as
`{ "message": "Unauthorized", "request_id": "d8aafa5b8f3e400b60bea0123dd33317" }`.
- **403 Forbidden** — The API key does not have write permissions for this operation.
- **404 Not Found** — Tenant or Custom Entity denominator not found.
- **500 Internal Server Error** — Unexpected technical error.

## Example
**Request:**

```http
POST /CustomEntities('Brand') HTTP/1.1
X-API-KEY: your-api-key-here
Accept-Language: en-US
Content-Type: application/json
            
{
  "abcd_title": "Acme",
  "abcd_description": "Acme brand"
}
```
**Response:**

```http
HTTP/1.1 201 Created
Location: /CustomEntities('Brand')/Item(42)
```

Endpoint: POST /CustomEntities('{customEntityDenominator}')
Version: 2.0.0

## Path parameters:

  - `customEntityDenominator` (string, required)
    Custom Entity denominator (natural language name from the PIM)

## Header parameters:

  - `X-API-KEY` (string)
    Tenant's API key (required)

  - `Accept-Language` (string)
    Culture for localized field values in the request body (Accept-Language header)

## Response 200 fields (application/json):

  - `readLink` (object)

  - `readLink.uri` (string)

  - `value` (any)

## Response 401 fields (application/json):

  - `message` (string)

  - `request_id` (string)

## Response 403 fields (application/json):

  - `message` (string)

  - `request_id` (string)

## Response 404 fields (application/json):

  - `type` (string)

  - `title` (string)

  - `status` (integer)

  - `detail` (string)

  - `instance` (string)

## Response 500 fields (application/json):

  - `error` (string)

  - `details` (any)