Documentation/Contacts API/Step 2: Wait for Import

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

Name Required? Description
domain_key Yes Your domain key.
domain_password Yes Your domain password.
import_id Yes import_id value returned from the call to begin_import in Step 1.
echo No Any 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

Name Description
events An array of events objects for the specified import_id. See the table below for details.
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 an argument to the call to /begin_import.
echo The 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-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 ERROR An error code from the table below.
GATHERING COMPLETED n/a
COMPLETE ERROR An error code from the table below.
COMPLETE COMPLETED n/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 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.
544 Failed Google Contacts is not configured properly in CloudSponge. Sign into your account and complete the branding set up.
545 Failed Google Contacts is not configured properly. If you are the developer, enable Google’s People API in your Google APIs Console.
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.
1027 Failed File 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.