--- schema_version: "1" id: d29f14307e1f7aa55500aa46adab0b4107955e861d50448fef779d83db824341 title: CustomField collection: legacydeveloper version: current locale: en-us portal_url: https://docs.salesforce.com/legacydeveloper/current/en-us/api_meta/customfield.md canonical_url: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/customfield.htm source_site: developer.salesforce.com content_type: documentation content_hash: 9118ef2734f82cf04ff8abc0727869dae46d26491d4036c7a56aa95ad7d5c89c description: Represents the metadata associated with a field. Use this metadata type to create, update, or delete custom field definitions on standard, custom, and external objects or standard field definitions on standard objects. --- # CustomField Represents the metadata associated with a field. Use this metadata type to create, update, or delete custom field definitions on standard, custom, and external objects or standard field definitions on standard objects. This type extends the [Metadata](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/metadata.htm "The base class for all metadata types. You can’t edit this object. A component is an instance of a metadata type.") metadata type and inherits its fullName field. ![Important](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note_important.png) #### Important Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations. Only standard fields that you can customize are supported, that is, standard fields to which you can add help text or turn on history tracking or Chatter feed tracking. Other standard fields aren't supported, including system fields (such as CreatedById or LastModifiedDate) and auto number fields. Some standard picklist fields aren’t supported. See [Unsupported Metadata Types](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_unsupported_types.htm "Some Salesforce features have metadata types that aren’t available in Metadata API. These metadata types can’t be retrieved or deployed with Metadata API. To make changes to these types, you must do it manually in each of your organizations."). By default, a custom object doesn’t have any standard fields that are customizable. Specify the full name whenever you create or update a field. For example, a custom field on a custom object: MyCustomObject\_\_c.MyCustomField\_\_c An example of a custom field on a standard object: Account.MyAcctCustomField\_\_c An example of a standard field on a standard object: Account.Phone An example of a custom field on an external object: MyExternalObject\_\_x.MyCustomField\_\_c ![Note](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note.png) #### Note In Metadata API, external objects are represented by the CustomObject metadata type. These custom field types aren’t available for external objects. - Auto number (available only with the cross-org adapter for Salesforce Connect) - Currency (available only with the cross-org adapter for Salesforce Connect) - Formula - Location - Master-detail relationship - Picklist and multi-select picklist (available only with the cross-org adapter for Salesforce Connect) - Rollup summary - Text (encrypted) - Text area (rich) ## Declarative Metadata File Suffix and Directory Location Custom fields are user-defined fields and are part of the custom object or standard object definition. See [CustomObject](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/customobject.htm "Represents a custom object that stores data unique to your org or an external object that maps to data stored outside your org.") for more information. Standard fields are predefined on standard objects. ![Note](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note.png) #### Note Retrieving a component of this metadata type in a project makes the component appear in any Profile and PermissionSet components that are retrieved in the same package. ## Retrieving Fields on Custom or Standard Objects When you retrieve a custom or standard object, you return everything associated with the object, except for standard fields that aren't customizable. You can also retrieve only specific fields for an object by explicitly naming the object and fields in package.xml. The following definition in package.xml creates the files objects/MyCustomObject\_\_c.object and objects/Account.object, each containing the requested field definitions. MyCustomObject\_\_c.MyCustomField\_\_c Account.MyCustomAccountField\_\_c Account.Phone CustomField ## Retrieving or Deploying Fields on Data 360 Objects When you retrieve a Data 360 object, such as a data lake object (DLO) or data model object (DMO), not all custom field properties are returned. The properties returned depend on the data type of the custom field. When you deploy a Data 360 object via Metadata API, in API version 60.0 or later, the call succeeds only if the properties are supported by the custom field's data type. If you include a property that isn't supported by the field's data type, the API returns an error. Data 360 objects support these data types. - Boolean/Checkbox - Date - DateTime - Email - Lookup (DMOs only) - Number - Percent - Phone - Text - Url ## Version Custom and standard fields are available in API version 10.0 and later. ## Fields Unless otherwise noted, all fields are creatable, filterable, and nillable.
Field Name Field Type Description
businessOwnerGroup reference Group associated with this field. The business owner group understands the importance of the field’s data to your company, and can be responsible for determining the minimum security classification. This field is available in API version 45.0 and later.
businessOwnerUser reference Person associated with this field. The business owner understands the importance of the field’s data to your company, and can be responsible for determining the minimum security classification. This field is available in API version 45.0 and later.
businessStatus picklist Indicates if the field is in use. Valid values are:
  • Active
  • DeprecateCandidate
  • Hidden
