Cloudsponge

The Do-It-Yourself Approach

Despite there being three different user authentication methods, importing contacts with the API follows a similar 3-stage asynchronous process.

Step 1: Get The User's Permission - Your application initiates an address book import by calling the “Begin Import” URL, specifying the user authentication method, the address book source, plus any other additional information required. The API returns a result object containing a unique identifier for subsequent calls to the API, and in some cases data needs to be displayed in the user’s browser.

Step 2: Wait For The Import To Finish - Your application polls the “Events” URL and receives a result object indicating the current Import Events. These events notify you of the current progress of the import, if any errors have occurred, or when the import is complete. You can optionally display these Import Events to the user’s browser.

Step 3: Download the Address Book - Once you have received a successful “complete” Import Event, you can retrieve the contacts payload from the API directly or from a database configured for your account.

Step 1: Get The User's Permission

This step is a little different depending on which source your user wants to use.

User Consent - Gmail, Yahoo, Hotmail/MSN/Windows Live

1. Your application launches a new popup window to accommodate for the user consent URL.
2. Once the popup launches, your application calls the “Begin Import” URL, including the contact source requested.
   URL: https://api.cloudsponge.com/begin_import/user_consent<format>
   Method: POST
   Parameters:
   

   • service: Contact source name. (YAHOO, WINDOWSLIVE or GMAIL)
   • domain_key: Your domain key.
   • domain_password: Your domain password.
   • include (optional): By specifying 'mailing_address' here, mailing addresses will be returned in addition to the other contact information.
   • user_id (optional): Any unique identifier you use to identify a user.
   • echo (optional): Any customer defined string data to be returned in the response.
   • format (optional): either '.json' (default) or '.xml'

   
   Example:
   https://api.cloudsponge.com/begin_import/user_consent.json /
   ?service=YAHOO /
   &user_id=myUserId_0003 /
   &echo=echo123 /
   &domain_key=33664218758c5244136965160db455db012b1411 /
   &domain_password=Tpa01z+vVPE7MxXi
3. CloudSponge returns a result object, including the import_id to use to fetch the contacts later and a URL for the user consent page, which needs to be displayed to the user in the popup window.
   Response:
   

   • status: success or failure
   • url: User Consent URL where the user’s browser should be directed.
   • import_id: The identifier for this import, used in subsequent calls to fetch events and contacts.
   • user_id: The customer defined string that was passed in as a parameter.
   • echo: The customer defined string that was passed in as a parameter.

   
   JSON Example:
   {
     "status":"success",
     "url":"https:\/\/api.login.yahoo.com\/oauth\/v2\/request_auth?oauth_token=d",
     "import_id":1126,
     "user_id":"myUserId_0003",
     "echo":"echo123"
   }
   
   XML Example:
   <?xml version="1.0" encoding="UTF-8"?>
   <result>
     <status>success</status>
     <url>https://api.login.yahoo.com/oauth/v2/request_auth?oauth_token=d</url>
     <import-id>1126</import-id>
     <user-id>myUserId_0003</user-id>
     <echo>echo123</echo>
   </result>
   
4. Your application redirects the popup to the consent page URL.
5. Your application's main page goes to Step 2 while the user gives CloudSponge permission to access their address book and we download it for you.

Regular Import - AOL, Plaxo

1. Your application collects the user's username and password combination for the contact source requested.
2. Your application calls the “Begin Import” URL, including the username/password plus the contact source requested.
   URL: https://api.cloudsponge.com/begin_import/import<format>
   Method: POST
   Parameters:
   

   • username: Username for the contact source.
   • password: Password for the contact source.
   • service: Contact source name. (AOL or PLAXO)
   • domain_key: Your domain key.
   • domain_password: Your domain password.
   • include (optional): By specifying 'mailing_address' here, mailing addresses will be returned in addition to the other contact information.
   • user_id (optional): Any unique identifier you use to identify a user.
   • echo (optional): Any customer defined string data to be returned in the response.
   • format (optional): either '.json' (default) or '.xml'

   
   Example:
   https://api.cloudsponge.com/begin_import/import.xml /
   ?username=foo /
   &password=bar /
   &service=AOL /
   &user_id=myUserId_0003 /
   &echo=echo123 /
   &domain_key=33664218758c5244136965160db455db012b1411 /
   &domain_password=Tpa01z+vVPE7MxXi
