Adding, Updating and Upserting Objects
Use the Add
(XML API) or add()
(SOAP API) command to add objects of a supported type except User
objects.
Use the CreateUser
(XML API) or createUser()
(SOAP API) command to add User
objects.
Use the Modify
(XML API), ModifyOnCondition
(XML API) or modify()
(SOAP API) command to update objects of a supported type including User
objects.
Use the Add
(XML API) or upsert()
(SOAP API) command to upsert objects of a supported type.
Upserts use a lookup field to determine whether it adds or updates an object:
-
If the lookup field is not matched in any existing objects, a new object is added.
-
If the lookup field is matched one time, the existing object is updated.
These commands pass the following parameters and arguments:
-
type
— (XML API only) You must specify the type of object you want to add, update or upsert. For information about supported object types, see List of Supported Business Object Types. -
Attributes — You can use attributes to set custom field values or to look up objects with a matching object property value when adding, updating and upserting objects using the XML API or SOAP API. See Add, Update and Upsert Attributes.
-
Objects — All command must include the object(s) to be added, updated or upserted as argument. The
CreateUser
(XML API) orcreateUser()
(SOAP API) command also requires theCompany
object as argument. See the command descriptions for details.In the argument object properties, 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. The API looks up the internal ID of the related object using the external ID [
externalid
] or name [name
] as foreign key and set the internal ID if a unique object matching the foreign key can be found. See Related Object Lookup Using the XML API and Related Object Lookup Using the SOAP API.