Field Types

In addition to the primitive data types, the API defines the following data types for fields:

Note
For fields that contain strings, behavior is different beginning with API version 15.0. In API versions previous to 15.0, if you specify a value for a field, and that value is too large, the value is truncated. For API version 15.0 and later, if a value is specified that is too large, the operation fails and the fault code STRING_TOO_LONG is returned. AllowFieldTruncationHeader allows you to specify that the previous behavior, truncation, be used instead of the new behavior in API versions 15.0 and later. This header has no effect in versions 14.0 and earlier. The affected fields are: anyType, email, encryptedstring, multipicklist, phone, picklist, string, and textarea.
Field Type What the Field Contains
address A compound data type that contains address field data. See Address Compound Fields.
anyType

Polymorphic data type that returns string, picklist, reference, Boolean, currency, int, double, percent, ID, date, datetime, url, or email data depending on the kind of field involved. See AnyType Field Type.

calculated Fields that are defined by a formula. See Calculated Field Type.
combobox A combobox, which includes a set of enumerated values and allows the user to specify a value not in the list. See ComboBox Field Type.
currency Currency values. See Currency Field Type.
DataCategoryGroupReference Reference to a data category group or a category unique name. See DataCategoryGroupReference Field Type.
email Email addresses. See Email Field Type.
encryptedstring Encrypted text fields contain any combination of letters, numbers, or symbols that are stored in encrypted form. You can set a maximum length of up to 175 characters. Available in API versions 11.0 and later.
ID Primary key field for the object. See ID Field Type.

Note that most Web services tools, including .NET andWSC, map the ID simple type defined in the API WSDL (Enterprise or Partner) to a string. However, other tools generate a specific ID class to represent the ID simple type. Please consult your Web services toolkit documentation for more information.

location A compound data type that contains latitude and longitude values for geolocation fields. See Geolocation Compound Fields.
masterrecord When records are merged, the ID of the record that is saved (the other records are deleted).
multipicklist Multi-select picklists, which include a set of enumerated values from which multiple values can be selected. See Multi-Select Picklist Field Type.
percent Percentage values. See Percent Field Type.
phone Phone numbers. Values can include alphabetic characters. Client applications are responsible for phone number formatting. See Phone Field Type.
picklist Picklists, which include a set of enumerated values from which one value can be selected. See Picklist Field Type.
reference Cross-references to a different object. Analogous to a foreign key field in SQL. See Reference Field Type.
textarea String that is displayed as a multiline text field. See Textarea Field Type.
url URL values. Client applications should commonly display these as hyperlinks. See URL Field Type.

These field types extend primitive data types. While many of these field types follow common data typing conventions that are made explicit in their metadata, certain field types have unique characteristics that you need to understand before using them in your client application.

These field types apply to both standard and custom fields. They are enumerated in the type field of the  Field type, which is described in the fields property of the DescribeSObjectResult.

Note
Some numeric fields have precision and scale limits. In addition, certain text fields have length restrictions. These restrictions are enforced when you create() or update() objects. However, the API may return data that does not meet these restrictions.

AnyType Field Type

The anyType field type is dynamic and returns string, date, number, or boolean data depending on the kind of field involved. For example, the element in a SOAP message has an xsi:type="xsd:string" attribute if the field is of type string. This field type is used in history objects for the NewValue and OldValue fields. It is also a valid field type for fieldType and soapType.

Note
Most SOAP toolkits automatically deserialize this element into the correct native type.

Calculated Field Type

Calculated fields are read-only fields in the API. These are fields defined by a formula, which is an algorithm that derives its value from other fields, expressions, or values. You can filter on these fields in SOQL, but you should not replicate these fields. The length of text calculated fields is 3900 characters or less—anything longer will be truncated.

Calculated fields are called formula fields in the Salesforce user interface.

ComboBox Field Type

A combobox is a picklist that also allows users to type a value that is not already specified in the list. A combobox is defined as a string value.

