---
title: "Create a Preference"
method: POST
path: "/devicepreferences"
tags: ["Preferences"]
---

# Create a Preference

`POST /devicepreferences`

## Request

- Base URL: `https://api.smartthings.com/v1`
- URL: `https://api.smartthings.com/v1/devicepreferences`
- Auth: OAuth 2
  - Implicit: `https://auth-global.api.smartthings.com`
  - Scopes: `w:customcapabilities:*`
- TypeScript: <https://skmtc.dev/smartthings/apis/smartthings-api/docs/devicepreferences/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a preference.

## Headers

- `X-ST-Organization` string, ^(?:([0-9a-fA-F]{32})|([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$

## Request body

- PreferenceRequest
  - `preferenceId` string: The ID of the preference. When explicit flag is true this field is required.
  - `name` string, required: An alphanumeric English language name for this preference. Will be appended to a namespace to generate the full preference id.
  - `title` string, required: A short description for this preference.
  - `description` string: A long description for this preference.
  - `explicit` boolean: A flag describing whether this preference is explicit, or inline. When set to true a preferenceId is required.
  - `required` boolean: A flag describing whether this property is required or not.
  - `preferenceType` 'integer' | 'number' | 'boolean' | 'string' | 'enumeration', required: The type of preference this is.
  - `definition` object, required: The definition of this preference.
    - `minimum` number, double: Minimum value a preference may be set to. Only valid for `integer` and `number` preference types.
    - `maximum` number, double: Maximum value a preference may be set to. Only valid for `integer` and `number` preference types.
    - `minLength` integer: Minimum length a string may be set to. Only valid for `string` preference type.
    - `maxLength` integer: Maximum length a string may be set to. Only valid for `string` preference type.
    - `default` unknown
    - `stringType` 'text' | 'password' | 'paragraph': The type of a string preference. `text` is a normal preference, `password` encrypts the values, and `paragraph` is for documentation purposes.
    - `options` object: The available selections for an `enumeration` preference.

## Response `200`

successful return of the created preference

- PreferenceResponse
  - `preferenceId` string: The ID of the preference
  - `name` string: An alphanumeric English language name for this preference.
  - `title` string, required: A short description for this preference.
  - `description` string: A long description for this preference.
  - `required` boolean: A flag describing whether this property is required or not.
  - `explicit` boolean: A flag describing whether this preference is explicit, or inline.
  - `preferenceType` 'integer' | 'number' | 'boolean' | 'string' | 'enumeration', required: The type of preference this is.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `429`: Too many requests
- `default`: Unexpected error

## Changes

- **2022-12-19** `adcacfc2749d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/smartthings/apis/smartthings-api/changes/devicepreferences/post.md)

---

[API](https://skmtc.dev/smartthings/apis/smartthings-api.md) - [All operations](https://skmtc.dev/smartthings/apis/smartthings-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smartthings/apis/smartthings-api/revisions/2788a4236800?raw)