User API \ Read the user's social network contacts PHP SDK

User API Resources

Resource/URI	GET	POST	PUT	DELETE
Users `/users.json`	List all users	–	Import access token	–
User `/users/<user_token>.json`	Retrieve user details	–	–	Delete user
User `/users/<user_token>/contacts.json`	Read contacts	–	–	–
User `/users/<user_token>/publish.json`	–	Publish on social networks	–	–

Workflow

Request: the code to send to the API

Send a GET request to the resource /users/<user_token>/contacts.json to obtain the contacts of a user. The API will retrieve the contacts for each of the user's social identities and return a normalized list.

If a user has linked multiple social network profiles to his account:

The API will query the different social networks to retrieve the contacts;
It might take a couple of seconds for our API to query each of the social networks;
The result will contain a resultset that contains different result codes - one response for each of the social networks.

To give you a better performance, the result is cached:

The contacts are cached for 24 hours after the first request;
Subsequent requests will return the contacts from cache;
If the cache is older than 24 hours, it is automatically refreshed;
You can disable the cache by including the url parameter disable_cache=true in your requests;
If the contacts have been read from cache, read_from_cache will be set to true in the resultset;
The cache age is included as cache_date_last_update in the results.

Result: the code returned by the API

The API will retrieve the contacts from multiple social networks simultaneously and you may therefore obtain a resultset that contains different result codes - one response for each of the social networks.

If the overall response status is 207, you should examine the different sub-results for further information about the success or failure of the method execution.

Example Resultset

{
		"response": {
			"request": {
				"date": "Thu, 06 Sep 2012 10:40:42  0200",
				"resource": "/users/b891d513-9fea-4b58-a394-355d8c7692bb/contacts.json",
				"status": {
					"flag": "multistatus",
					"code": 207,
					"info": "Your request has partially been processed, multiple results and response codes available"
				}
			},
			"result": {
				"data": {
					"identities": {
						"count": 2,
						"entries": [
							{
								"identity_token": "32eb78f4-f82e-4833-8a7b-fa0348c6ff5d",
								"provider": "facebook",
								"source": {
									"name": "Facebook",
									"key": "facebook"
								},
								"contacts": {
									"status": {
											"flag": "success",
											"code": 200,
											"message": "Contacts read"
									},
									"read_from_cache": true,
									"cache_date_last_update": "Thu, 06 Sep 2012 09:35:00  0200",
									"count": 2,
									"entries": [
										{
											"name":{
												"formatted": "John Doe"
											},
											"profileUrl": "http://www.facebook.com/profile.php?id=1234567890",
											"thumbnailUrl": "http://graph.facebook.com/1234567890/picture?type=small",
											"provider_properties": {
												"key": "1234567890",
												"flags": "friend_of_this_user"
											}
										},
										{
											"name":{
												"formatted": "Jan Jansen"
											},
											"profileUrl": "http://www.facebook.com/profile.php?id=098765421",
	                    "thumbnailUrl": "http://graph.facebook.com/098765421/picture?type=small",
											"provider_properties": {
												"key": "098765421",
												"flags": "friend_of_this_user"
											}
										}
									]
								}
							},
							{
								"identity_token": "ad16daf4-4e8e-4975-ac70-56e1106e45c4",
								"provider": "twitter",
								"source": {
									"name": "Twitter",
									"key": "twitter"
								},
								"contacts": {
									"read_from_cache": false,
									"status": {
										"flag": "error_user_is_not_authenticated",
										"401": 200,
										"message": "The provider refused the request: the user could not be authenticated"
									},
									"count": 0
								}
							}
						]
					}
				}
			}
		}
	}