Back to Support

Understanding CANDDi and Contact API

Published 02 Nov 2020 by Ellice Eadie, CANDDi
Read this in about 3 minutes

Disclaimer: there’s a LOT of code to take in here. Continue at your own peril.

If you need a hand, just reach out to our fellow techies and they’ll sort you out.

Using CANDDi’s Contact API

Google Contact API

With CANDDi’s contact API you can update and view a user’s contacts. To get a contact, see below:

Example:

curl -i -H'CANDDi_API:**[API_KEY]**' -H'Accept:application/json' https://**[slug]**.canddi.com/contact/[ContactId]

Success Response

{ "CountSessions" : 1, "DatesActive" : [ 1337094881 ], "Addresses" : { "8c3bf02da310c5be496824158f22845a" : { "City" : "Manchester", "Count" : 0, "Line1" : "85 Kenworthy Lane", "Line2" : "", "Postcode" : "M22 4FA", "UserDefault" : true } }, "AssignedTo" : { "EmailAddress" : "fred@canddi.com", "Accepted" : false, "TimeAssigned" : null }, "InStreams" : [ "df13414e6b2b6ac6d2fd5942f8f85d54", "c94a781c86e16d06040ae19f22710292", "6db7e0ff8ee12687b3fec23c303c7a55", "810ac9f4b18f36374260d03a75affb50" ], "LastSession" : { "SessionGUID" : "1be21e65e2ba0411281d882dd5dba0f9", "SessionType" : { "Id" : 1, "Type" : "Website" }, "DateCreated" : "2012-05-15 15:14:41", "TimeCreated" : 1337094881, "TotalDuration" : 722, "TotalDurationPretty" : "12 mins", "TotalGoals" : 19 }, "TimeCreated" : ISODate("2012-05-15T15:14:41Z"), "TotalDuration" : 722, "Widgets" : { "browser" : { "Widgets" : { "fdc83df8ef7c4b5238f839dcae57a919" : { "Data" : { "UserAgent" : "Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)", "BrowserName" : "Internet Explorer", "BrowserVersion" : "9.0", "BrowserClass" : "browser_explorer" }, "TimeCreated" : 1337094882 } } }, "iplookup" : { "Widgets" : { "03b876c67e8158bcf99b3dab05b7275e" : { "Data" : { "IP" : "67.185.84.103", "Organisation" : "Comcast Cable", "ContinentCode" : "NA", "CountryCode" : "US", "CountryName" : "United States", "Region" : "WA", "City" : "Spokane", "PostalCode" : "", "Latitude" : "47.677898406982", "Longitude" : "-117.37930297852" }, "TimeCreated" : 1337094882 } } }, "referrer" : { "Widgets" : { "eb87ee8b231a624d94272d01fb9f78fe" : { "Data" : { "SessionGoalId" : "eb87ee8b231a624d94272d01fb9f78fe", "TrackerReferrerId" : "7ed5ffaec8f6422e9c82632c994b9ebc", "RawReferrer" : "CANDDi_DIRECT_HOSTNAME", "ReferrerType" : "Direct", "ReferrerTitle" : "(Unknown)", "ReferrerClass" : null, "ReferrerDate" : "2012-05-15 16:14:41", "Fields" : [ ] }, "TimeCreated" : 1337094882 } } } }, "Names" : { "965c58daed7cd75cbf6b3552bda4fa43" : { "Count" : 1, "FirstName" : "Tom", "LastName" : "", "MiddleName" : "", "Prefix" : "", "Suffix" : "" } }, "Emails" : { "bdb63e5b551b8133de99a90fbe5dc386" : { "Count" : 1, "Email" : "tom@canddi.com" } }, "Gender" : { "Male" : 1 }, "Companies" : { "bd4d2ee3933c0147bafb59e2c9a0b14e" : { "Company" : "PORTLAND STREET", "Count" : 2 } }, "_Location" : [ { "lat" : 47.677898406982, "lon" : -117.37930297852, "CId" : "3e69a694c01d717ef126050ac92a54a1", "TimeCreated" : 1337094882 } ], "_id" : "542932916f6ab9f1c13fea46737c9d43" }

To get more activity for one contact, see below:

curl -i -H'CANDDi_API:**[API_KEY]**' -H'Accept:application/json' https://**[slug]**.canddi.com/contact/[ContactId]/activity?limit=10

Success Response

{ "Activities": [ { "_id": "b9bc76bc9968212beb2c431ba2765cbc", "SessionGUID": "734b6f44e00ce65bdc787e8a660291d9", "GoalTitle": "Viewed Section: Qualify and up-sell each enquiry", "GoalType": "event", "SessionGoalTypeId": 1, "TimeCreated": 1386586466, "Duration": 0, "PageTypeId": 5, "rawURL": "Viewed Section: Qualify and up-sell each enquiry", "rawPostArray": [ ], "Referrer": [ ], "TrackerGoalId": "e9dff079e2aabb457ad2a341e53aef48", "MaxScroll": 0 }, { "_id": "80aadef4601b389004aa2ad1aff59b8c", "SessionGUID": "734b6f44e00ce65bdc787e8a660291d9", "GoalTitle": "Viewed Section: More leads from your website visitors", "GoalType": "event", "SessionGoalTypeId": 1, "TimeCreated": 1386586379, "Duration": 0, "PageTypeId": 5, "rawURL": "Viewed Section: More leads from your website visitors", "rawPostArray": [ ], "Referrer": [ ], "TrackerGoalId": "af1b380c90359afac501209a4af1b3bc", "MaxScroll": 0 } ], "TotalRows": 79 ]

You might get a failure response if:

  • the API key is invalid - will return HTTP status: 401 (Authentication required)
  • the User doesn’t have access to this account then will return HTTP status: 401
  • the Contact doesn’t exist in the database then this will return HTTP status: 404

To search for contact(s), use the below: GET /contact/Email/search?id=[EmailAddress]. It is probable that other searches will be implemented at a later date.

A success response will look like:

[ { ContactId: "", Score: 1 } ... (there can be multiple here) ]

This returns an array of contact scores. The highest Score is the record which CANDDi would recommend displaying.

You might get a failure response if:

  • the API key is invalid - will return HTTP status: 401 (Authentication required)
  • the User doesn’t have access to this account then will return HTTP status: 401
  • the Contact doesn’t exist in the database then this will return HTTP status: 404