CONTACT API

Follow

Summary:

The Contact API provides access to the raw data required to generated the individual Contact Views within the CANDDi dashboard.  

Please see attached PDF document for technical definition of each field in the API

Example:

 




There are two methods described (currently) in this document

  • GET one Contact
  • GET more activity for one Contact
  • GET (search) for Contacts by email address



Get one contact
GET /contact/[ContactId]

Purpose: This returns ONE Contact using the "known" ContactId
URL: https://[slug].canddi.com/contact/[ContactId]
Verb: GET
Parameters: Slug this is your account slug (same as when you log into the CANDDi dashboard)
ContactId this is the CANDDi unique Contact identifier (this is the end point of the URL when you look at the ContactId in the dashboard)


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" }

Failure Response

If the API key is invalid - will return HTTP status: 401 (Authentication required)

If the User doesn't have access to this account then will return HTTP status: 401

If the ContactId doesn't exist in the database then this will return HTTP staus: 404

 

Get more activity for one contact
GET /contact/[ContactId]/activity

Purpose: This returns more data for one Contact
URL: https://[slug].canddi.com/contact/[ContactId]/activity?limit=[Int_Limit]&skip=[Int_Skip]

Verb: GET

Parameters: Slug this is your account slug (same as when you log into the CANDDi dashboard)

ContactId this is the CANDDi unique Contact identifier (this is the end point of the URL when you look at the ContactId in the dashboard)

Int_Limit (integer) this is the number of Activity records to return in this call.  Maximum value = 100. Default Value = 20

Int_Skip (integer) this is the number of Activity records to "skip" before starting to return data.  Default Value = 0


Example:




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 ]

Failure Response

If the API key is invalid - will return HTTP status: 401 (Authentication required)

If the User doesn't have access to this account then will return HTTP status: 401

If the ContactId doesn't exist in the database then this will return HTTP staus: 404

Search for contact(s)
GET /contact/Email/search?id=[EmailAddress]

Purpose: This returns an array of ContactId's which have this email address
URL: https://[slug].canddi.com/contact/Email/search?id=[EmailAddress]

Verb:
NOTE : This MUST be a capital E for Email

GET
Parameters: Slug this is your account slug (same as when you log into the CANDDi dashboard)
EmailAddress this is the email address to search for

It is probable that other searches will be implemented at a later date

NOTE: It is possible that CANDDi will have multiple Contacts with the same email address. This can happen because:

  • CANDDi has seen the same email address on multiple different computers (but isn't confident enough that they represent the same "real person" to Merge the records


Success Response

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

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

Failure Response

If the API key is invalid - will return HTTP status: 401 (Authentication required)

If the User doesn't have access to this account then will return HTTP status: 401

If the EmailAddress doesn't exist in the database then this will return HTTP staus: 404

Have more questions? Submit a request

Comments