So, you've read the Where can I find the documentation for the Eloqua API, have been granted access, and gottenConnecting to the Eloqua API - Generic Setup to the Eloqua Web Services API via code. 


Now it's time to play!


This series of How To posts will focus on code snippits that show examples of what can be done using the API. 


Let's start with something basic...


The code below will illustrate how to query a Contact by e-mail address, and list some details of the returned record.


Note: we will assume that the code from Connecting to the Eloqua API - Generic Setup is also being used.



    class RetrieveContactByEmail
        static void Main()
            const string searchQuery = "C_EmailAddress=''";

               //Create the service instance using your credentials

               EloquaInstance service = new EloquaInstance("instance", "userid", "password");
                // Instantiate a Contact Entity Type
                EntityType contactEntityType = new EntityType
                                                ID = 0,
                                                Name = "Contact",
                                                Type = "Base"

                // Create a new list containing the fields you want populated
                List<string> fieldList = new List<string> { "C_EmailAddress", "C_FirstName", "C_LastName" };
                // Define a container for the Query results
                DynamicEntityQueryResults queryResult;


                // Set the page number and size for the results
                const int currentPage = 1;
                const int pageSize = 20;


                // If the field list is empty - the request will return all Entity Fields
                // Otherwise, only fields defined in the field list are returned
                if (fieldList.Count == 0)
                    // Execute the request and return all of the Entity's fields
                    queryResult = service.ServiceProxy.Query(contactEntityType, searchQuery, null, currentPage, pageSize);
                    // Execute the request and return only the selected fields
                    queryResult = service.ServiceProxy.Query(contactEntityType, searchQuery, fieldList.ToArray(), currentPage, pageSize);


                if (queryResult.Entities.Length > 0)
                    //Extract the total number of pages and records
                    Console.WriteLine(String.Format("Total number of pages: {0}", queryResult.TotalPages));
                    Console.WriteLine(String.Format("Total number of records: {0}", queryResult.TotalRecords));


                    // Extract each Dynamic Entity in the result
                    foreach (DynamicEntity dynamicEntity in queryResult.Entities)
                        // Extract the field name and value of each field in the collection
                        foreach (KeyValuePair<string, string> field in dynamicEntity.FieldValueCollection)
                            Console.WriteLine(String.Format("Field Name: {0}: {1}", field.Key, field.Value));


            // Customize your own error handling code
            catch (System.ServiceModel.FaultException ex)
                // Catch Service Model Fault Exceptions
                Console.WriteLine(String.Format("Reason: {0}", ex.Reason));
                Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType()));
                Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name));
            catch (Exception ex)
                // Catch System Exceptions
                Console.WriteLine(String.Format("Exception Message: {0}", ex.Message));

            // Wait for user input before stepping out.
            Console.WriteLine("Press any key to continue.");


When the program is run, a console window will pop up showing the results of the query as seen below.



This is of course a very simple example, but it shows how easy it is to get going with the Eloqua API.


A great intro to using the WS API with Java can be found Using Eloqua WS API with Java - Part 1.