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 import from.

Which import method should I use?

The table below summarizes which import method to use with each source. Desktop imports use a different import method depending on the configuration of the end user's system.

Source System Method Endpoint
Gmail-OAuth2.0 import/begin_import/user_consent
Outlook.com-OAuth2.0 import/begin_import/user_consent
Yahoo-OAuth import/begin_import/user_consent
AOL-OAuth2.0 import/begin_import/user_consent
Plaxo-Username/Password import/begin_import/import
Outlook1.7u45 <= Java version < 1.7u51CSV import/begin_import/user_consent
OutlookJava version < 1.7u45Applet import/begin_import/desktop_applet
OutlookJava version > 1.7u51Applet import/begin_import/desktop_applet
Mac ContactsJava version >= 1.7u45VCard import/begin_import/user_consent
Mac ContactsChrome w/ Java version > 1.6VCard import/begin_import/user_consent
Mac ContactsJava version < 1.7u45Applet import/begin_import/desktop_applet

User Consent - Gmail, Yahoo, Outlook.com, AOL, Windows Outlook and Mac Contacts

  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 - 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. (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=PLAXO /
    &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 - Windows Outlook, Mac Contacts

  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.

event-type status value
INITIALIZING INPROGRESS n/a
INITIALIZING COMPLETED n/a
INITIALIZING ERROR An error code from the table below.
GATHERING INPROGRESS Number of contacts gathered so far.
GATHERING COMPLETED n/a
GATHERING ERROR An error code from the table below.
COMPLETE COMPLETED n/a
COMPLETE ERROR An error code from the table below.

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

Error Code Error Category Explanation
1 Failed Could not authenticate the domain key/password.
2 Failed Invalid parameters supplied to begin_import.
256 Failed Unexpected error occurred during webmail import.
257 Failed Webmail import failed.
258 Failed Timeout occurred during webmail import.
259 Failed Username and password are required.
260 Failed Service is required.
261 Failed Unrecognized service selected.
262 Failed The same import failed to authenticate recently.
263 Failed Username and password do not match.
264 Failed The address book is temporarily unavailable, please try again later.
265 Failed This account has been canceled.
266 Failed The account has been blocked. Reset the password to reenable it.
267 Failed Terms of Service have changed for your account. Sign in to your account to enable it.
512 Failed Unknown error occurred during a user consent import.
513 Failed User consent import failed because the domain is not permitted to use the service.
514 Abandoned User consent import failed because the user did not provide consent to access their contacts.
516 Abandoned Consent was not granted within the allotted time.
517 Abandoned The user abandoned the import before consent was granted.
518 Failed Unable to communicate successfully with the address book provider.
528 Failed Unable to retrieve contacts. New Yahoo! users must wait 14 days to use this feature.
768 Failed Unexpected error occurred during applet import.
769 Abandoned Applet failed to import because user did not trust the applet.
770 Failed Applet failed to import because it could not find an appropriate address book to import.
771 Failed Applet failed to submit contacts to CloudSponge.
772 Abandoned The Desktop Applet was not trusted within the allotted time.
773 Abandoned The user abandoned the import before the Desktop Applet was trusted.
774 Abandoned You must allow access to Microsoft Outlook to import your contacts.
775 Failed The import was denied access to Contacts by the OS.
1025 Failed A file was uploaded that is not of type text/csv.
1026 Failed A CSV file was uploaded but could not be parsed.

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>