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.
This step is a little different depending on which source your user wants to import from.
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.
|Outlook||1.7u45 <= Java version < 1.7u51||CSV import|
|Outlook||Java version < 1.7u45||Applet import|
|Outlook||Java version > 1.7u51||Applet import|
|Mac Contacts||Java version >= 1.7u45||VCard import|
|Mac Contacts||Chrome w/ Java version > 1.6||VCard import|
|Mac Contacts||Java version < 1.7u45||Applet import|
import_idinto the following HTML snippet and rendering it onto the page.
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.
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.
|INITIALIZING||ERROR||An error code from the table below.|
|GATHERING||INPROGRESS||Number of contacts gathered so far.|
|GATHERING||ERROR||An error code from the table below.|
|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.|
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.