Fields - Create

Create a new field.

POST https://dev.azure.com/{organization}/{project}/_apis/wit/fields?api-version=7.1

URI Parameters

Name In Required Type Description
organization
path True

string

The name of the Azure DevOps organization.

project
path

string

Project ID or project name

api-version
query True

string

Version of the API to use. This should be set to '7.1' to use this version of the api.

Request Body

Name Type Description
_links

ReferenceLinks

Link references to related REST resources.

canSortBy

boolean

Indicates whether the field is sortable in server queries.

description

string

The description of the field.

isDeleted

boolean

Indicates whether this field is deleted.

isIdentity

boolean

Indicates whether this field is an identity field.

isLocked

boolean

Indicates whether this field is marked as locked for editing.

isPicklist

boolean

Indicates whether this instance is picklist.

isPicklistSuggested

boolean

Indicates whether this instance is a suggested picklist .

isQueryable

boolean

Indicates whether the field can be queried in the server.

name

string

The name of the field.

picklistId

string

If this field is picklist, the identifier of the picklist associated, otherwise null

readOnly

boolean

Indicates whether the field is [read only].

referenceName

string

The reference name of the field.

supportedOperations

WorkItemFieldOperation[]

The supported operations on this field.

type

FieldType

The type of the field.

url

string

usage

FieldUsage

The usage of the field.

Responses

Name Type Description
200 OK

WorkItemField2

successful operation

Security

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Scopes

Name Description
vso.work_write Grants the ability to read, create, and update work items and queries, update board metadata, read area and iterations paths other work item tracking related metadata, execute queries, and to receive notifications about work item events via service hooks.

Examples

Create a new field

Sample request

POST https://dev.azure.com/{organization}/_apis/wit/fields?api-version=7.1

{
  "name": "New Work Item Field",
  "referenceName": "SupportedOperations.GreaterThanEquals",
  "description": null,
  "type": "string",
  "usage": "workItem",
  "readOnly": false,
  "canSortBy": true,
  "isQueryable": true,
  "supportedOperations": [
    {
      "referenceName": "SupportedOperations.Equals",
      "name": "="
    }
  ],
  "isIdentity": true,
  "isPicklist": false,
  "isPicklistSuggested": false,
  "url": null
}

Sample response

{
  "name": "New Work Item Field",
  "referenceName": "SupportedOperations.GreaterThanEquals",
  "description": null,
  "type": "string",
  "usage": "workItem",
  "readOnly": false,
  "canSortBy": true,
  "isQueryable": true,
  "supportedOperations": [
    {
      "referenceName": "SupportedOperations.Equals",
      "name": "="
    },
    {
      "referenceName": "SupportedOperations.NotEquals",
      "name": "<>"
    },
    {
      "referenceName": "SupportedOperations.GreaterThan",
      "name": ">"
    },
    {
      "referenceName": "SupportedOperations.LessThan",
      "name": "<"
    },
    {
      "referenceName": "SupportedOperations.GreaterThanEquals",
      "name": ">="
    },
    {
      "referenceName": "SupportedOperations.LessThanEquals",
      "name": "<="
    },
    {
      "referenceName": "SupportedOperations.Contains",
      "name": "Contains"
    },
    {
      "referenceName": "SupportedOperations.NotContains",
      "name": "Does Not Contain"
    },
    {
      "referenceName": "SupportedOperations.In",
      "name": "In"
    },
    {
      "name": "Not In"
    },
    {
      "referenceName": "SupportedOperations.InGroup",
      "name": "In Group"
    },
    {
      "referenceName": "SupportedOperations.NotInGroup",
      "name": "Not In Group"
    },
    {
      "referenceName": "SupportedOperations.Ever",
      "name": "Was Ever"
    },
    {
      "referenceName": "SupportedOperations.EqualsField",
      "name": "= [Field]"
    },
    {
      "referenceName": "SupportedOperations.NotEqualsField",
      "name": "<> [Field]"
    },
    {
      "referenceName": "SupportedOperations.GreaterThanField",
      "name": "> [Field]"
    },
    {
      "referenceName": "SupportedOperations.LessThanField",
      "name": "< [Field]"
    },
    {
      "referenceName": "SupportedOperations.GreaterThanEqualsField",
      "name": ">= [Field]"
    },
    {
      "referenceName": "SupportedOperations.LessThanEqualsField",
      "name": "<= [Field]"
    }
  ],
  "isIdentity": false,
  "isPicklist": false,
  "isPicklistSuggested": false,
  "url": "https://dev.azure.com/fabricam3/_apis/wit/fields/SupportedOperations.GreaterThanEquals"
}

Definitions

Name Description
FieldType

The type of the field.

FieldUsage

The usage of the field.

ReferenceLinks

The class to represent a collection of REST reference links.

WorkItemField2

Describes a field on a work item and it's properties specific to that work item type.

WorkItemFieldOperation

Describes a work item field operation.

FieldType

The type of the field.

Name Type Description
boolean

string

Boolean field type.

dateTime

string

Datetime field type.

double

string

Double field type.

guid

string

Guid field type.

history

string

History field type.

html

string

HTML (Multiline) field type.

identity

string

Identity field type.

integer

string

Integer field type.

picklistDouble

string

Double picklist field type. When creating a double picklist field from REST API, use "Double" FieldType.

picklistInteger

string

Integer picklist field type. When creating a integer picklist field from REST API, use "Integer" FieldType.

picklistString

string

String picklist field type. When creating a string picklist field from REST API, use "String" FieldType.

plainText

string

Plain text field type.

string

string

String field type.

treePath

string

Treepath field type.

FieldUsage

The usage of the field.

Name Type Description
none

string

Empty usage.

tree

string

Treenode field usage.

workItem

string

Work item field usage.

workItemLink

string

Work item link field usage.

workItemTypeExtension

string

Work Item Type Extension usage.

The class to represent a collection of REST reference links.

Name Type Description
links

object

The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only.

WorkItemField2

Describes a field on a work item and it's properties specific to that work item type.

Name Type Description
_links

ReferenceLinks

Link references to related REST resources.

canSortBy

boolean

Indicates whether the field is sortable in server queries.

description

string

The description of the field.

isDeleted

boolean

Indicates whether this field is deleted.

isIdentity

boolean

Indicates whether this field is an identity field.

isLocked

boolean

Indicates whether this field is marked as locked for editing.

isPicklist

boolean

Indicates whether this instance is picklist.

isPicklistSuggested

boolean

Indicates whether this instance is a suggested picklist .

isQueryable

boolean

Indicates whether the field can be queried in the server.

name

string

The name of the field.

picklistId

string

If this field is picklist, the identifier of the picklist associated, otherwise null

readOnly

boolean

Indicates whether the field is [read only].

referenceName

string

The reference name of the field.

supportedOperations

WorkItemFieldOperation[]

The supported operations on this field.

type

FieldType

The type of the field.

url

string

usage

FieldUsage

The usage of the field.

WorkItemFieldOperation

Describes a work item field operation.

Name Type Description
name

string

Friendly name of the operation.

referenceName

string

Reference name of the operation.