Contacts (CONTACT.SVC)

Introduction

This provides access to the contacts data. These services directly affect the contacts table. The service provides the following services:

  • UpdateAdd: This combines the update and add operations into one service call.
  • Update: Update contact records.
  • Add: Add contact records.
  • GetContacts: Retrieve a contact record.
  • DeleteContacts: Delete a contact.
  • ChangeOptOutStatus: Change optout status of a contact.
  • ChangeStatus: Change general status of a contact.
  • UpdateExLinkID: Update external contact ID for a contact.
  • Merge: Merge two contact records.

Example Service: http://newsletter.ie/wcf/Contact.svc

UPDATEADD / UPDATE / ADD

These three service calls take the same parameters, described in one block.

  • AddUpdate: A combined add/update operation. Firstly an attempt is made to update the contact and if this fails because the contact does not exist it is then added to the database.
  • Update: Straight update if this fails because the record cannot be found and error is returned.
  • Add: Straight add - if add fails an error is returned.
Input Parameters
Parameter Description Type
Token Token String
Contact Contact Array of Values Array
Options Options Object
ReturnFailedRequests True failed requests are returned in the failed requests array. Only use this if required as it will reduce throughput and bloat the response object. Bool
UpdateByKey What key should be used to perform the update. If updating using a foreign/external key, use 'exlinkid'. If using email address, use 'email'. Leave blank to use native key. String
Sample
							
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<UpdateAdd xmlns="http://wcf.spinnakerpro.net/1.0">
<Token>bac37743-57e9-470c-8489-79c54c71150f</Token>
<Contact xmlns:a="urn:spinnakerpro.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:Contact>
<a:ContactData>
<a:BusCity i:nil="true"/>
<a:BusCountry i:nil="true"/>
<a:BusName i:nil="true"/>
<a:BusState i:nil="true"/>
<a:BusStreet i:nil="true"/>
<a:BusStreet1 i:nil="true"/>
<a:BusWebSite i:nil="true"/>
<a:BusZip i:nil="true"/>
<a:BusinessEmail i:nil="true"/>
<a:BusinessEmail1 i:nil="true"/>
<a:BusinessFax i:nil="true"/>
<a:Categories i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
<a:ContactId>0</a:ContactId>
<a:ContactType>0</a:ContactType>
<a:Date1>0001-01-01T00:00:00</a:Date1>
<a:Date2>0001-01-01T00:00:00</a:Date2>
<a:Date3>0001-01-01T00:00:00</a:Date3>
<a:Date4>0001-01-01T00:00:00</a:Date4>
<a:Date5>0001-01-01T00:00:00</a:Date5>
<a:DateOfLastPurchase>0001-01-01T00:00:00</a:DateOfLastPurchase>
<a:DateofBirth>0001-01-01T00:00:00</a:DateofBirth>
<a:ExtLinkId>Unique_Id_From_CRM0</a:ExtLinkId>
<a:ExtLinkIdField>Unique_Id_Field_Name</a:ExtLinkIdField>
<a:ExtLinkIdGuid>00000000-0000-0000-0000-000000000000</a:ExtLinkIdGuid>
<a:ExtLinkIdGuidField i:nil="true"/>
<a:ExtLinkIdNum>0</a:ExtLinkIdNum>
<a:ExtLinkIdNumField i:nil="true"/>
<a:FirstName>John</a:FirstName>
<a:Gender i:nil="true"/>
<a:GlobalId>00000000-0000-0000-0000-000000000000</a:GlobalId>
<a:GroupBy1 i:nil="true"/>
<a:GroupBy2 i:nil="true"/>
<a:GroupBy3 i:nil="true"/>
<a:GroupByIndustry i:nil="true"/>
<a:HomeFax i:nil="true"/>
<a:ImportId>00000000-0000-0000-0000-000000000000</a:ImportId>
<a:ImportName i:nil="true"/>
<a:InFix i:nil="true"/>
<a:InfoObtainedFrom i:nil="true"/>
<a:JobTitle i:nil="true"/>
<a:LastBroadCastDate>0001-01-01T00:00:00</a:LastBroadCastDate>
<a:LastName>James 0</a:LastName>
<a:LastReponseDate>0001-01-01T00:00:00</a:LastReponseDate>
<a:LastUpdatedById>0</a:LastUpdatedById>
<a:LastUpdatedByUser i:nil="true"/>
<a:LinkId>00000000-0000-0000-0000-000000000000</a:LinkId>
<a:Loyalty>0</a:Loyalty>
<a:MapId>0</a:MapId>
<a:MessagePreference i:nil="true"/>
<a:Name i:nil="true"/>
<a:Num1>0</a:Num1>
<a:Num2>0</a:Num2>
<a:Num3>0</a:Num3>
<a:Num4>0</a:Num4>
<a:Num5>0</a:Num5>
<a:OptOut>In</a:OptOut>
<a:OrgId>0</a:OrgId>
<a:OrginalEMail i:nil="true"/>
<a:OrginalOptOut>In</a:OrginalOptOut>
<a:OtherPhone i:nil="true"/>
<a:Pager i:nil="true"/>
<a:Password i:nil="true"/>
<a:PerCity i:nil="true"/>
<a:PerCountry i:nil="true"/>
<a:PerState i:nil="true"/>
<a:PerStreet i:nil="true"/>
<a:PerStreet1 i:nil="true"/>
<a:PerZip i:nil="true"/>
<a:PersonalEMail>genericEmailAddress0@man.com</a:PersonalEMail>
<a:PersonalEmail1 i:nil="true"/>
<a:PhoneBusiness i:nil="true"/>
<a:PhoneHome i:nil="true"/>
<a:PhoneMobile i:nil="true"/>
<a:PhoneOther i:nil="true"/>
<a:Privacy i:nil="true"/>
<a:ReferedById>0</a:ReferedById>
<a:RestrictEmails i:nil="true"/>
<a:Status>Ok</a:Status>
<a:SyncDate>0001-01-01T00:00:00</a:SyncDate>
<a:Title i:nil="true"/>
<a:TotalBroadCasts>0</a:TotalBroadCasts>
<a:TotalResponses>0</a:TotalResponses>
<a:UserChar10 i:nil="true"/>
<a:UserChar11 i:nil="true"/>
<a:UserChar12 i:nil="true"/>
<a:UserChar13 i:nil="true"/>
<a:UserChar14 i:nil="true"/>
<a:UserChar15 i:nil="true"/>
<a:UserChar2 i:nil="true"/>
<a:UserChar3 i:nil="true"/>
<a:UserChar4 i:nil="true"/>
<a:UserChar5 i:nil="true"/>
<a:UserChar6 i:nil="true"/>
<a:UserChar7 i:nil="true"/>
<a:UserChar8 i:nil="true"/>
<a:UserChar9 i:nil="true"/>
<a:YearlyPurchase>0</a:YearlyPurchase>
</a:ContactData>
</a:Contact>
<a:Options i:nil="true"/>
<a:ReturnFailedRequests>false</a:ReturnFailedRequests>
<a:UpdateByKey>extlinkid</a:UpdateByKey>
</Contact>
</UpdateAdd>
</s:Body>
</s:Envelope>
Output
UpdResponse (object)
  • Result (object see determine the success or failure of a service call)
  • UpdateCount (int) total records updated.
  • AddCount (int) total records added.
  • FailedRequests (array) array/adds of updates that failed. Only returned if "returnfailedrequest" is set to true on request.

