BIGContacts API

REST API docs

Request format:

https://app.bigcontacts.com/api/{resource}/{id}.{format}

Where {resource} can be:

● contact

● user

● activity

or their plural forms (contacts, users)

{format} can be either json to indicate the desired response being the first one

the default format.

{id} is the unique identifier for the resourceSample request:

https://app.bigcontacts.com/api/contacts.json?access_token=iiRzm9b7SDCQ53SibDRb

x34_wPsgGSJ9gOqWlyvck

In this case, the response will contain all the contacts for the user associated to the

access token being used.

Note: even though the access token is being passed in the URL you can instead use an

Authorization HTTP header

(e.g. “Authorization: Bearer iiRzm9b7SDCQ53SibDRbx34_wPsgGSJ9gOqWlyvck”).

For simplicity sake the access_token URL parameter will be removed from the

examples below.

All responses contain 3 default fields:

status: success or error

message: a string extending the status (can be an error message)

payload: object containing the requested resource. can be an collection or a single

object

current_user_id: The ID belonging to the user currently logged in

If the payload is populated, that is, if the resource existed, there will be also 2 more

fields:

page: the page number that was requested, for pagination purposes

totalcount: total number of records that matched the query

{"result":"error","message":"No such contact","payload":[]}

will be the typical response for a request of a non existent contact

Important Note:

For any POST or PUT request (mostly used to create or update items), it is required to

add the following header: “ContentType: application/xwwwformurlencoded”.

An exception to this rule is when trying to create and edit contacts, which takes JSON

input, and does not need to be URLencoded.

If you are using Firefox’s RESTClient plugin, the way to do it is by clicking on “Headers”

(top menu), then selecting the “Custom Header” option. When the popup opens, enter

“ContentType” in the name field, “application/xwwwformurlencoded” as value, and then

click on “Okay”.These are the functions currently supported by the API:

1. Users

a. List all team members (users)

GET /api/users.{format}

2. Contacts

a. List all contacts

GET /api/contacts.{format}

b. Get one specific contact

GET /api/contact/{id}.{format}

c. Add a contact

POST /api/contacts.{format}

d. Update a contact

PUT /api/contact/{id}.{format}

e. Delete a contact

DELETE /api/contact/{id}.{format}

3. Contact Activity

a. List all contact activity

GET /api/contact/{id}/activity.{format}

b. Get one specific contact activity record

GET /api/contact/{id}/activity/{activityid}.{format}

c. Add contact activity

POST /api/contact/{id}/activity.{format}

d. Update contact activity

PUT /api/contact/{id}/activity/{activityid}.{format}

e. Delete contact activity

DELETE /api/contact/{id}/activity/{activityid}.{format}Users

List all team members (users)

GET /api/users.{format}

Returns the data for all team members, which are the users belonging to the customer

Sample response in JSON for https://app.bigcontacts.com/api/users.json