This field is available in API version 45.0 and later
caseSensitive boolean Indicates whether the field is case-sensitive (true) or not (false).

For indirect lookup relationship fields on external objects, this attribute affects how this custom field’s values are matched against the values of the referenceTargetField.
complianceGroup multipicklist Compliance acts, definitions, or regulations related to the field’s data. Valid values are:
  • CCPA
  • COPPA
  • GDPR
  • HIPAA
  • PCI
  • PII
This field is available in API version 47.0 and later.
customDataType string Deprecated in the Spring ‘19 (API version 45.0) release.
defaultValue string If specified, represents the default value of the field.
deleteConstraint DeleteConstraint (enumeration of type string) Deletion options for lookup relationships. Valid values are:
  • Cascade—Deletes the lookup record and associated lookup fields.
  • Restrict—Prevents the record from being deleted if it's in a lookup relationship.
  • SetNull—Default value. If the lookup record is deleted, the lookup field is cleared.

For more information on lookup relationships, see Object Relationships Overview.
deprecated boolean Reserved for future use.
description string Description of the field.
displayFormat string Display format of the field.
displayLocationInDecimal boolean Indicates how the geolocation values of a custom location field appear in the user interface. If true, the geolocation values appear in decimal notation. If false, the geolocation values appear as degrees, minutes, and seconds.
elementType ElementType (enumeration of type string) Reserved for future use.
encryptionScheme EncryptionScheme (enumeration of type string) For encrypted fields, determines which encryption scheme a field takes. Valid values are:
  • CaseInsensitiveDeterministicEncryption
  • CaseSensitiveDeterministicEncryption
  • None
  • ProbabilisticEncryption
This value pertains to Shield Platform Encryption, not Classic Encryption. This field is available in API version 44.0 and later.
externalDeveloperName string Available only for external objects. Name of the table column on the external data source that maps to this custom field in Salesforce. Corresponds to the External Column Name in the user interface. This field is available in API version 32.0 and later.
externalId boolean Indicates whether the field is an external ID field (true) or not (false). This property is returned only if the custom field data type is auto number, email, number, or text.
fieldManageability FieldManageability (enumeration of type string) Determines who can update the field after it’s released in a managed package. Valid values are:
  • Locked—The field can’t be updated.
  • DeveloperControlled—The creator of the record can update the field with a package upgrade.
  • SubscriberControlled—Anyone with proper permissions can update the field. The field can’t be updated with a package upgrade.
Available only for fields on custom metadata types. If the field type is MetadataRelationship, and the manageability of the entity definition field is:
  • Subscriber-controlled, then the Field Definition field must be subscriber-controlled.
  • Upgradeable, then the Field Definition field must be either upgradeable or subscriber-controlled.
formula string If specified, represents a formula on the field.
formulaTreatBlanksAs TreatBlanksAs (enumeration of type string) Indicates how to treat blanks in a formula. Valid values are BlankAsBlank and BlankAsZero.
fullName string Full name of the object. It must be specified when creating, updating, or deleting the object. See createMetadata() to see an example of this field specified for a call.