GETCONTACTS

Get contact record. This service is used to retrieve a contact from the database. The contact can be retrieved by email address, by external key, or by native contact ID. Depending on how you want to retrieve the contact records, add the key to the appropriate collection in the request object below.

Input Parameters
Parameter Description Type
GetRequest Request Object. Use one of the following three types. Object
- ExtLinkIds Get Contact by External/Foreign Keys String Array
- EmailAddress Get Contact by Email Address String Array
- Contactids Get Contact by Internal Contact ID Long Array
Sample
							
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetContacts xmlns="http://wcf.spinnakerpro.net/1.0">
<Token>1d5c1237-bfd4-431c-96be-8b664e586d94</Token>
<Contact xmlns:a="urn:spinnakerpro.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:ContactIds i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
<a:EmailAddress i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
<a:ExtLinkIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<b:string>Unique_Id_From_CRM0</b:string>
<b:string>Unique_Id_From_CRM1</b:string>
</a:ExtLinkIds>
</Contact>
</GetContacts>
</s:Body>
</s:Envelope>
Output
GetResponse (object)
  • Result (object see determine the success or failure of a service call)
  • Contacts (array of contacts) list of retrieved contacts.

DELETECONTACTS

This service is used to delete a contact from the database. It is possible to delete contacts by email address, by external key, or by native contacted ID. Note: once a contact has been broadcasted to, they cannot be deleted to preserve their opt out status.

