ABContactAPI methods

The ContactManager ABContactAPI web service provides the following methods.

Method	Parameters	Description
`createContact`	abContactXML – Contact information in `XmlBackedInstance` format.	Creates a new contact and returns an AddressBookUIDContainer containing IDs for the Contact and child objects. Contact information is expected to be in XmlBackedInstance format. If the abContactXML parameter includes an `External_UniqueID` field and that field has a value, ContactManager uses this value to populate the `LinkID` field. In this manner, the calling application specifies the ultimate value of the `LinkID`. If the `External_UniqueID` field is missing or is `null`, ContactManager generates its own `LinkID` and passes it back to the calling application. ContactManager determines if the unique ID passed to ContactManager for any ABLinkable entity in the ABContact graph already exists on an entity of that type, including retired entities. If so, ContactManager throws a `DuplicateKeyException` for the call to `createContact`. In this case, the contact is not created in ContactManager. It is up to the calling application to recover from this state, either by providing a new unique ID or allowing ContactManager to create a unique ID. Calls ValidateABContactCreationPlugin to ensure that there is enough data to create the contact. If not, the method returns `RequiredFieldException` to the calling application. If there is enough data, the method creates a new ABContact of the subtype specified by `abContactXML`. The method then populates the new entity with data it retrieves by calling ContactIntegrationMapper.populateABContactFromXML.
`createContactPendingApproval`	abContactXML – Contact information in XmlBackedInstance format. updateContext – User, entity, and application information sent by core application. An instance of ABContactAPIPendingContactChange.	Creates a new contact of the type specified and sets its status to `PENDING_APPROVAL`. Returns an AddressBookUIDContainer containing IDs for the Contact and child objects and the update context and transaction ID. This method is called by the core application because the core application user creating the contact does not have permission to create a contact. Contact information is expected to be in XmlBackedInstance format. Calls ValidateABContactCreationPlugin to ensure that there is enough data to create the contact. If not, the method returns `RequiredFieldException` to the calling application. If there is enough data and no other exceptions are thrown, the method creates a new ABContact of the subtype specified by `abContactXML`. The method then populates the new entity with data it retrieves by calling ContactIntegrationMapper.populateABContactFromXML and sets its status to `PENDING_APPROVAL`.
`findDuplicates`	abContactXML – XmlBackedInstance that contains the contact data for which duplicates are being found. abContactAPISearchSpec – Specifies how the search is to be returned.	Finds contacts that match the specified contact. Returns an ABContactAPIFindDuplicatesResultContainer object containing summary information about each match.
`getReplacementAddress`	addressLinkID – `linkID` of an address that has been replaced because of a merge	Gets the address that has replaced the address passed in the parameter. An address can be replaced as a part of a merge. Returns the `linkID` of the address that replaces the address denoted by the argument.
`getReplacementContact`	contactLinkID – `linkID` of a contact that has been replaced because of a merge	Gets the contact that has replaced the contact passed in the parameter. A contact can be replaced as a result of a merge. Returns the `linkID` of the contact that replaces the contact denoted by the argument, or `null` if the contact has not been replaced by another contact.
`getSpecialistServices`	contactLinkID – `linkID` of the contact that has specialist services	Gets the specialist services associated with the contact passed in the parameter. Returns an array of ABContactAPISpecialistService objects, or `null` if the contact has no specialist services.
`removeContact`	abContactXML – XmlBackedInstance that contains the `linkID` of the contact to be removed and miscellaneous information.	Removes the contact with the matching `linkID` if the contact is not being used by any remote application. If a remote application is not running when this method runs, the contact is assumed to be in use and is not removed. Returns a `Boolean` indicating whether the contact was successfully removed.
`retrieveContact`	linkID – ID uniquely associated with this contact. In a core application, this value is the `AddressBookUID`.	Retrieves information about the contact uniquely specified by the `linkID`. Returns contact information in XmlBackedInstance format.
`retrieveDocumentsforContact`	contactLinkID – ID uniquely associated with this contact. In a core application, this value is the `AddressBookUID`. abContactAPIDocumentSearchCriteria – The criteria for the search. Required and cannot be `null`. abContactAPIDocumentSearchSpec – Specifications for how the results are to be returned.	Retrieves information about the contact’s documents. Returns document information in ABContactAPIDocumentSearchResultContainer format.
`retrieveRelatedContacts`	linkID – ID uniquely associated with this contact relationshipTypes – Array of ContactBidiRel relationship types of the related contacts to return information on. If `null`, then no restriction is enforced on the related contacts returned.	Retrieves information about the contact's related contacts. Returns a RelatedContactInfoContainer containing information about the contact's related contacts.
`searchContact`	abContactAPISearchCriteria – Criteria for the search. This parameter must not be null. abContactAPISearchSpec – Specifies how the results are to be returned.	Searches for all contacts that match the given search criteria. Return an ABContactAPISearchResultContainer object containing the search results.
`updateContact`	abContactXML – Contact information in XmlBackedInstance format.	Updates an existing contact and returns an AddressBookUIDContainer object containing IDs for the `Contact` and child objects. Contact information is expected to be in XmlBackedInstance format. An existing ABContact is selected based on the `abContactXML.LinKID`. If none is found, the method throws `BadIdentifierException`. Then, `origValue` attributes for all fields and foreign keys being updated are checked against those same values in the selected ABContact. If discrepancies are found, the method throws `EntityStateException`. The purpose is to manage versioning of contact-related changes across multiple client applications. If no exceptions have yet been thrown, the method calls ContactIntegrationMapper.populateABContactFromXML to update the data for local entities from `abContactXML`.
`updateContactPendingApproval`	abContactXML – Contact information in XmlBackedInstance format. updateContext – User, entity, and application information sent by core application.	Submits for approval an update to an existing contact that is pending until approved. The core application calling this method has determined that the user updating the contact does not have permission to do so. Contact information is expected to be in XmlBackedInstance format. If no existing ABContact can be found based on the `abContactXML.LinKID`, the method throws `BadIdentifierException`. If an ABContact entity is found with this `LinkID`, this method creates a PendingUpdate entity for the contact.
`validateCreateContact`	abContactXML – Contact information in XmlBackedInstance format.	Determines if the specified contact can be created. Calls ValidateABContactCreationPlugin.validateCanCreate to see if `abContactXML` has the minimum data required to create an ABContact entity. Returns an ABContactAPIValidateCreateContactResult object indicating whether validation passed and, if validation failed, an error message. For more information, see ValidateABContactCreationPlugin plugin interface.