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