This value can't be null.
globalPicklist string. If this custom field is a picklist that’s based on a global picklist, globalPicklist is the name of the global picklist whose value set this picklist inherits. A custom picklist that’s based on a global picklist is restricted. You can only add or remove values by editing the global picklist. This field is available only in API version 37.0.
indexed boolean Indicates whether the field is indexed (true) or not (false). If this field is unique or the externalId is set true, the isIndexed value is set to true. This field is available only in API version 14.0 and earlier.
inlineHelpText string Content of field-level help. For more information, see Define Field-Level Help.
isAIPredictionField boolean Available for number type custom fields when you use Einstein Prediction Builder. Indicates whether the field can store and display Einstein prediction data on an object (true) or not (false). Use Einstein Prediction Builder to determine the data for the target field. This field is available in API version 43.0 and later.
isFilteringDisabled boolean Available only for external objects. Indicates whether the custom field is available in filters (true) or not (false). This field is available in API version 32.0 and later.
isNameField boolean Available only for external object fields of type text. Indicates whether the custom field is the name field (true) or not (false). For each external object, you can specify one field as the name field. If you set this value to true, ensure the external table column identified by the externalDeveloperName attribute contains name values. This field is available in API version 32.0 and later.
isSortingDisabled boolean Available only for external objects. Indicates whether the custom field is sortable (true) or not (false). This field is available in API version 32.0 and later.
label string Label for the field. You can't update the label for standard picklist fields, such as the Industry field for accounts.
length int Length of the field.
lookupFilter LookupFilter Metadata associated with a lookup filter definition. This field is only available in API version 30.0 and earlier. The metadata associated with a lookup filter is now represented by the lookupFilter field in the CustomField component.

LookupFilter isn't supported on the article type object.
maskChar EncryptedFieldMaskChar (enumeration of type string)

For encrypted fields, specifies the character to be used as a mask. Valid values are:

  • asterisk
  • X

This value pertains to Classic Encryption, not Shield Platform Encryption. For more information on encrypted fields, see Classic Encryption for Custom Fields in Salesforce Help.
maskType EncryptedFieldMaskType (enumeration of type string)

For encrypted text fields, specifies the format of the masked and unmasked characters in the field. Valid values are:

  • all—all characters in the field are hidden. This option is equivalent to the Mask All Characters option in Salesforce.
  • creditCard—The first 12 characters are hidden and the last four appear. This option is equivalent to the Credit Card Number option in Salesforce.
  • lastFour—all characters are hidden but the last four appear. This option is equivalent to the Last Four Characters Clear option in Salesforce.
  • nino—all characters are hidden. Salesforce automatically inserts spaces after each pair of characters if the field contains nine characters. This option is equivalent to the National Insurance Number option in Salesforce.
  • sin—all characters are hidden but the last four appear This option is equivalent to the Social Insurance Number option in Salesforce.
  • ssn—The first five characters are hidden and the last four appear This option is equivalent to the Social Security Number option in Salesforce.
This value pertains to Classic Encryption, not Shield Platform Encryption. For more information on encrypted fields, see Classic Encryption for Custom Fields in Salesforce Help.
metadataRelationshipControllingField string In custom metadata relationships, represents the controlling field that specifies the standard or custom object in an entity definition metadata relationship. Required when creating a field definition or entity particle metadata relationship on a custom metadata type. The object specified in the controlling field determines the values available in its dependent field definition or entity particle. For example, specifying the Account object filters the available fields in the field definition to Account fields only. This field is available in API version 39.0 and later.
picklist Picklist If specified, the field is a picklist, and this field counts the picklist values and labels. This field is available only in API version 37.0 and earlier. In later versions, use valueSet instead.
populateExistingRows boolean Indicates whether existing rows are going to be populated (true) or not (false).
precision int Precision, or number of digits in a number value. For example, the number 256.99 has a precision value of 5.
referenceTargetField string Specifies the custom field on the parent object to match against this indirect lookup relationship field, whose values come from an external data source. The specified custom field on the parent object must have both externalId and unique set to true. Available only for indirect lookup relationship fields on external objects. This field is available in API version 32.0 and later.
referenceTo string Reference this field has to another object.
relationshipLabel string Label for the relationship.
relationshipName string Value for one-to-many relationships. For example, if MyObject has a relationship to YourObject, the relationship name can be YourObjects.
relationshipOrder int This field is valid for all master-detail relationships, but the value is only non-zero for junction objects. A junction object has two master-detail relationships, and is analogous to an association table in a many-to-many relationship. Junction objects must define one parent object as primary (0), the other as secondary (1). The definition of primary or secondary affects delete behavior and inheritance of look and feel, and record ownership for junction objects.

