The API has two distinct groups of functions used for writing objects: “add” functions and “update” functions. Add functions will fail for pre-existing objects, and update functions will fail for non-existing objects. For a few objects, notably contacts, there are addOrUpdate functions which allow you to create a new object in Bronto, or, if the object already exists, update it instead. This saves the need to make multiple API calls to query for the pre-existence of an object to determine if an add or an update is necessary. This can be useful for more efficiently synchronizing contact data between your own systems and Bronto.
For add functions, many object attributes will be required. For update functions, most attributes of an object are optional and will only be changed if you provide them. Required attributes are clearly noted for each particular function; if an attribute is not required, default values are also noted. Objects to be updated may be specified by either an id or other unique key.
The maximum number of objects that may be specified per write query is 5000.
The return of an add or update function includes a writeResult object containing two conditionally included arrays. One array (called “results”) contains information on all successful objects, and another (called “errors”) contains information on problems or errors that prevented an object from being added or updated. In each array you will find response objects that include the id of the object (if it exists); a boolean indicating if a new object was created; If the result was an error, an error code and description of the problem will also be provided, as well as the original position of the object you provided to the add/update call, so that you can map back the error to your own object.