Reference Fields

Many objects have one or more properties referencing a related object of a certain type by its internal ID value.

• Typically, the property name for a reference field ends with the letters id and references the object type of the related object, noted as per the name of the database table corresponding to this object type. For Envelope objects, for example, the userid property references the employee [user] who created and submitted the expense report [Envelope].

  Note:

  In many cases, the column name for a reference field in the database ends with an underscore (_) and the letters id, and the property name for that reference field in the XML API and SOAP API ends with the letters id without underscore. There are exceptions to this rule. Refer to the XML and SOAP API Business Object Reference, WSDL and XSD to validate your syntax.

• Some object types allow for parent-child relationships between objects of the same types. An object can reference another object of the same type, and the property name typically indicates this relationship (parentid or portfolio_projectid for example).

• Some object types have compound reference fields that allow to specify the object type as well as the internal ID of the related object. An Attachment object, for example, has an owner_type property specifying the type of object the file is attached to and an ownerid referencing one object of the specified object type by its internal ID.

• Other properties with names that do not end with the letters id can reference a related object by internal ID. Typically, the names of these other properties indicate the type of relationship. If the property holds the internal ID of an employee approving a certain type of transactions, for example, the property name includes a two-letter code representing the transaction type, such as ta for timesheets, and the word approver (ta_approver).

Whereas the internal ID field [id] is analogous to a primary key in relational databases and cannot be modified, reference fields are analogous to foreign keys and can be modified using a command performing a create or update operation.

The reference field value must either be:

• A valid internal ID (the internal ID of an existing object of the appropriate object type in your company's account data).

• In some instances such as the approver properties, for example, a negative integer representing a metavalue. See the property descriptions for accepted values.

• An empty value, which indicates an empty reference, if the reference field is not a required field.

After you read an object including reference field properties, you can read each objects referenced by internal ID to get additional information about related objects.

When you add, update or upsert an object, you can use a related object lookup to set the internal ID of any related object indirectly if you know the external ID or the name of this related object. See Adding, Updating and Upserting Objects.

For some object types, you cannot delete an object if this object is referenced by another object. For more information about dependencies preventing deletion, see XML and SOAP API Business Object Reference and the usage guidelines for individual business object type.