0 or 1 are the only valid values, and 0 is always the value for objects that aren't junction objects.
reparentableMasterDetail boolean Indicates whether the child records in a master-detail relationship on a custom object can be reparented to different parent records (true) or not (false). The default value is false.

This field is available in API version 25.0 and later.
required boolean Indicates whether the field requires a value on creation (true) or not (false).
scale int Scale, or the number of digits to the right of the decimal point in a number. For example, the number 256.99 has a scale of 2.
securityClassification picklist Sensitivity of the data contained in the field. Valid values are:
  • Public
  • Internal
  • Confidential
  • Restricted
  • MissionCritical
This field is available in API version 45.0 and later.
startingNumber int Starting number for the field. When you create records, the Starting Number value increments to store the number that will be assigned to the next auto number field created.
  • You can’t retrieve the starting number of an auto number field through the Metadata API. To specify a Starting Number while deploying, add a startingNumber tag for your field to your package.xml file. For example: <startingNumber>42</startingNumber>
  • If you deploy without specifying a Starting Number value in your package.xml file, the default starting number for standard fields is 0. The default starting number for custom fields is 1.
stripMarkup boolean Indicates whether to remove markup (true) or preserve it (false). Used when converting a rich text area to a long text area.
summarizedField string Field on the detail row that’s being summarized. This field can't be null unless the summaryOperation value is count.
summaryFilterItems FilterItem[] Set of filter conditions for this field if it's a summary field. This field is summed in the child if the filter conditions are met.
summaryForeignKey string Master-detail field on the child that defines the relationship between the parent and the child.
summaryOperation SummaryOperations (enumeration of type string) Represents the type of sum operation to be performed. Valid values are:
  • Count
  • Min
  • Max
  • Sum
trackFeedHistory boolean Indicates whether the field is enabled for feed tracking (true) or not (false). To set this field to true, the enableFeeds field on the associated CustomObject must also be true. For more information, see Customize Chatter Feed Tracking.

This field is available in API version 18.0 and later.
trackHistory boolean Indicates whether history tracking is enabled for the field (true) or not (false). Also available for standard object fields (picklist and lookup fields only) in API version 30.0 and later.

To set trackHistory to true, the enableHistory field on the associated standard or custom object must also be true.

Field history tracking isn’t available for external objects.
trackTrending boolean Indicates whether historical trending data is captured for the field (true) or not (false). An object is enabled for historical trending if this attribute is true for at least one field. This field is available in API version 29.0 and later.

For more information, see Report on Historical Changes.
trueValueIndexed boolean Relevant only for a checkbox field. If set, true values are built into the index. This field is available only in API version 14.0 and earlier.
type FieldType (enumeration of type string) Type of field. Optional for standard fields on standard objects. This field is included for some standard field types, such as picklist or lookup, but not for others. The type field is included for custom fields.
unique boolean Indicates whether the field is unique (true) or not (false).
valueSet ValueSet Set of values that make up a picklist on a custom field. Each value is defined as a CustomValue. If this custom field is a picklist that uses a global value set, valueSet is the name of the global value set whose values this picklist inherits. A custom picklist that uses a global value set is restricted. You can only add or remove values by editing the global value set.

A ValueSet component has either a valueSetDefinition or a valueName specified, but never both.

