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:
-
Add the attribute
external
orname
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. -
For each object property referencing related object(s) by internal ID:
-
Set the attribute value to the related object type.
-
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>