Input Parameters
Parameter Description Type
DeleteRequest Request Object. Use one of the following three types. Object
- ExtLinkIds Get Contact by External/Foreign Keys String Array
- EmailAddress Get Contact by Email Address String Array
- Contactids Get Contact by Internal Contact ID Long Array
ReturnFailedRequests Return requests which have failed. If set to true, this will cause the message response to increase in size Bool
Sample
							
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<DeleteContacts xmlns="http://wcf.spinnakerpro.net/1.0">
<Token>498b8acc-b4f3-41f8-9157-78ff082517be</Token>
<Contact xmlns:a="urn:spinnakerpro.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:ContactIds i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
<a:EmailAddress i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
<a:ExtLinkIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<b:string>Unique_Id_From_CRM0</b:string>
</a:ExtLinkIds>
<a:ReturnFailedRequests>true</a:ReturnFailedRequests>
</Contact>
</DeleteContacts>
</s:Body>
</s:Envelope>
Output
GetResponse (object)
  • Result (object see determine the success or failure of a service call)
  • Contacts (array of contacts) list of retrieved contacts.

CHANGEOPTOUTSTATUS

This service is used to change the opt out status for a contact. If they have opted out they will not be emailed.

Input Parameters
Parameter Description Type
StatusChangeRequest Request Object. Use one of the following three types. Object
- ExtLinkIds Get Contact by External/Foreign Keys String Array
- EmailAddress Get Contact by Email Address String Array
- Contactids Get Contact by Internal Contact ID Long Array
ReturnFailedRequests Return requests which have failed. If set to true, this will cause the message response to increase in size Bool
Status Status which contacts listed will be set to
-10: Opted Out
-5: Pending Opt In
0: Opted In
Int
Sample
							
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<ChangeOptoutStatus xmlns="http://wcf.spinnakerpro.net/1.0">
<Token/>
<Contact xmlns:a="urn:spinnakerpro.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:ContactIds i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
<a:EmailAddress i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
<a:ExtLinkIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<b:string>Unique_Id_From_CRM0</b:string>
</a:ExtLinkIds>
<a:ReturnFailedRequests>true</a:ReturnFailedRequests>
<a:Status>-10</a:Status>
</Contact>
</ChangeOptoutStatus>
</s:Body>
</s:Envelope>
Output
StatusChangeResponse (object)
  • Result (object see determine the success or failure of a service call)
  • FailedRequests (array of objects) this will contain the key (either string or long) which failed to update the contact.

CHANGESTATUS

This service is used to change the general status for a contact.

Input Parameters
Parameter Description Type
StatusChangeRequest Request Object. Use one of the following three types. Object
- ExtLinkIds Get Contact by External/Foreign Keys String Array
- EmailAddress Get Contact by Email Address String Array
- Contactids Get Contact by Internal Contact ID Long Array
ReturnFailedRequests Return requests which have failed. If set to true, this will cause the message response to increase in size Bool
Status Status which contacts listed will be set to
0: Active
10: Referred
20: Inactive
-10: Bounced/Rejected
Int
Sample
							
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<ChangeStatus xmlns="http://wcf.spinnakerpro.net/1.0">
<Token>70d8f930-2a7b-46d1-8eca-29cf4bb6142b</Token>
<Contact xmlns:a="urn:spinnakerpro.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:ContactIds i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
<a:EmailAddress i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
<a:ExtLinkIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<b:string>Unique_Id_From_CRM1</b:string>
</a:ExtLinkIds>
<a:ReturnFailedRequests>true</a:ReturnFailedRequests>
<a:Status>20</a:Status>
</Contact>
</ChangeStatus>
</s:Body>
</s:Envelope>
Output
StatusChangeResponse (object)
  • Result (object see determine the success or failure of a service call)
  • FailedRequests (array of objects) this will contain the key (either string or long) which failed to update the contact.

UPDATEEXLINKID

This service is used to update the external link id (exlinkid) for the contact.

Input Parameters
Parameter Description Type
ReturnFailedRequests Return requests which have failed. If set to true this will cause the message response to increase in size Bool
OldKeyNewKeyCollection Named pairs containing old key and new key Array
- OldKey Old Key String String
- NewKey New Key String String
Sample
							
