Step 2: Wait for Import

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.
  2. CloudSponge returns the current Event result object.

Please Note The value on this endpoint will only update every second at most. Please limit your queries here to once per second.

Definition

GET https://api.cloudsponge.com/events/[import_id][.format]

Request Arguments

NameRequired?Description
domain_keyYesYour domain key.
domain_passwordYesYour domain password.
import_idYesimport_id value returned from the call to begin_import in Step 1.
echoNoAny customer defined string data to be returned in the response.

Example Request

curl --user 33664218758c5244136965160db455db012b1411:Tpa01z+vVPE7MxXi \
     --url "https://api.cloudsponge.com/events/1126.json"

Response Variables

NameDescription
eventsAn array of events objects for the specified import_id. See the table below for details.
import_idThe identifier for this import, used in subsequent calls to fetch events and contacts.
user_idThe customer defined string that was passed in as an argument to the call to /begin_import.
echoThe customer defined string that was passed in as an argument.

Example Response (JSON)

{
  "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  
}  

Example Response (XML)

<?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>

API 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.

event-typestatusvalue
INITIALIZINGINPROGRESSn/a
INITIALIZINGCOMPLETEDn/a
INITIALIZINGERRORAn error code from the table below.
GATHERINGINPROGRESSNumber of contacts gathered so far.
GATHERINGERRORAn error code from the table below.
GATHERINGCOMPLETEDn/a
COMPLETEERRORAn error code from the table below.
COMPLETECOMPLETEDn/a
API Error Codes

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 CodeError CategoryExplanation
1FailedCould not authenticate the domain key/password.
2FailedInvalid parameters supplied to begin_import.
256FailedUnexpected error occurred during webmail import.
257FailedWebmail import failed.
258FailedTimeout occurred during webmail import.
259FailedUsername and password are required.
260FailedService is required.
261FailedUnrecognized service selected.
262FailedThe same import failed to authenticate recently.
263FailedUsername and password do not match.
264FailedThe address book is temporarily unavailable, please try again later.
265FailedThis account has been canceled.
266FailedThe account has been blocked. Reset the password to reenable it.
267FailedTerms of Service have changed for your account. Sign in to your account to enable it.
512FailedUnknown error occurred during a user consent import.
513FailedUser consent import failed because the domain is not permitted to use the service.
514AbandonedUser consent import failed because the user did not provide consent to access their contacts.
516AbandonedConsent was not granted within the allotted time.
517AbandonedThe user abandoned the import before consent was granted.
518FailedUnable to communicate successfully with the address book provider.
528FailedUnable to retrieve contacts. New Yahoo! users must wait 14 days to use this feature.
544FailedGoogle Contacts is not configured properly in CloudSponge. Sign into your account and complete the branding set up.
545FailedGoogle Contacts is not configured properly. If you are the developer, enable Google’s People API in your Google APIs Console.
768FailedUnexpected error occurred during applet import.
769AbandonedApplet failed to import because user did not trust the applet.
770FailedApplet failed to import because it could not find an appropriate address book to import.
771FailedApplet failed to submit contacts to CloudSponge.
772AbandonedThe Desktop Applet was not trusted within the allotted time.
773AbandonedThe user abandoned the import before the Desktop Applet was trusted.
774AbandonedYou must allow access to Microsoft Outlook to import your contacts.
775FailedThe import was denied access to Contacts by the OS.
1025FailedA file was uploaded that is not of type text/csv.
1026FailedA CSV file was uploaded but could not be parsed.
1027FailedFile uploads are not supported on the device.

Try CloudSponge for free in your
testing environment

Get Started

Have a questions or prefer a guided tour?
Schedule a consultation with our Founder.