User API \ Read a user's social network contacts

Send a GET request to the following resource to retrieve the social network contacts of an existing user.

Resource/URI GET POST PUT DELETE
Users /users.<format> List all users – – –
User /users/<user_token>.<format> Retrieve a user's details – – Delete a user
User /users/<user_token>/contacts.<format> Read a user's contacts – – –
User /users/<user_token>/publish.<format> – Publish on social networks – –

Workflow

1. Request: the code to send to the API

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

Please note:
  1. If a user has linked multiple social networks 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.
  2. To give you a better performance, the result is cached:
    • The contacts are cached for 24 hours after the first request;
    • Subsequent request 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 true in the result;
    • The cache age is included as cache_date_last_update in the results.

2. 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.

HTTP Status Code 207: Multi-Status
  • The API may return one of the following status codes:
    • 200 : The contacts have been read successfully from each of the social networks;
    • 207 : The contacts have been read successfully from some but not from all of the social networks;
    • 4xx : The contacts have been read from none of the social networks

Multi-Status Example: Successfull for Twitter, authentication error for Facebook

		{
		  "response": {
		    "request": {
		      "date": "Mon, 12 Dec 2011 16:40:48 +0100",
		      "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": {
		        "action": "read_user_contacts",
		        "results": [
		          {
		            "provider": "facebook",
		            "user_token": "b891d513-9fea-4b58-a394-355d8c7692bb",
		            "identity_token": "11e07a80-d04a-4a72-9c22-c8ca11c5ab00",
		            "read_from_cache ": true,
		            "cache_date_last_update": "Mon, 12 Dec 2011 15:22:23 +0100",
		            "status": {
		              "flag": "error_user_is_not_authenticated",
		              "code":401,
		              "message": "The provider refused the request: the user could not be authenticated"
		            },
		            "contacts": [		              
		            ]
		          },
		          {
		            "provider": "twitter",
		            "user_token": "b891d513-9fea-4b58-a394-355d8c7692bb",
		            "identity_token": "9c10daf5-8893-4073-b3c0-9e9cc0684ac4",
		            "read_from_cache ": true,
		            "cache_date_last_update": "Mon, 12 Dec 2011 19:22:23 +0100",
		            "status": {
		              "flag": "success",
		              "code":200,
		              "message": "Contacts read successfully"
		            },
		            "contacts": [
		              {
		                "name": {
		                  "formatted": "Example User 1"
		                },
		                "preferredUsername": "example_user1",
		                "profileUrl": "http://twitter.com/example_user1l",
		                "thumbnailUrl": "http://twimg0-a.akamaihd.net/profile_images/1619195437/oneall_twitter_normal.png",
		                "aboutMe": "Example User1 Description",
		                "provider_properties": {
		                  "key":1234567890,
		                  "flags": "followed_by_this_user"
		                }
		              },
		              {
		                "name": {
		                  "formatted": "Example User 2"
		                },
		                "preferredUsername": "example_user2",
		                "profileUrl": "http://twitter.com/example_user1l",
		                "thumbnailUrl": "http://twimg0-a.akamaihd.net/profile_images/1619195437/oneall_twitter_normal.png",
		                "aboutMe": "Example User2 Description",
		                "provider_properties": {
		                  "key":223344556677,
		                  "flags": "follows_this_user,followed_by_this_user"
		                }
		              },
		            ]
		          }
		        ]
		      }
		    }
		  }
		}