1.{

2. "status": "success",

3. "message": "Users listing",

4. "page": 1,

5. "totalcount": 3,

6. "payload":

7. [

8. {

9. "id": 1,

10. "email": "robert.hammond@live.com.ar",

11. "first_name": "Robert",

12. "last_name": "Hammond",

13. "short_name": "Robert H.",

14. "color": "91AF7C",

15. "last_login": "20131106T19:

04:46+0000"

16. },

17. {

18. "id": 2,

19. "email": "carl.olmann@gmail.com",

20. "first_name": "Carl",

21. "last_name": "Olmann",

22. "short_name": "Carl O.",

23. "color": "88FA6A",

24. "last_login": "20131104T12:

15:12+0000"

25. },

26. {

27. "id": 3,

28. "email": "paul.farnan@gmail.com",

29. "first_name": "Paul",

30. "last_name": "Farnan",

31. "short_name": "Robert H.",

32. "color": "AC98BC",

33. "last_login": "20131116T07:

42:11+0000"

34. },

35. ]

36. Contacts

List all contacts

GET /api/contacts.{format}

Returns a list of all contacts that belong to the customer and that can be seen by the

invoking user.

e.g. Customer ACME has 3 users. One of these 3 users is named John Doe. The

access token being used in the requests is associated to John Doe. Sending this

request will present a list of all contacts that belong to ACME and can be seen by John

Doe. Contact visibility can be managed via GUI for testing purposes.

If you need pagination, just append a URL parameter named page e.g.

https://app.bigcontacts.com/api/contacts.json?page=2

There is also an optional pagination parameter called “results” (it defaults to 100), which

defines how many results will be displayed per page.

https://app.bigcontacts.com/api/contacts.json?page=2&results=50

All contacts in JSON format: https://app.bigcontacts.com/api/contacts.json

Filter contacts by update or creation date________________________

GET /api/contacts.{format}&{operator}={datetime}

By adding the {operator} parameter, it will filter the contact list basing on their update or

creation date.

The {operator} parameter can take any of the following values:

updated

(this will return contacts that were updated on the date)

updated_lt

(this will return contacts that were updated before the date)

updated_gt

(this will return contacts that were updated after the date)

updated_lte

(this will return contacts that were updated before or on the date)

updated_gte

(this will return contacts that were updated after or on the date)

created

(this will return contacts that were created on the date)

created_lt

(this will return contacts that were created before the date)

created_gt

(this will return contacts that were created after the date)

created_lte

(this will return contacts that were created before or on the date)

created_gte (this will return contacts that were created after or on the date)

The {datetime} parameter can take any valid representation of time, including but not

limited to date formats, datetime formats, and string representation.

Examples: 20140101 11:54:01, 20130503,now, today, etc.Get only contacts that match a certain criteria_____________________

GET /api/contacts.{format}&q={search_criteria}

By adding the q parameter, it will return a list of contacts that contain the search_criteria

value either in any of their emails, their company name, or their or their spouse’s or

family members’ first or last name.

Get one specific contact_______________________________________

GET /api/contact/{id}.{format}

Returns the data for the requested contact id. User must have permission to see the

contact and the id must be a valid contact id belonging to the customer.

Sample response in JSON for https://app.bigcontacts.com/api/contact/2

1.{

2. "status": "success",

3. "message": "Contact",

4. "page": 1,

5. "totalcount": 1,

6. "payload":

7. {

8. "id": 435,

9. "is_business": false,

10. "division": "Design Division",

11. "first_name": "Shirley",

12. "middle_name": "J.",

13. "last_name": "McRae",

14. "salutation": "Ms.",

15. "gender": "f",

16. "date_of_birth": "19341230T00:

00:000300",

17. "contact_type":

18. {

19. "id": 91,

20. "name": "Client"

21. },

22. "abcd": "A",

23. "dl_number": "DriverLicID32322",

24. "dl_issuing_state": "GA",

25. "dl_issue_date": "20101010T00:

00:000300",

26. "dl_expiration_date": "20131009T00:

00:000300",27. "email_opt_out": false,

28. "comments": "Some sample comments",

29. "is_private": false,

30. "phones":

31. [

32. {

33. "id": 1753,

34. "type": "F",

35. "phone": "(678) 5463723"

36. },

37. {

38. "id": 1752,

39. "type": "H",

40. "phone": "(404) 6574938"

41. },

42. {

43. "id": 1754,

44. "type": "M",

45. "phone": "(773) 3562939"

46. },

47. {

48. "id": 1755,

49. "type": "O",

50. "phone": "(919) 4256222"

51. }

52. ],

53. "office_phones":

54. [

55. {

56. "id": 1756,

57. "type": "W",

58. "phone": "(212) 6835853"

59. }

60. ],

61. "addresses":

62. [

63. {

64. "id": 936,

65. "address": "2154 Peachetree Road",

66. "address2": "Suite 224",

67. "address3": "",

68. "city": "Atlanta",

69. "state": "GA",

70. "country": "USA",

71. "postal_code": "31265"

72. }

73. ],74. "office_addresses":

75. [

76. {

77. "id": 937,

78. "address": "4805 Pine Needle Dr",

79. "address2": "",

80. "address3": "",

81. "city": "Duluth",

82. "state": "GA",

83. "country": "USA",

84. "postal_code": "30300"

85. }

86. ],

87. "emails":

88. [

89. {

90. "id": 1007,

91. "email": "shirley33@hotmail.com"

92. },

93. {

94. "id": 1008,

95. "email": "mcrae@gangnamstyle.com"

96. }

97. ],

98. "office_emails":

99. [

100. {

101. "id": 1009,

102. "email": "webmaster@gmail.com"

103. },

104. {

105. "id": 1010,

106. "email": "webmaster@aol.com"

107. }

108. ],

109. "im_services":

110. [

111. {

112. "id": 293,

113. "im_service_type":

114. {

115. "id": 46,

116. "name": "Skype"

117. },

118. "name": "shirley"

119. },

120. {121. "id": 294,

122. "im_service_type":

123. {

124. "id": 47,

125. "name": "AOL"

126. },

127. "name": "aolshirley"

128. },

129. {

130. "id": 295,

131. "im_service_type":

132. {

133. "id": 48,

134. "name": "Gtalk"

135. },

136. "name": "shirley@gmail.com"

137. }

138. ],

139. "spouse":

140. {

141. "id": 309,

142. "first_name": "Maggie",

143. "last_name": "Simpson",

144. "nickname": "Jabru",

145. "date_of_birth": "19851212T00:

00:000300",

146. "gender": "f",

147. "country": "USA",

148. "dl_number": "223232",

149. "email_opt_out": true,

150. "phone": "4555788944",

151. "fax": "(888) 2349876",

152. "emails": "spouse@email.com",

153. "screen_name": "TheSpouse Screen Name",

154. "skype_id": "skypeId",

155. "ssn": "SSNnumber",

156. "website": "www.hotmail.com"

157. },

158. "family":

159. [

160. {

161. "id": 464

162. },

163. {

164. "id": 504,

165. "first_name": "Jhon",

166. "last_name": "McRae",167. "formal_name": "John McRae III",

168. "country": "USA",

169. "date_of_birth": "19851212T00:

00:000300",

170. "dl_number": "223232",

171. "fax": "(888) 2349876",

172. "phone": "(234) 8903746",

173. "gender": "m",

174. "interests": "Jet skiing",

175. "relation": "Son",

176. "salutation": "Mr.",

177. "ssn": "SSNnumber",

178. "website": "www.yahoo.com"

179. },

180. {

181. "id": 505,

182. "first_name": "Wanda",

183. "last_name": "McRae",

184. "country": "USA",

185. "date_of_birth": "19921122T00:

00:000200",

186. "phone": "(234) 3333336",

187. "gender": "f",

188. "interests": "Buying clothes",

189. "relation": "Daughter"

190. }

191. ],

192. "custom_fields":

193. [

194. {

195. "id": 2,

196. "custom_field":

197. {

198. "id": 3,

199. "customer":

200. {

201. "id": 20,

202. "first_name": "Sebastian",

203. "last_name": "Choren",

204. "company": "Codigo Austral",

205. "phone": "(678) 5559834",

206. "email": "schoren@codigoaustral.com",

207. "created": "20121226T17:

54:350300",

208. "updated": "20121226T17:

54:350300"

209. },210. "name": "blood type",

211. "sort_order": 0,

212. "created": "20121226T17:

54:350300",

213. "updated": "20121226T17:

54:350300"

214. },

215. "value": "0+",

216. "created": "20121226T17:

54:350300",

217. "updated": "20121226T17:

54:350300"

218. }

219. ],

220. "is_active": true,

221. "assigned_to":

222. {

223. "id": 87,

224. "email": "schoren@codigoaustral.com",

225. "first_name": "Sebastian",

226. "last_name": "Choren",

227. "short_name": "Sebas",

228. "color": "91A7C7"

229. },

230. "interests":

231. [

232. {

233. "id": 61,

234. "name": "Waterpolo"

235. },

236. {

237. "id": 62,

238. "name": "Bird shooting"

239. },

240. {

241. "id": 63,

242. "name": "Water skiing"

243. },

244. {

245. "id": 64,

246. "name": "Vintage billiard tables"

247. }

248. ],

249. "groups":

250. [

251. {

252. "id": 77,253. "name": "US clients"

254. }

255. ],

256. "categories":

257. [

258. {

259. "id": 242,

260. "value": "Brown"

261. },

262. {

263. "id": 246,

264. "value": "2535"

265. },

266. {

267. "id": 250,

268. "value": "Robust"

269. },

270. {

271. "id": 253,

272. "value": "Volley"

273. }

274. ],

275. "created": "20121226T17:

54:350300",

276. "updated": "20121226T17:

54:350300",

277. "dropbox":

278. [

279. ]

280. }

281. }

Add a contact________________________________________________

POST /api/contacts.{format}

Send the contact data in the request headers using the same JSON format used by the

API to return a contact.

Associated entities

Some fields are considered as separate entities that can be associated with the contact.

Those fields, such as phone, email, fax, etc must be sent as a JSON array.

1. “phones”:

2. [

3. {

4. “phone”: “(555) 5555555”,5. “is_office”: 0,

6. “type”: “H”

7. },

8. {

9. “phone”: “(666) 6666666”,

10. “is_office”: 1,

11. “type”: “W”

12. }

13. ]

Please note: even though the output format matches the input format, it is important not

to include the “ID” field in the JSON requests, or it can lead to unexpected results.

Required Fields

For a contact to be added to the database, the following three fields are mandatory:

first_name (Contact’s first name)

last_name (Contact’s last name)

emails.email (Contact’s primary email address)

Fields list

first_name

String. First name for primary contact. Required

middle_name

String. Middle name for primary contact

last_name

String. Last name for primary contact. Required

is_business

Bool. Is this contact a business? (defaults to 0)

emails

Array of JSON Objects. Email addresses for the contact. The object can contain the

following values:

String email: The email address

Bool is_office: (optional defaults to 0). Is this email work related?

addresses

Array of JSON Objects. Addresses for the contact. The object can contain the

following values:

String address: Address line 1.

String address2: Address line 2.

String address3: Address line 3.

String city: Sity.String state: State.

String country: Country.

String postal_code: Zip Code.

phones

Array of JSON Objects. Phones for the contact. The object can contain the following

values:

String phone: Phone number.

String type: This field can take any of the following values: W for “work”. H for

“home”. M for “mobile”. O for “other”. F for “fax”. P for “pager”.

String is_office: Is this phone workrelated?

im_services

Array of JSON Objects. Instant messaging information (Skype, etc) for the contact.

The object can contain the following values:

String im_services_type: One of the following values: AIM, AOL, Gtalk, Skype,

Yahoo.

String name: The ID or username used to reach the contact in the IM Service.

social_media

Array of JSON Objects. Social media information (Facebook, Twitter, etc) for the

contact. The object can contain the following values:

String social_media_type: One of the following values: Facebook, LinkedIn,

Twitter,

YouTube, flickr, vimeo.

String name: The ID or username used by the contact in the social media.

custom_fields

Array of JSON Objects. Custom fields. The object can contain the following values:

String name: Name of the custom field (note: if the name does not match any

existing custom field, a new one will be created automatically).

String value: Value of the custom field.