Documentation/Contacts API/Step 1: Get Permissions/User Consent

User Consent

This import method will send your user to a new window to grant permission to access their contacts. You will call our API to get the URL that you need to load in this window.

  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/user_consent endpoint, including the contact source requested.
  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.
  4. Your application redirects the popup to the consent page url.

Now your application’s main page should go to Step 2 while the user gives CloudSponge permission to access their contacts and we download their address book for you.

Definition

POST https://api.cloudsponge.com/begin_import/user_consent[.format]

Request Arguments

Name Required? Description
domain_key Yes Your domain key.
domain_password Yes Your domain password.
service Yes Service code (see table above)
include No By specifying mailing_address here, mailing addresses will be returned in addition to the other contact information.
user_id No Any unique identifier you use to identify a user. This value will be returned on calls to the /events and /contacts endpoints.
echo No Any customer defined string data to be returned in the response.
redirect_url No The URL where the browser will be redirected after the consent flow has completed. This parameter is useful when you are redirecting the browser to the consent URL. It is how you tell our application where to redirect the browser after the user has completed the consent flow. Typically, this is be the URL of the page where the user will see their imported address book.
NB If you are opening the consent URL in a popup window with window.open, do not specify a value for the parameter.

Example Request

curl --user 33664218758c5244136965160db455db012b1411:Tpa01z+vVPE7MxXi \
     --request POST \
     --data "service=yahoo" \
     --url "https://api.cloudsponge.com/begin_import/user_consent.json"

Response Variables

Name Description
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 an argument.
echo The customer defined string that was passed in as an argument.

Example Response (JSON)

{  
  "status": "success",
  "url": "https://api.cloudsponge.com/n/FULNW3D",
  "import_id": 1126
}

Example Response (XML)

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <status>success</status>
  <url>https://api.cloudsponge.com/n/FULNW3D</url>
  <import-id>1126</import-id>
</result>