---
title: "Create a property"
method: POST
path: "/audience/properties"
tags: ["Audience"]
---

# Create a property

`POST /audience/properties`

## Request

- Base URL: `https://app.lettr.com/api`
- URL: `https://app.lettr.com/api/audience/properties`
- Auth: HTTP bearer

Create a new property that contacts can store. The `name` and `type` fields are immutable after creation — to change them, delete the property and create a new one. Requires the `audience:write` scope and is blocked for sandbox API keys.

## Request body

- StoreAudiencePropertyRequest
  - `name` string, required: Property name. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores.
  - `type` 'string' | 'number' | 'boolean' | 'date' | 'json', required: Data type of the property
  - `fallback_value` string, nullable
  - `purpose` 'communication_language' | 'null', nullable: Designate this property as the team's communication language. Assigning it takes the role away from whichever property held it before.

## Response `201`

Property created

- ShowAudiencePropertyResponse
  - `message` string, required
  - `data` AudiencePropertyView, required
    - `id` string, uuid, required
    - `name` string, required
    - `type` 'string' | 'number' | 'boolean' | 'date' | 'json', required: Data type of the property
    - `fallback_value` string, nullable, required
    - `purpose` 'communication_language' | 'null', nullable: Role the property is designated for. `communication_language` marks the property campaigns read the recipient language from; only one property per team can hold it.
    - `created_at` string, date-time, required

## Other responses

- `401`: Unauthorized - Missing or invalid API key
- `403`: Forbidden - API key does not have the required scope
- `409`: Conflict
- `422`: Validation error
- `500`: Internal server error
- `503`: Service unavailable - the API key could not be verified, so the request was not processed. This does not mean the key is invalid; retry after the delay given in the Retry-After header.

---

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