3. CloudSponge returns a result object indicating the request has been received and specifying an identifier to use for fetching events and contacts.
   Response:
   

   • status: success or failure
   • import_id: The identifier for this import, used in subsequent calls to fetch events and contacts.
   • user_id: The customer defined string that was passed in as a parameter.
   • echo: The customer defined string that was passed in as a parameter.

   
   JSON Example:
   {
     "status":"success",
     "import_id":1131,
     "user_id":"myUserId_0003",
     "echo":"echo123"
   }
   
   XML Example:
   <?xml version="1.0" encoding="UTF-8"?>
   <result>
     <status>success</status>
     <import-id>1131</import-id>
     <user-id>myUserId_0003</user-id>
     <echo>echo123</echo>
   </result>
   
4. (Optional) Your application displays a status update to the user.
5. Your application goes to Step 2 while CloudSponge downloads the address book for you.

Desktop Applet - Outlook, OS X Address Book

1. Your application calls the “Begin Import” URL, including the contact source requested.
   URL: https://api.cloudsponge.com/begin_import/desktop_applet<format>
   Method: POST
   Parameters:
   

   • service: Contact source name. (OUTLOOK or ADDRESSBOOK)
   • domain_key: Your domain key.
   • domain_password: Your domain password.
   • include (optional): By specifying 'mailing_address' here, mailing addresses will be returned in addition to the other contact information.
   • user_id (optional): Any unique identifier you use to identify a user.
   • echo (optional): Any customer defined string data to be returned in the response.
   • format (optional): either '.json' (default) or '.xml'

   
   Example:
   https://api.cloudsponge.com/begin_import/desktop_applet.json /
   ?service=ADDRESSBOOK /
   &user_id=myUserId_0003 /
   &echo=echo123 /
   &domain_key=33664218758c5244136965160db455db012b1411 /
   &domain_password=Tpa01z+vVPE7MxXi
2. CloudSponge returns a result object, including a URL for the desktop applet, which needs to be downloaded by the user and an import_id to be used to identify the import to the applet and to fetch the events and contacts.
   Response:
   

   • status: success or failure
   • url: Java applet URL to be used to process the import.
   • import_id: The identifier for this import, used in subsequent calls to fetch events and contacts.
   • user_id: The customer defined string that was passed in as a parameter.
   • echo: The customer defined string that was passed in as a parameter.

   
   JSON Example:
   {
     "status":"success",
     "url":"https:\/\/api.cloudsponge.com\/objects\/ContactsApplet_signed.jar",
     "import_id":1132,
     "user_id":"myUserId_0003",
     "echo":"echo123"
   }
   
   XML Example:
   <?xml version="1.0" encoding="UTF-8"?>
   <result>
     <status>success</status>
     <url>https://api.cloudsponge.com/objects/ContactsApplet_signed.jar</url>
     <import-id>1132</import-id>
     <user-id>myUserId_0003</user-id>
     <echo>echo123</echo>
   </result>
   