This field is available in API version 38.0 and later.
visibleLines int Number of lines shown for the field.
writeRequiresMasterRead boolean Minimum sharing access level required on the primary record to create, edit, or delete child records. This field applies only to master-detail or junction object custom field types.
  • true—Allows users with Read access to the primary record permission to create, edit, or delete child records. This setting makes sharing less restrictive.
  • false—Allows users with Read/Write access to the primary record permission to create, edit, or delete child records. This setting is more restrictive than true, and is the default value.

For junction objects, the most restrictive access from the two parents is enforced. For example, if you set to true on both master-detail fields, but users have Read access to one primary record and Read/Write access to the other primary record, users aren't able to create, edit, or delete child records.
Fields use additional data types. For more information, see [Metadata Field Types](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_field_types.htm "These field types extend the field types described in the Salesforce Object Reference."). ## MktDataModelFieldAttributes Represents the Data 360 data model field attributes for a custom field. This type is a subtype of CustomField.
Field Name Field Type Description
definitionCreationType DefinitionCreationType enumeration How the object was added. Valid values are:
  • Bridge
  • Custom
  • Derived
  • Standard
  • System

In API version 62.0 and later, additional valid values are:

  • Activation_Audience
  • Ad_Audience_Insights
  • ADG
  • Calculated_Insight
  • CG_Audience
  • Chunk
  • Directory_Table
  • External
  • Problem_Records
  • Segment_Membership
  • Semantic
  • Transform
  • Vector_Embedding

In API version 67.0 and later, additional valid values are:

  • Ad_Audience_Insights
  • Auxiliary
  • Clean_Room
  • Deletion_Records
  • Problem_Records
invalidMergeActionType InvalidMergeActionType (enumeration of type string) Action to take when an invalid merge occurs for a field used to merge data. Valid values are:
  • Drop
  • Keep
  • Override
isDynamicLookup boolean Indicates whether existing data is queried for the field’s unique values (true) or not (false).
labelOverride string Custom label that overrides the field’s default display label in the data model. If unspecified, the default label is used. Maximum length is 255 characters. This field is available in API version 65.0 and later.
mappingAlertType MappingAlertType (enumeration of type string)

Type of alert shown when this field isn't mapped in the data model. This field is available in API version 65.0 and later. Valid values are:

  • None—No alert is shown when the mapping is incomplete or invalid.
  • Warning—A non-blocking warning is shown when the field mapping is incomplete or invalid.
  • Error—A blocking error prevents saving when the mapping is invalid.
masterLabel string Master label for the field. Maximum length is 40 characters. This field is available in API version 65.0 and later.
primaryIndexOrder int Position of the field in the primary key, starting at 1. If specified, the field is part of the primary key. For a compound primary key, the value specifies the field’s position in the key.
refAttrDeveloperName string Developer name of the field in the reference model. Applies only to standard fields.
mktDatalakeSrcKeyQualifier string Developer name of the MktDataLakeSrcKeyQualifier configured in the field.
## MktDataLakeFieldAttributes Represents the Data 360 data lake field attributes for a custom field. This type is a subtype of CustomField. Available in API version 50.0 or later.
Field Name Field Type Description
definitionCreationType DefinitionCreationType (enumeration of type string) How the object was added. Valid values are:
  • Bridge
  • Custom
  • Derived
  • Standard
  • System

In API version 62.0 and later, additional valid values are:

  • ADG
  • Calculated_Insight
  • CG_Audience
  • Chunk
  • Directory_Table
  • External
  • Semantic
  • Vector_Embedding