<?xml version="1.0" encoding="utf-8" ?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<UpdateExtLinkID xmlns="http://wcf.spinnakerpro.net/1.0">
<Token>c0573b24-d587-4042-9f9d-64ecb6df1ef3</Token>
<Contact xmlns:a="urn:spinnakerpro.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:Result i:nil="true"/>
<a:OldKeyNewKeyCollection>
<a:ExtLinkIdPair>
<a:NewKey>Unique_Id_From_CRM2</a:NewKey>
<a:OldKey>Unique_Id_From_CRM1</a:OldKey>
</a:ExtLinkIdPair>
</a:OldKeyNewKeyCollection>
<a:ReturnFailedRequests>false</a:ReturnFailedRequests>
</Contact>
</UpdateExtLinkID>
</s:Body>
</s:Envelope>
Output
  • UpdateExtLinkIdResponse (object)
    • Result (object see determine the success or failure of a service call)
    • FailedRequests (array of ExtLinkIdPair)
      • ExtLinkIdPair
        • OldKey (string) old key string
        • NewKey (string) new key string

MERGE

Merge two contacts. Can be used after a de-duplication process in a CRM system.

Input Parameters
Parameter Description Type
MergeRequest Merge Request Data Object
- Token Named pairs containing old key and new key String
- Newcontact New Contact Data Object
- NewExtLinkID New Key String String
- OldExtLinkID New Key String String
Sample
							
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<Merge xmlns="http://wcf.spinnakerpro.net/1.0">
<Token>113e50f9-ecaf-4f4e-94bb-dc8eb592949f</Token>
<UpdateContactExtLinkId xmlns:a="urn:spinnakerpro.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:NewContact>
<a:BusCity i:nil="true"/>
<a:BusCountry i:nil="true"/>
<a:BusName i:nil="true"/>
<a:BusState i:nil="true"/>
<a:BusStreet i:nil="true"/>
<a:BusStreet1 i:nil="true"/>
<a:BusWebSite i:nil="true"/>
<a:BusZip i:nil="true"/>
<a:BusinessEmail i:nil="true"/>
<a:BusinessEmail1 i:nil="true"/>
<a:BusinessFax i:nil="true"/>
<a:Categories i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
<a:ContactId>0</a:ContactId>
<a:ContactType>0</a:ContactType>
<a:Date1>0001-01-01T00:00:00</a:Date1>
<a:Date2>0001-01-01T00:00:00</a:Date2>
<a:Date3>0001-01-01T00:00:00</a:Date3>
<a:Date4>0001-01-01T00:00:00</a:Date4>
<a:Date5>0001-01-01T00:00:00</a:Date5>
<a:DateOfLastPurchase>0001-01-01T00:00:00</a:DateOfLastPurchase>
<a:DateofBirth>0001-01-01T00:00:00</a:DateofBirth>
<a:ExtLinkId i:nil="true"/>
<a:ExtLinkIdField i:nil="true"/>
<a:ExtLinkIdGuid>00000000-0000-0000-0000-000000000000</a:ExtLinkIdGuid>
<a:ExtLinkIdGuidField i:nil="true"/>
<a:ExtLinkIdNum>0</a:ExtLinkIdNum>
<a:ExtLinkIdNumField i:nil="true"/>
<a:FirstName>Richard </a:FirstName>
<a:Gender i:nil="true"/>
<a:GlobalId>00000000-0000-0000-0000-000000000000</a:GlobalId>
<a:GroupBy1 i:nil="true"/>
<a:GroupBy2 i:nil="true"/>
<a:GroupBy3 i:nil="true"/>
<a:GroupByIndustry i:nil="true"/>
<a:HomeFax i:nil="true"/>
<a:ImportId>00000000-0000-0000-0000-000000000000</a:ImportId>
<a:ImportName i:nil="true"/>
<a:InFix i:nil="true"/>
<a:InfoObtainedFrom i:nil="true"/>
<a:JobTitle i:nil="true"/>
<a:LastBroadCastDate>0001-01-01T00:00:00</a:LastBroadCastDate>
<a:LastName>Smith </a:LastName>
<a:LastReponseDate>0001-01-01T00:00:00</a:LastReponseDate>
<a:LastUpdatedById>0</a:LastUpdatedById>
<a:LastUpdatedByUser i:nil="true"/>
<a:LinkId>00000000-0000-0000-0000-000000000000</a:LinkId>
<a:Loyalty>0</a:Loyalty>
<a:MapId>0</a:MapId>
<a:MessagePreference i:nil="true"/>
<a:Name i:nil="true"/>
<a:Num1>0</a:Num1>
<a:Num2>0</a:Num2>
<a:Num3>0</a:Num3>
<a:Num4>0</a:Num4>
<a:Num5>0</a:Num5>
<a:OptOut>In</a:OptOut>
<a:OrgId>0</a:OrgId>
<a:OrginalEMail i:nil="true"/>
<a:OrginalOptOut>In</a:OrginalOptOut>
<a:OtherPhone i:nil="true"/>
<a:Pager i:nil="true"/>
<a:Password i:nil="true"/>
<a:PerCity i:nil="true"/>
<a:PerCountry i:nil="true"/>
<a:PerState i:nil="true"/>
<a:PerStreet i:nil="true"/>
<a:PerStreet1 i:nil="true"/>
<a:PerZip i:nil="true"/>
<a:PersonalEMail>rsmith@gamil.com</a:PersonalEMail>
<a:PersonalEmail1 i:nil="true"/>
<a:PhoneBusiness i:nil="true"/>
<a:PhoneHome i:nil="true"/>
<a:PhoneMobile i:nil="true"/>
<a:PhoneOther i:nil="true"/>
<a:Privacy i:nil="true"/>
<a:ReferedById>0</a:ReferedById>
<a:RestrictEmails i:nil="true"/>
<a:Status>Ok</a:Status>
<a:SyncDate>0001-01-01T00:00:00</a:SyncDate>
<a:Title i:nil="true"/>
<a:TotalBroadCasts>0</a:TotalBroadCasts>
<a:TotalResponses>0</a:TotalResponses>
<a:UserChar10 i:nil="true"/>
<a:UserChar11 i:nil="true"/>
<a:UserChar12 i:nil="true"/>
<a:UserChar13 i:nil="true"/>
<a:UserChar14 i:nil="true"/>
<a:UserChar15 i:nil="true"/>
<a:UserChar2 i:nil="true"/>
<a:UserChar3 i:nil="true"/>
<a:UserChar4 i:nil="true"/>
<a:UserChar5 i:nil="true"/>
<a:UserChar6 i:nil="true"/>
<a:UserChar7 i:nil="true"/>
<a:UserChar8 i:nil="true"/>
<a:UserChar9 i:nil="true"/>
<a:YearlyPurchase>0</a:YearlyPurchase>
</a:NewContact>
<a:NewExtLinkId>Unique_Id_From_CRM0</a:NewExtLinkId>
<a:OldExtLinkId>Unique_Id_From_CRM2</a:OldExtLinkId>
<a:Options i:nil="true"/>
<a:ReturnFailedRequests>false</a:ReturnFailedRequests>
</UpdateContactExtLinkId>
</Merge>
</s:Body>
</s:Envelope>
Output
  • UpdateExtLinkIdResponse (object)
    • Result (object see determine the success or failure of a service call)
    • FailedRequests (array of ExtLinkIdPair)
      • ExtLinkIdPair
        • OldKey (string) old key string
        • NewKey (string) new key string