3. Your application directs the user's browser to download the applet from the URL provided. This is accomplished by inserting the url and import_id into the following HTML snippet and rendering it onto the page.
   <!--[if !IE]> Firefox and others will use outer object -->
   <object classid="java:ContactsApplet"
     type="application/x-java-applet"
     archive="url"
     height="1"
     width="1">
     <!-- Konqueror browser needs the following param -->
     <param name="archive" value="url" />
     <param name="cookieValue" value="document.cookie"/>
     <param name="importId" value="import_id"/>
     <param name="MAYSCRIPT" value="true">
   <!--<![endif]-->
   
     <!-- MSIE (Microsoft Internet Explorer) will use inner object -->
     <object classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
       codebase="http://java.sun.com/update/1.6.0/jinstall-6u30-windows-i586.cab"
       height="0"
       width="0" >
       <param name="code" value="ContactsApplet" />
       <param name="archive" value="url" />
       <param name="cookieValue" value="document.cookie"/>
       <param name="importId" value="import_id"/>
      <param name="MAYSCRIPT" value="true">
   
       <!-- Chrome falls through to this innermost applet -->
       <applet archive="url" code="ContactsApplet" height="1" width="1" MAYSCRIPT>
         <param name="cookieValue" value="document.cookie" />
         <param name="importId" value="import_id"/>
         <param name="MAYSCRIPT" value="true">
         <strong>
           This browser does not have a Java Plug-in.<br />
           <a href="http://java.sun.com/products/plugin/downloads/index.html">
             Get the latest Java Plug-in here.
           </a>
         </strong>
       </applet>
     </object>
   
   <!--[if !IE]> close outer object -->
   </object>
   <!--<![endif]-->
   
4. Your application goes to Step 2 while the user gives CloudSponge permission to access their address book and we download it for you.

Step 2: Wait For The Import To Finish

After a contact import is initiated, your application must monitor the events as they are generated from CloudSponge. Use the import_id value that was returned from the call to begin_import to identify the import request to CloudSponge when fetching events.

1. Your application calls the “Events” URL to get the current Import Events, specifying the import_id returned in the initial request.
   URL: https://api.cloudsponge.com/events<format>/<import_id>
   Method: GET
   Parameters:
   

   • import_id: import_id value returned from the call to begin_import in Step 1.
   • domain_key: Your domain key.
   • domain_password: Your domain password.
   • echo (optional): Any customer defined string data to be returned in the response.
   • format (optional): either '.json' (default) or '.xml'

   
   Example:
   https://api.cloudsponge.com/events.json/1126 /
   ?echo=echo123 /
   &domain_key=33664218758c5244136965160db455db012b1411 /
   &domain_password=Tpa01z+vVPE7MxXi
2. CloudSponge returns the current Event result object.
   Response:
   

   • events: An array of events objects for the specified import_id. See the table below for details.
   • import_id: The identifier for this import.
   • user_id: The customer defined string that was passed in as a parameter.
   • echo: The customer defined string that was passed in as a parameter.

   
   JSON Example:
   {
     "events":
     [
       {"value":0,"status":"COMPLETED","event_type":"INITIALIZING"},
       {"value":2,"status":"COMPLETED","event_type":"GATHERING"},
       {"value":0,"status":"COMPLETED","event_type":"COMPLETE"}
     ],
     "echo":null,
     "user_id":"myUserId_0003",
     "import_id":1126
   }
   
   XML Example:
   <?xml version="1.0" encoding="UTF-8"?>
   <eventsResponse>
     <events type="array">
       <event>
         <event-type>INITIALIZING</event-type>
         <status>COMPLETED</status>
         <value type="integer">0</value>
       </event>
       <event>
         <event-type>GATHERING</event-type>
         <status>COMPLETED</status>
         <value type="integer">2</value>
       </event>
       <event>
         <event-type>COMPLETE</event-type>
         <status>COMPLETED</status>
         <value type="integer">0</value>
       </event>
     </events>
     <echo nil="true"></echo>
     <user-id>myUserId_0003</user-id>
     <import-id>1126</import-id>
   </eventsResponse>
   

The following table defines the events array elements. Please note that the XML response will have some extra fields included, we do not recommend that you write your code to depend on these fields since we are in the process of deprecating them.

The following table defines all of the error codes that you can expect to receive along with status=ERROR elements in the events array.

Step 3: Download The Address Book

When the COMPLETE event is received with the COMPLETED status in Step 2, your application should retrieve the contacts immediately. After a few minutes, they will be deleted from CloudSponge.

