Create task custom field

Creates a new custom field for tasks. All fields are required.

Step-by-step process:

Provide a default name and description (used as fallback when no translation exists)
Select the field type (Text, TextArea, Number, Date, Checkbox, Select, or MultiSelect)
For Select or MultiSelect types, provide select options with default values
Add multilingual translations for field name, description, and select options
The field will be available to assign to task types

Field types:

Text: Short text entries (e.g., “Responsible reviewer”)
TextArea: Longer text entries (e.g., “Audit result”)
Number: Numeric values
Date: Date values
Checkbox: Yes/No information
Select: Single selection from predefined options (requires selectOptions)
MultiSelect: Multiple selections from predefined options (requires selectOptions)

Multilingual support: Provide translations for field name, description, and select options. Leadtime automatically displays the correct text based on the user language.

Note: After creation, assign this custom field to specific task types to make it appear in task forms.

POST/administration/task-settings/custom-fields

Authorization

AuthorizationOAuth2 access token · headerrequired

Scopes:api:write

AuthorizationBearer token (JWT) · headerrequired

Query parameters

fieldsToReturnstring

Comma-separated list of top-level response fields to return. Overrides the endpoint compact default unless responseShape=full is used.

responseShapestring

Advanced override. Omit for the endpoint compact default. Use full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Allowed:compactfull

Header parameters

LT-Response-Shapestring

Advanced override. Set to full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Allowed:full

Request body

requiredapplication/json

descriptionstringrequired

Default custom field description (used as fallback when no translation exists for user's language)

idstring

Custom field ID (optional for create)

namestringrequired

Default custom field name (used as fallback when no translation exists for user's language)

selectOptionsFieldOptionDto[]required

Select options (required for Select and MultiSelect types)

Show properties

Array of FieldOptionDto

idobject

Option ID

translationsCustomFieldTranslationDto[]required

Language-specific translations for this option. Overrides the default value when user's language matches.

Show properties

Array of CustomFieldTranslationDto

languagestringrequired

Language code following ISO 639-1 format (e.g., "en", "de", "fr")

namestringrequired

Translated name for this language. Overrides the default name when user's language matches.

valuestringrequired

Default option value (used as fallback when no translation exists for user's language)

translationsCustomFieldTranslationDto[]required

Language-specific translations for field name. Overrides the default name when user's language matches.

Show properties

Array of CustomFieldTranslationDto

languagestringrequired

Language code following ISO 639-1 format (e.g., "en", "de", "fr")

namestringrequired

Translated name for this language. Overrides the default name when user's language matches.

translationsDescriptionsCustomFieldTranslationDto[]required

Language-specific translations for field description. Overrides the default description when user's language matches.

Show properties

Array of CustomFieldTranslationDto

languagestringrequired

Language code following ISO 639-1 format (e.g., "en", "de", "fr")

namestringrequired

Translated name for this language. Overrides the default name when user's language matches.

typestringrequired

Custom field type

Allowed:TextTextareaNumberDateCheckboxSelectMultiSelectCurrencyUrl

Responses

201

Task custom field created successfully

descriptionobject | nullrequired

Default custom field description (used as fallback when no translation exists for user's language)

entitystringrequired

Entity type (always Task for task custom fields)

Allowed:TaskProjectOrganizationObject

idstringrequired

Custom field ID

namestringrequired

Default custom field name (used as fallback when no translation exists for user's language)

selectOptionsFieldOptionDto[]required

Select options with their translations. Each option has a default value and language-specific overrides.

Show properties

Array of FieldOptionDto

idobject

Option ID

translationsCustomFieldTranslationDto[]required

Language-specific translations for this option. Overrides the default value when user's language matches.

Show properties

Array of CustomFieldTranslationDto

languagestringrequired

Language code following ISO 639-1 format (e.g., "en", "de", "fr")

namestringrequired

Translated name for this language. Overrides the default name when user's language matches.

valuestringrequired

Default option value (used as fallback when no translation exists for user's language)

sortnumberrequired

Sort order

translationsCustomFieldTranslationDto[]required

Language-specific translations for field name. Overrides the default name when user's language matches.

Show properties

Array of CustomFieldTranslationDto

languagestringrequired

Language code following ISO 639-1 format (e.g., "en", "de", "fr")

namestringrequired

Translated name for this language. Overrides the default name when user's language matches.

typestringrequired

Custom field type

Allowed:TextTextareaNumberDateCheckboxSelectMultiSelectCurrencyUrl

401

Unauthorized - Invalid or missing authentication token

403

Forbidden - Insufficient API scopes or permissions

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

OAuth2 access tokenRemember on this deviceInclude my values in samples

Parameters

fieldsToReturnqueryComma-separated list of top-level response fields to return. Overrides the endpoint compact default unless responseShape=full is used.responseShapequeryAdvanced override. Omit for the endpoint compact default. Use full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.LT-Response-ShapeheaderAdvanced override. Set to full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Bodyapplication/json

Request body

Request

curl -X POST "https://leadtime.app/api/public/administration/task-settings/custom-fields" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Task priority level",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Priority",
  "selectOptions": [
    {
      "id": "1",
      "translations": [
        {
          "language": "en",
          "name": "Priority"
        }
      ],
      "value": "High"
    }
  ],
  "translations": [
    {
      "language": "en",
      "name": "Priority"
    }
  ],
  "translationsDescriptions": [
    {
      "language": "en",
      "name": "Priority"
    }
  ],
  "type": "Select"
}'

const response = await fetch("https://leadtime.app/api/public/administration/task-settings/custom-fields", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"description\": \"Task priority level\",\n  \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"name\": \"Priority\",\n  \"selectOptions\": [\n    {\n      \"id\": \"1\",\n      \"translations\": [\n        {\n          \"language\": \"en\",\n          \"name\": \"Priority\"\n        }\n      ],\n      \"value\": \"High\"\n    }\n  ],\n  \"translations\": [\n    {\n      \"language\": \"en\",\n      \"name\": \"Priority\"\n    }\n  ],\n  \"translationsDescriptions\": [\n    {\n      \"language\": \"en\",\n      \"name\": \"Priority\"\n    }\n  ],\n  \"type\": \"Select\"\n}"
});

import requests

response = requests.post(
    "https://leadtime.app/api/public/administration/task-settings/custom-fields",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"description\": \"Task priority level\",\n  \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"name\": \"Priority\",\n  \"selectOptions\": [\n    {\n      \"id\": \"1\",\n      \"translations\": [\n        {\n          \"language\": \"en\",\n          \"name\": \"Priority\"\n        }\n      ],\n      \"value\": \"High\"\n    }\n  ],\n  \"translations\": [\n    {\n      \"language\": \"en\",\n      \"name\": \"Priority\"\n    }\n  ],\n  \"translationsDescriptions\": [\n    {\n      \"language\": \"en\",\n      \"name\": \"Priority\"\n    }\n  ],\n  \"type\": \"Select\"\n}",
)

Response

{
  "description": "Task priority level",
  "entity": "Task",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Priority",
  "selectOptions": [
    {
      "id": "1",
      "translations": [
        {
          "language": "en",
          "name": "Priority"
        }
      ],
      "value": "High"
    }
  ],
  "sort": 1,
  "translations": [
    {
      "language": "en",
      "name": "Priority"
    }
  ],
  "type": "Select"
}