Merge Logic.

This is a scenario where two records are de-duplicated in CRM. This is the process of merging two records into one. In SensorPro the following situation may exist:

  • Neither of these records may exist in SensorPro
  • The deleted record in CRM may exist in SensorPro
  • The merged record in CRM may exist in SensorPro
  • Both records may exist in SensorPro
  • The email address being used on the merged person may already exist in SensorPro, thus preventing the update.

The terminology used is as follows:

  • Deleted contact – the person which was deleted in CRM after merge process
  • Merged contact – the person which remains after the merge process in CRM

The logic is as follows:

  • If (deleted contact record Exists AND the merged contact record does Not Exist in SensorPro)
    • Set the external link (exlinkid) in SensorPro to the merged person (CRM unique id)
    • This record will be used as the new record for the new merged contact later in the process
  • If (both deleted person and merged person exist in SensorPro)
    • Delete the deleted person from SensorPro
  • If (this contact cannot be deleted because he has been broadcasted to)
    • Set the status to inactive
    • Set the optout / unsubscribe status to opted out
    • Set email address to deduped@new Guid().com (prevents email address clash)
    • Update the contact
  • If (the email address already exists in SensorPro)
    • EXIT cannot have duplicate email address in SensorPro
  • Else
    • If (neither deleted person or merged person existed in SensorPro)
      • Add merged person as new contact
    • Else – Update one of the existing records (deleted contact or merged contact in SensorPro)
  • If (deleted person existed in SensorPro and merged person does not exist in SensorPro)
    • Update deleted contact in SensorPro with merged contact details
  • Else
    • Update merged contact in SensorPro with merged person data

Is this something you could use?