Currency Field Type

Currency fields contain currency values, such as the ExpectedRevenue field in a Campaign, and are defined as type double.

For organizations that have the multicurrency option enabled, the CurrencyIsoCode field is defined for any object that can have currency fields. The CurrencyIsoCode field and currency fields are linked in a special way. On any specific record, the CurrencyIsoCode field defines the currency of that record, and thus, the values of all currency fields on that record will be expressed in that currency.

For most cases, clients do not need to consider the linking of the CurrencyIsoCode field and the currency fields on an object. However, clients may need to consider the following:

To perform currency conversions, client applications can look up the CurrencyIsoCode in the CurrencyType object.

DataCategoryGroupReference Field Type

A data category group has categories that classify articles in Salesforce Knowledge and questions in the Answers feature. Every article and question object has two fields of type DataCategoryGroupReference which contain the category group and category unique name. You can use the describeDataCategoryGroups() and describeDataCategoryGroupStructures() calls to retrieve the category groups and categories associated to these objects.

Email Field Type

Email fields contain email addresses. Client applications are responsible for specifying valid and properly formatted email addresses in create() and update() calls.

ID Field Type

With rare exceptions, all objects in the API have a field of type ID that is named Id and contains a unique identifier for each record in the object. It is analogous to a primary key in relational databases. When you create() a new record, the Web service generates an ID value for the record, ensuring that it is unique within your organization’s data. You cannot use the update() call on ID fields. Because the ID value stays constant over the lifetime of the record, you can refer to the record by its ID value in subsequent API calls. Also, the ID value contains a three-character code that identifies the object type, which client applications can retrieve via the describeSObjects() call.

In addition, certain objects, including custom objects, have one or more fields of type reference that contain the ID value for a related record. These fields have names that end in the suffix “-Id”, for example, OwnerId in the account object. OwnerId contains the ID of the user who owns that object. Unlike the field named Id, reference fields are analogous to foreign keys and can be changed via the update() call. For more information, see Reference Field Type.

Some API calls, such as retrieve() and delete(), accept an array of IDs as parameters—each array element uniquely identifies the row to retrieve or delete. Similarly, the update() call accepts an array of sObject records—each sObject contains an Id  field that uniquely identifies the sObject.

ID fields in the Salesforce user interface contain 15-character, base-62, case-sensitive strings. Each of the 15 characters can be a numeric digit (0-9), a lowercase letter (a-z), or an uppercase letter (A-Z). Two unique IDs may only be different by a change in case.

Because there are applications like Access which do not recognize that 50130000000014c is a different ID from 50130000000014C, an 18-digit, case-safe version of the ID is returned by all API calls. The 18 character IDs have been formed by adding a suffix to each ID in the Force.com API. 18-character IDs can be safely compared for uniqueness by case-insensitive applications, and can be used in all API calls when creating, editing, or deleting data.

If you need to convert the 18-character ID to a 15-character version, truncate the last three characters. Salesforce.com recommends that you use the 18-character ID.

Note
Most Web services tools, including .NET and WSC, map the ID simple type defined in the API WSDL (Enterprise or Partner) to a string. However, other tools generate a specific ID class to represent the ID simple type. Please consult your web services toolkit documentation for more information.

Multi-Select Picklist Field Type

Multi-select picklist fields contain a list of one or more items from which a user can choose multiple items. One of the items can be configured as the default item. Selections are maintained as a string containing a series of attributes delimited by semicolons. For example, a query might return the values of a multivalue picklist as “first value; second value; third value”. For information on querying multi-select picklists, see Querying Multi-Select Picklists in the Salesforce SOQL and SOSL Reference Guide.

Percent Field Type

Percent fields contain percent values. Percent fields are defined as type double.

Phone Field Type

Phone fields contain phone numbers, which can include alphabetic characters. Client applications are responsible for phone number formatting.

Picklist Field Type

