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.

Your application calls the /events URL to get the current Import Events, specifying the import_id returned in the initial request.
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.