Documentation/Contacts API/Step 3: Download

Step 3: Download

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.

  1. Your application calls the /contacts endpoint to retrieve the contacts, specifying the import_id from the initial request.
  2. CloudSponge returns the Contacts result object in the format requested.

Definition

GET https://api.cloudsponge.com/contacts/[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.
start No For pagination: the 0-based index of the start of the contacts returned. Defaults to 0.
count No For pagination: the maximum number of contacts to return in the contacts array. This value is ignored if start is not included. Defaults to 0 (all contacts).
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/contacts/1126.json?start=0&count=10"

Response Variables

Name Description
contacts An array of contact objects for the specified import_id.
contacts_owner Contact information for the owner of the address book.
import_id The identifier for this import, used in subsequent calls to fetch events and contacts.
start For pagination: The 0-based, starting offset of the array of contacts that are returned.
count For pagination: The number of contacts included in the array of contacts.
total The total number of contacts imported from the address book.
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)

{
  "echo":null,
  "user_id":"myUserId_0003",
  "import_id":1126,
  "start": 0,
  "count": 2,
  "total": 2,
  "contacts_owner":
    {
      "first_name":"Joe",
      "last_name":"Smith",
      "email":[
        {
          "address":"joe@example.com"
        }
      ]
    },
  "contacts": [
    {
      "first_name":"John",
      "last_name":"Doe",
      "phone": [
        {
          "number":"555-1234",
          "type":"Home"
        },
        {
          "number":"555-2468",
          "type":"Work"
        }
      ],
      "email": [
        {
          "address":"johndoe@nowhere.com",
          "type":"Email 1"
        },
        {
          "address":"second@email.com",
          "type":"Email 2"
        }
      ]
    },
    {
      "first_name":"Jane",
      "last_name":"Smith",
      "phone":[
        {
          "number":"555.5678",
          "type":"Home"
        }
      ],
      "email":[
        {
          "address":"janesmith@nowhere.com",
          "type":"Email 1"
        }
      ],
      "addresses": [
        {
          "street":"3450 Sacramento St., #510",
          "city":"San Francisco",
          "region":"CA",
          "country":"US",
          "postal_code":"94118",
          "formatted":"3450 Sacramento St., #510 San Francisco, CA 94118"
        }
      ]
    }
  ]
}

Example Response (XML)

<?xml version="1.0" encoding="UTF-8"?>
<contactsResponse>
  <echo nil="true"></echo>
  <user-id>myUserId_0003</user-id>
  <import-id>1126</import-id>
  <start>0</start>
  <count>2</count>
  <total>2</total>
  <contacts-owner>
    <first-name>Joe</first-name>
    <last-name>Smith</last-name>
    <email type="array">
      <email>
        <address>joe@example.com</address>
      </email>
    </email>
  </contacts-owner>
  <contacts type="array">
    <contact>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <phone type="array">
        <phone>
          <number>555-1234</number>
          <type>Home</type>
        </phone>
        <phone>
          <number>555-2468</number>
          <type>Work</type>
        </phone>
      </phone>
      <email type="array">
        <email>
          <address>johndoe@nowhere.com</address>
          <type>Email 1</type>
        </email>
        <email>
          <address>second@email.com</address>
          <type>Email 2</type>
        </email>
      </email>
    </contact>
    <contact>
      <first-name>Jane</first-name>
      <last-name>Smith</last-name>
      <phone type="array">
        <phone>
          <number>555.5678</number>
          <type>Home</type>
        </phone>
      </phone>
      <email type="array">
        <email>
          <address>janesmith@nowhere.com</address>
          <type>Email 1</type>
        </email>
      </email>
      <address type="array">
        <address>
          <street>3450 Sacramento St., #510</street>
          <city>San Francisco</city>
          <region>CA</region>
          <country>US</country>
          <postal-code>94118</postal-code>
          <formatted>3450 Sacramento St., #510 San Francisco, CA 94118</formatted>
        </address>
      </address>
    </contact>
  </contacts>
</contactsResponse>