/// <summary>
/// Create a new contact and assign it to one or more lists.
/// </summary>
/// <param name="fields">A dictionary of field IDs (as the key) and
/// the new field value (as the value).</param>
/// <param name="listIDs">An array of list IDs to assign the contact
/// to.</param>
/// <returns>A representation of the newly created contact.</returns>
public Responses.ContactEntity CreateContact(Dictionary <string, string> fields, int[] listIDs)
{
Requests.ContactEntity contact = new Requests.ContactEntity();
Requests.FieldEntity[] fieldArray = new Requests.FieldEntity[fields.Count];
int fieldCounter = 0;
foreach (KeyValuePair <string, string> f in fields)
{
Requests.FieldEntity fieldEntity = new Requests.FieldEntity();
fieldEntity.ID = f.Key;
fieldEntity.Value = f.Value;
fieldArray[fieldCounter++] = fieldEntity;
}
contact.Fields = fieldArray;
if (listIDs.Length > 0)
{
int listCounter = 0;
Requests.ListEntity[] listArray = new Requests.ListEntity[listIDs.Length];
foreach (int id in listIDs)
{
Requests.ListEntity listEntity = new Requests.ListEntity();
listEntity.ID = id;
listArray[listCounter++] = listEntity;
}
contact.ListIds = listArray;
}
contact.ID = null;
return(this.connection.Call <Responses.ContactEntity>("POST", "contactmanager/contacts", null, contact));
}
/// <summary>
/// Update the field values of the given contact.
/// </summary>
/// <param name="contactID">The ID of the contact to update.</param>
/// <param name="fields">A dictionary of field IDs (as the key) and
/// the new field value (as the value).</param>
/// <returns>A representation of the updated contact.</returns>
public Responses.ContactEntity UpdateContact(int contactID, Dictionary <string, string> fields)
{
Requests.ContactEntity contact = new Requests.ContactEntity();
Requests.FieldEntity[] fieldArray = new Requests.FieldEntity[fields.Count];
int fieldCounter = 0;
foreach (KeyValuePair <string, string> f in fields)
{
Requests.FieldEntity fieldEntity = new Requests.FieldEntity();
fieldEntity.ID = f.Key;
fieldEntity.Value = f.Value;
fieldArray[fieldCounter++] = fieldEntity;
}
contact.Fields = fieldArray;
return(this.connection.Call <Responses.ContactEntity>("POST", "contactmanager/contacts/" + contactID, null, contact));
}
/// <summary>
/// Example of creating multiple contacts via batch. Also provides an
/// example of updating existing contacts by merging upon an existing
/// column (this will create a new contact if there are no merge
/// candidates).
///
/// Note that this is functionality is not backwards-compatible with
/// version 1.1. Because merging upon a column could return one or
/// more contact responses (if multiple merge candidates are found),
/// ContactBatchResult now contains a ContactCollection object instead
/// of a ContactEntity object. The example is updated to show the new
/// usage.
/// </summary>
public void ContactBatchExample()
{
//Get the email and name column IDs. You should probably do validation on the response ;)
string emailColumnID = api.ContactManager.GetColumnsByName("email").Columns[0].ID;
string nameColumnID = api.ContactManager.GetColumnsByName("name").Columns[0].ID;
//Precreate a contact to test the 'upsert' merge functionality.
Dictionary <string, string> fields = new Dictionary <string, string>();
fields.Add(emailColumnID, "*****@*****.**");
fields.Add(nameColumnID, "This name should be overwritten");
ContactManager.Responses.ContactEntity contact = api.ContactManager.CreateContact(fields);
Console.WriteLine("Created inital contact (ID: " + contact.ID + ") with name '" + contact.GetFieldsByName("name")[0].Value + "'.");
List <ContactManager.Requests.ContactEntity> contacts = new List <ContactManager.Requests.ContactEntity>();
for (int i = 0; i < 3; i++)
{
ContactManager.Requests.ContactEntity c = new ContactManager.Requests.ContactEntity();
c.Fields = new ContactManager.Requests.FieldEntity[] {
new ContactManager.Requests.FieldEntity(emailColumnID, "example+" + i + "@example.com"),
new ContactManager.Requests.FieldEntity(nameColumnID, "Jane Doe")
};
contacts.Add(c);
}
Console.WriteLine("Submitting " + contacts.Count.ToString() + " contacts to a batch create.");
//Supply the email column as the merge row.
ContactManager.Responses.ContactBatchResponse response = api.ContactManager.BatchCreateContacts(contacts.ToArray(), emailColumnID);
Console.WriteLine("Submitted batch job. ID is " + response.ID.ToString() + ".");
// Wait for the batch to complete.
do
{
response = api.ContactManager.GetBatchStatus(response.ID);
Console.WriteLine("[" + System.DateTime.Now.ToLongTimeString() + "] Current status is: " + response.Status.ToString());
System.Threading.Thread.Sleep(5000);
} while (response.Status != ContactManager.Responses.ContactBatchResponse.BatchStatus.Complete &&
response.Status != ContactManager.Responses.ContactBatchResponse.BatchStatus.Error);
ContactManager.Responses.ContactBatchResultCollection results = api.ContactManager.GetBatchResult(response.ID);
foreach (ContactManager.Responses.ContactBatchResult result in results.Results)
{
//Output information about the created contacts, showing that we did indeed merge the
//new contact information in. We're assuming that there is only one contact returned
//as a result of each contact batch operation in the request, but there could be more.
Console.WriteLine("Created / updated contact " + result.ContactCollection.Contacts[0].ID + " (" +
result.ContactCollection.Contacts[0].GetFieldsByName("email")[0].Value + " / " +
result.ContactCollection.Contacts[0].GetFieldsByName("name")[0].Value + ").");
Console.WriteLine("Cleaning up: removing contact " + result.ContactCollection.Contacts[0].ID + ".");
api.ContactManager.DeleteContact(result.ContactCollection.Contacts[0].ID);
}
Console.Write("Press enter to continue...");
Console.ReadLine();
}
/// <summary>
/// Perform an upsert operation by either creating a contact or merging
/// the given data into all contacts that match the provided merge
/// column. For example, if the email field is provided in the fields
/// parameter and is also specified as the merge column, all contacts
/// with that email value will have their entries updated with the new
/// data. If there is no match, a new contact will be created.
/// </summary>
/// <param name="fields">The fields to create / update.</param>
/// <param name="mergeColumnID">The column ID to merge upon.</param>
/// <returns>A collection containing all contacts modified by the
/// <param name="listIDs">An array of list IDs to add the contact(s) to.
/// </param>
/// operation.</returns>
public Responses.ContactCollection UpsertContact(Dictionary <string, string> fields, string mergeColumnID, int[] listIDs)
{
Dictionary <string, string> queryParameters = new Dictionary <string, string>();
queryParameters.Add("mergecolumn", mergeColumnID);
Requests.ContactEntity contact = new Requests.ContactEntity();
Requests.FieldEntity[] fieldArray = new Requests.FieldEntity[fields.Count];
int fieldCounter = 0;
foreach (KeyValuePair <string, string> f in fields)
{
Requests.FieldEntity fieldEntity = new Requests.FieldEntity();
fieldEntity.ID = f.Key;
fieldEntity.Value = f.Value;
fieldArray[fieldCounter++] = fieldEntity;
}
contact.Fields = fieldArray;
if (listIDs.Length > 0)
{
int listCounter = 0;
Requests.ListEntity[] listArray = new Requests.ListEntity[listIDs.Length];
foreach (int id in listIDs)
{
Requests.ListEntity listEntity = new Requests.ListEntity();
listEntity.ID = id;
listArray[listCounter++] = listEntity;
}
contact.ListIds = listArray;
}
contact.ID = null;
string xml = this.connection.Call <string>("POST", "contactmanager/contacts", queryParameters, contact);
//We're going to deserialize ourselves, since the response could be
//either a contact collection or a contact entity. We're going to
//turn the contact entity into a collection for consistency.
using (System.Xml.XmlReader reader = new System.Xml.XmlTextReader(new System.IO.StringReader(xml)))
{
//If it's a collection, return it.
System.Xml.Serialization.XmlSerializer serializer = new System.Xml.Serialization.XmlSerializer(typeof(Responses.ContactCollection));
if (serializer.CanDeserialize(reader))
{
return((Responses.ContactCollection)serializer.Deserialize(reader));
}
serializer = new System.Xml.Serialization.XmlSerializer(typeof(Responses.ContactEntity));
//If it's an entity, create a collection and put the contact in it.
if (serializer.CanDeserialize(reader))
{
Responses.ContactEntity c = (Responses.ContactEntity)serializer.Deserialize(reader);
Responses.ContactCollection contactCollection = new Responses.ContactCollection();
contactCollection.Contacts = new Responses.ContactEntity[] { (Responses.ContactEntity)c };
return(contactCollection);
}
else
{
throw new Exception("Invalid XML response: could not deserialize into a ContactEntity or ContactCollection.");
}
}
}