dateFormat string Optional date format of date and time fields. This field is available only in API version 55.0 and earlier.
externalName string External name of this field.
isEventDate boolean Indicates whether this field contains the event date for behavioral model area objects that are used to partition data (true) or not (false).
primaryIndexOrder int Position of the field in the primary key, starting at 1. If specified, the field is part of the primary key. For a compound primary key, the value specifies the field’s position in the key.
isInternalOrganization boolean Indicates whether this field contains the value for internal organization (true) or not (false). The value of the field is the name of the internal organization. Landing objects don't have access to the Salesforce ID and use the developer name instead.
isRecordModified boolean Indicates whether the field is the record modified field used to calibrate latest record version (true) or not (false).
mktDatalakeSrcKeyQualifier string Developer name of the MktDataLakeSrcKeyQualifier configured in the field. This field is available in API version 55.0 and later.
keyQualifierName string Developer name of key qualifier field. This field is available in API version 55.0 and later.
## LookupFilter Represents the metadata associated with a lookup filter. Replaces the NamedFilter component, which was removed as of API version 30.0. LookupFilter is available in API version 30.0 and later. | Field | Field Type | Description | | --- | --- | --- | | active | boolean | Required. Indicates whether the lookup filter is active (true) or not (false). | | booleanFilter | string | Advanced filter conditions. | | description | string | Description of what this filter does. | | errorMessage | string | Error message that appears if the lookup filter fails. | | filterItems | [FilterItem\[\]](#filteritem) | Required. Set of filter conditions. You can have up to 10 FilterItems per lookup filter. | | infoMessage | string | Information message displayed on the page. Use this field describe things the user possibly doesn't understand, such as why certain items are excluded in the lookup filter. | | isOptional | boolean | Required. Indicates whether the lookup filter is optional (true) or not (false). | Lookup filters use additional data types. For more information, see [Metadata Field Types](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_field_types.htm "These field types extend the field types described in the Salesforce Object Reference."). ## FilterItem Represents one entry in a set of filter criteria.
Field Field Type Description
field string Name of the field specified in the filter.
operation FilterOperation (enumeration of type string) Filter operation for this filter item. Valid values are:
  • equals
  • notEqual
  • lessThan
  • greaterThan
  • lessOrEqual
  • greaterOrEqual
  • contains
  • notContain
  • startsWith
  • includes
  • excludes
  • within (DISTANCE criteria only)
value string Value of the filter item being operated on, for example, if the filter is my_number_field__c > 1, the value of value is 1.
valueField string Final column in the filter contains a field or a field value. Approval processes don’t support valueField entries in filter criteria.
## Declarative Metadata Sample Definition The following example shows a field definition for a custom field that’s named Comments\_\_c. .... Comments\_\_c Add your comments about this object here This field contains help text for this object Comments 32000 LongTextArea 30 .... This XML is the definition for two fields on the Account standard object—a custom field (MyCustomAccountField\_\_c), and a standard field (Phone) that has history tracking enabled. MyCustomAccountField\_\_c A custom field on the Account standard object. false Some help text. MyCustomAccountField 100 false false false Text false Phone false true ## Wildcard Support in the Manifest File This metadata type doesn’t support the wildcard character \* (asterisk) in the package.xml manifest file. For information about using the manifest file, see [Deploying and Retrieving Metadata with the Zip File](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/file_based_zip_file.htm "The deploy() and retrieve() calls are used to deploy and retrieve a .zip file. Within the .zip file is a project manifest (package.xml) that lists what to retrieve or deploy, and one or more XML components that are organized into folders."). - [← Previous](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_compactlayout.htm "CompactLayout") - [Next →](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_fieldset.htm "FieldSet") #### See Also - [CustomObject](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/customobject.htm "Represents a custom object that stores data unique to your org or an external object that maps to data stored outside your org.") - [Picklist (Including Dependent Picklist)](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_picklist.htm "Deprecated. Represents a picklist (or dependent picklist) definition for a custom field in a custom object or a custom or standard field in a standard object, such as an account.") - [Metadata](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/metadata.htm "The base class for all metadata types. You can’t edit this object. A component is an instance of a metadata type.") - [NamedFilter](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/namedfilter.htm "Represents the metadata associated with a lookup filter. This metadata type is used to create, update, or delete lookup filter definitions. This component has been removed as of API version 30.0 and is only available in previous API versions. The metadata associated with a lookup filter is now represented by the lookupFilter field in the CustomField component.")