Picklist fields contain a list of one or more items from which a user chooses a single item. They display as drop-down lists in the Salesforce user interface. One of the items can be configured as the default item.

In the Field object associated with the DescribeSObjectResult, the restrictedPicklist field defines whether the field is a restricted picklist or not. The API does not enforce the list of values for advisory (unrestricted) picklist fields on create() or update(). When inserting an unrestricted picklist field that does not have a PicklistEntry, the system creates an “inactive” picklist value. This value can be promoted to an “active” picklist value by adding the picklist value in the Salesforce user interface.

When creating new, inactive picklists, the API checks to see if there is a match. This check is case-insensitive.

In theField object associated with the DescribeSObjectResult, the picklistValues field contains an array of items (PicklistEntry objects). Each PicklistEntry defines the item’s label, value, and whether it is the default item in the picklist (a picklist has no more than one default value).

Enumerated fields support localization of the labels to the language of the user. For example, for the Industry field on an Account, the value “Agriculture” may be translated to various languages. The enumerated field values are fixed and do not change with a user’s language. However, each value may have a specified “label” field that provides the localized label for that value. You must always use the value when inserting or updating a field. The query() call always returns the value, not the label. The corresponding label for a value in the describeSObjectResult should be used when displaying the value to the user in any user interface.

The API supports the retrieval of the certain picklists in the following objects: CaseStatus, ContractStatus, LeadStatus, OpportunityStage, PartnerRole, SolutionStatus, TaskPriority, and TaskStatus. Each object represents a value in the respective picklist. These picklist entries always specify some other piece of information, such as whether the status is converted, and so on. Your client application can invoke the query() call on any of these objects (such as CaseStatus) to retrieve the set of values in the picklist, and then use that information while processing other objects (such as Case objects) to find more information about those objects (such as a given case). These objects are read-only via the API. To modify items in picklists, you must use the Salesforce user interface.

Reference Field Type

A reference field contains an Id value that points to a unique record (usually the parent record) on another object. This is analogous to the concept of a foreign key in relational databases. The name of a reference field ends, by convention, with the letters Id (such as CaseId or OpportunityId). For example, in the OpportunityCompetitor object, the OpportunityId field is a reference field that points to the Opportunity object. It contains an ID value that uniquely identifies an Opportunity record.

In some cases, an object can refer to another object of its same type. For example, an Account can have a parent link that points to another Account.

The Event and Task objects both have WhoId and WhatId cross-reference ID fields. Each of these cross-reference fields can point to one of several other objects. The WhoId field can point to a Contact or Lead, and the WhatId field can point to an Account, Opportunity, Campaign, or Case. In addition, if the WhoId field refers to a Lead, then the WhatId field must be empty.

You can describe and query each cross-referenced object. When you query a cross-reference ID field, it returns an object ID of the appropriate type. You can then query that ID to get additional information about the object, using the ID in the id field for that query.

The cross-reference ID field value is either:

The cross-reference ID field value, if non-null, is guaranteed to be an object in your organization. However, it is not guaranteed that you can query that object. Users with the “View All Data” permission can always query that object. Other users may be restricted from viewing or editing the referenced object.

When specifying a value for a cross-reference ID field in a create() or update() call, the value must be a valid value of type ID, and the user must have appropriate access to that object. The exact requirements vary from field to field.

Textarea Field Type

Textarea fields contain text that can be longer than 4000 bytes. Unlike string fields, textarea fields cannot be specified in the WHERE clause of a queryString of a query() call. To filter records on this field, you must do so while processing records in the QueryResult. For fields with this restriction, its filterable field in the Field type (described in the fields property of the DescribeSObjectResult) is false.

URL Field Type

URL fields contain URLs. Client applications are responsible for specifying valid and properly formatted URLs in create() and update() calls.

© Copyright 2000–2014 salesforce.com, inc. All rights reserved.
Various trademarks held by their respective owners.