1. Your application calls the “Contacts” URL to retrieve the contacts, specifying the import_id from the initial request.
   URL: https://api.cloudsponge.com/contacts<format>/<import_id>
   Method: GET
   Parameters:
   

   • import_id: import_id value returned from the call to begin_import in Step 1.
   • domain_key: Your domain key.
   • domain_password: Your domain password.
   • echo (optional): Any customer defined string data to be returned in the response.
   • format (optional): either '.json' (default) or '.xml'

   
   Example:
   https://api.cloudsponge.com/contacts.json/1126 /
   ?echo=echo123 /
   &domain_key=33664218758c5244136965160db455db012b1411 /
   &domain_password=Tpa01z+vVPE7MxXi
2. CloudSponge returns the Contacts result object in the format requested.
   Response:
   

   • contacts: An array of contact objects for the specified import_id.
   • contacts_owner: Contact information for the owner of the address book.
   • import_id: The identifier for this import.
   • user_id: The customer defined string that was passed in as a parameter.
   • echo: The customer defined string that was passed in as a parameter.

   
   JSON Example:
   {
     "echo":null,
     "user_id":"myUserId_0003",
     "import_id":1126,
     "contacts_owner":
     {
       "first_name":"Joe",
       "last_name":"Smith",
       "email":[{"address":"joe@example.com"}]
     },
     "contacts":
     [
       {
         "first_name":"John",
         "last_name":"Doe",
         "phone":
         [
           {"number":"555-1234","type":"Home"},
           {"number":"555-2468","type":"Work"},
         ],
         "email":
         [
           {"address":"johndoe@nowhere.com","type":"Email 1"},
           {"address":"second@email.com","type":"Email 2"}
         ]
       },
       {
         "first_name":"Jane",
         "last_name":"Smith",
         "phone":[{"number":"555.5678","type":"Home"}],
         "email":[{"address":"janesmith@nowhere.com","type":"Email 1"}],
         "addresses":
         [
           {
             "street":"3450 Sacramento St., #510",
             "city":"San Francisco",
             "region":"CA",
             "country":"US",
             "postal_code":"94118",
             "formatted":"3450 Sacramento St., #510 San Francisco, CA 94118"
           }
         ]
       }
     ]
   }
   
   XML Example:
   <?xml version="1.0" encoding="UTF-8"?>
   <contactsResponse>
     <echo nil="true"></echo>
     <user-id>myUserId_0003</user-id>
     <import-id>1126</import-id>
     <contacts-owner>
       <first-name>Joe</first-name>
       <last-name>Smith</last-name>
       <email type="array">
         <email>
           <address>joe@example.com</address>
         </email>
       </email>
     </contacts-owner>
     <contacts type="array">
       <contact>
         <first-name>John</first-name>
         <last-name>Doe</last-name>
         <phone type="array">
           <phone>
             <number>555-1234</number>
             <type>Home</type>
           </phone>
           <phone>
             <number>555-2468</number>
             <type>Work</type>
           </phone>
         </phone>
         <email type="array">
           <email>
             <address>johndoe@nowhere.com</address>
             <type>Email 1</type>
           </email>
           <email>
             <address>second@email.com</address>
             <type>Email 2</type>
           </email>
         </email>
       </contact>
       <contact>
         <first-name>Jane</first-name>
         <last-name>Smith</last-name>
         <phone type="array">
           <phone>
             <number>555.5678</number>
             <type>Home</type>
           </phone>
         </phone>
         <email type="array">
           <email>
             <address>janesmith@nowhere.com</address>
             <type>Email 1</type>
           </email>
         </email>
         <address type="array">
           <address>
             <street>3450 Sacramento St., #510</street>
             <city>San Francisco</city>
             <region>CA</region>
             <country>US</country>
             <postal-code>94118</postal-code>
             <formatted>3450 Sacramento St., #510 San Francisco, CA 94118</formatted>
           </address>
         </address>
       </contact>
     </contacts>
   </contactsResponse>