POST /api/v3/udf

Creates a new user defined field definition

CreateUDFV3 Permissions: ApplicationSettings (Manage)
Use this endpoint to add a new custom field to an entity type. For select-list data type (dataTypeId=12), UdfSelectValues must be provided with sequential display orders starting at 1. Requires ApplicationSettings Manage permission.

Request Headers

Header Value Required Description
ECI-ApiKey string Yes Your API key. See Authentication.
Content-Type application/json Yes All requests must specify JSON content type, including the request body.

Request Body

UDFCreate
Property Description Type
dataTypeId The UDF’s data type identifier. Possible value include: 1 (boolean), 2 (integer), 3 (string), 4 (double), 6 (date), 12 (select list), 13 (url), 15 (formatted text), 16 (image), 17 (pdf), 18 (document file), 19 (JSON text) Required integer (int32)
description Description for the UDF. Displayed next to the field name during data entry. Must be between 0 and 128 characters string
displayOrder

The UDF's display order

A value of 1 or less will put this record the beginning of the list

If the display order exists it will put this record at that spot. Display orders greater than or equal to this will be incremented by 1

A value greater than the stored max will put this record at the end of the list

Required		 integer (int32)
important Marks a UDF as important. Important fields are highlighted during data entry. boolean
name The UDF’s name Required Must be between 0 and 32 characters string
udfSelectValues

An array of options to populate a UDF select list.

Required when dataTypeId is 12 otherwise this will be ignored.

Required when dataTypeId is set to 12, case sensitive.		 UDFSelectValueCreate[]
UDFSelectValueCreate properties
Property Description Type
displayOrder The UDF select option’s display order Required integer (int32)
value The UDF select option’s value Required Must be between 0 and 255 characters string
udfType The UDF type. Possible value include: “Vendor”, “Place”, “Account”, “Meter”, “ChannelVersion”, “Rate”, “Bill”, “EnergyProject”, “Collection”, and “EmissionSource”. Required Must be between 0 and 32 characters string
Example Request Body application/json 
{  "dataTypeId": 1,  "description": "string",  "displayOrder": 1,  "important": false,  "name": "string",  "udfSelectValues": [
    {    "displayOrder": 1,    "value": "string"
  }
  ],  "udfType": "string"
}

Responses

200 OK The request succeeded and the response body contains the requested data.

Response Body Parameters

UDFResponse
Property Description Type
count The number of times this custom field has been used. Required (defined) integer (int32)
dataType DataTypeResponse
DataTypeResponse properties
Property Description Type
dataTypeCode The data type code/short name Required (defined) string
dataTypeId The unique identifier for the data type (e.g., 1=boolean, 2=integer, 3=string, 4=double, 6=date, 12=select list, 13=URL) Required (defined) integer (int32)
dataTypeInfo The data type display name/description Required (defined) string
description The description for the custom field. Required (defined) string
displayOrder The display order of the custom field. Required (defined) integer (int32)
important If true, this custom field is important. Required (defined) boolean
locked If true, then this udf is a system custom field Required (defined) boolean
name The name of the custom field. Required (defined) string
udfId The identifier of the custom field. Required (defined) integer (int32)
udfSelectValues Select values of the custom field, if it is a select list (DataType = 12). Required (defined) UDFSelectValueResponse[]
UDFSelectValueResponse properties
Property Description Type
count integer (int32)
displayOrder integer (int32)
udfSelectValueId integer (int32)
value string
udfType The type of the udf. Values include: Account, Meter, Vendor, Place, ChannelVersion, Rate, Bill, “EnergyProject”, “Collection”, and “EmissionSource”. Required (defined) string
Example Response application/json 
{  "count": 1,  "dataType": {    "dataTypeCode": "string",    "dataTypeId": 1,    "dataTypeInfo": "string"
  },  "description": "string",  "displayOrder": 1,  "important": false,  "locked": false,  "name": "string",  "udfId": 1,  "udfSelectValues": [
    {    "count": 1,    "displayOrder": 1,    "udfSelectValueId": 1,    "value": "string"
  }
  ],  "udfType": "string"
}
400 Bad Request The request was malformed or contains invalid parameters. Check the request body and query parameters.
404 Not Found The requested resource was not found. Verify the ID or path is correct.