Related Object Lookup Using the XML API

You can use a related object lookup to set the internal ID of any related object indirectly when you add, update or upsert an object if you know the external ID or the name of this related object. To do so:

1. Add the attribute external or name to each object property referencing the related object by internal ID. The attribute name determines which foreign key is used for looking up the related object.

2. For each object property referencing related object(s) by internal ID:

   1. Set the attribute value to the related object type.

   2. Pass the external ID or name instead of the internal ID as property value.

To look up the internal ID of a related object using an external ID as foreign key with the XML API, use the following syntax.

          <Modify type="ObjectType">
   <ObjectType>
      <id>internalID</id>
      <related_objectid external="RelatedObjectType">relatedObjectExternalID</related_objectid>
   </ObjectType>
</Modify> 

        

To look up the internal ID of a related object using an external ID as foreign key with the XML API, use the following syntax.

          <Modify type="ObjectType">
   <ObjectType>
      <id>internalID</id>
      <related_objectid name="RelatedObjectType">relatedObjectName</related_objectid>
   </ObjectType>
</Modify> 

        

Limitation

Related object lookup cannot be used to look up the internal ID for a generic users (User object with the property generic set to 1). It can only be used for named users (User object with the property generic set to 0).

Sample Codes

The following example updates the customer associated with a project and looks up the customer with external ID 805-25664 instead of passing the customer internal ID.

            <Modify type="Project"> 
   <Project> 
      <id>200</id>
      <customerid external="Customer">805-25664</customerid> 
   </Project> 
</Modify> 

          

The following example updates the cost center associated with a service (category) and looks up the cost center with name Maintenance instead of passing the cost center internal ID.

            <Modify type="Category"> 
   <Category> 
      <id>200</id>
      <cost_centerid name="Costcenter">Maintenance</cost_centerid> 
   </Category> 
</Modify>