Creating and reading Outlook.com contacts
The Live Connect APIs are deprecated. We recommend that you use the Outlook REST APIs to build your solutions. This will extend your reach to Outlook.com users and Office 365 enterprise customers. Although the Live Connect APIs will be supported in Outlook.com for the short term, existing Live Connect API solutions might stop working without advanced notice. If your app is using IMAP with OAuth 2.0, it will continue to work, but our REST APIs are the primary APIs for building apps that connect to Outlook.com and Office 365. Read the article on how you can take advantage of the Outlook REST APIs.
This topic describes how your apps can use the Live Connect APIs to create and read an Outlook.com user's contacts in these languages:
- JavaScript and HTML for Windows Store apps
- C# for Windows Store apps and Windows Phone apps
- Objective-C for iOS
- Java for Android
- REST API
For your app to read a user's contacts, the wl.basic scope must been granted to it by the user. To add a new contact to a user's contacts list, the wl.contacts_create scope is required. For info about requesting the required scope from your app, see Obtaining user consent.
To get the full benefit of the code examples in this topic, you can use them in the context of larger code reference samples that we provide in Working with the code examples.
Specifying a contact ID
The contact ID shown in these code examples is fictitious and won't work in your app. In your app, you'll need use a valid contact ID. Here are some examples of ways to get contact IDs to use in the path parameter:
- Use the contact ID of a contact.
- Get info about the currently signed-in user's contacts and friends by specifying
meas the user ID, as in:me/contacts, to get info about all of the signed-in user's contacts.me/friends, to get info about all of the signed-in user's friends.Note A friend is another Outlook.com user that a user has invited to be a friend and that has accepted the friend request. A friend is a contact that has its is_friend structure set to true. (You can't set the is_friend structure programmatically.)
- If you have the user ID of someone, get info about his or her contacts and friends by using the user ID in place of USER_ID as shown in these examples:
- USER_ID
/contacts, to get info about all of the contact entries for the user represented by USER_ID. - USER_ID
/friends, to get info about all of the friend entries for the user represented by USER_ID.
- USER_ID
You can also use the contact ID argument to filter the results returned in a collection. For example:
- Get a limited number of contact or friend entries by using the limit parameter in the preceding code to specify the number of entries to get. For example, to get the first two contact entries for the signed-in user, use
me/contacts?limit=2. - Specify the first contact or friend entry to get by setting the offset parameter in the preceding code to the index of the first entry that you want to get. For example, to get two contact entries for the signed-in user, starting at the third contact entry, use
me/contacts?limit=2&offset=3.Note In the JavaScript Object Notation (JSON)-formatted object that's returned, you can look in the paging object for the previous and next structures to get the offset and limit parameter values of the previous and next entries.
Reading and writing contacts in JavaScript and HTML for Windows Store apps
Reading contacts in JavaScript
function readContact_onClick() { WL.login({ scope: "wl.basic" }).then( function (response) { WL.api({ path: "contact.83960a61000000000000000000000000", method: "GET" }).then( function (response) { document.getElementById("resultDiv").innerHTML = "ID: " + response.id + "<br/>Name: " + response.first_name + " " + response.last_name; }, function (responseFailed) { document.getElementById("infoArea").innerText = "Error calling API: " + responseFailed.error.message; } ); }, function (responseFailed) { document.getElementById("infoArea").innerText = "Error signing in: " + responseFailed.error_description; } ); }
Writing contacts in JavaScript
function createContact_onClick() { WL.login({ scope: "wl.contacts_create" }).then( function (response) { WL.api({ path: "me/contacts", method: "POST", body: { first_name: "William", last_name: "Flash" } }).then( function (response) { document.getElementById("resultDiv").innerHTML = "ID: " + response.id + "<br/> Name: " + response.first_name + " " + response.last_name; }, function (responseFailed) { document.getElementById("infoArea").innerText = "Error calling API: " + responseFailed.error.message; } ); }, function (responseFailed) { document.getElementById("infoArea").innerText = "Error signing in: " + responseFailed.error_description; } ); }
Reading and writing contacts in C# for Windows Store apps and Windows Phone apps
Reading contacts in C#
private async void btnReadContact_Click(object sender, RoutedEventArgs e) { try { LiveConnectClient liveClient = new LiveConnectClient(this.session); LiveOperationResult operationResult = await liveClient.GetAsync("contact.b4466224b2ca42798c3d4ea90c75aa56"); dynamic result = operationResult.Result; this.infoTextBlock.Text = "Contact: " + result.name; } catch (LiveConnectException exception) { this.infoTextBlock.Text = "Error getting contact info: " + exception.Message; } }
Writing contacts in C#
private async void btnCreateContact_Click(object sender, RoutedEventArgs e) { try { var contact = new Dictionary<string, object>(); contact.Add("first_name", "Roberto"); contact.Add("last_name", "Tamburello"); LiveConnectClient liveClient = new LiveConnectClient(this.session); LiveOperationResult operationResult = await liveClient.PostAsync("me/contacts", contact); dynamic result = operationResult.Result; this.infoTextBlock.Text = string.Join(" ", "Contact:", result.name, "ID:", result.id); } catch (LiveConnectException exception) { this.infoTextBlock.Text = "Error creating contact: " + exception.Message; } }
Reading and writing contacts in Objective-C for iOS
Reading contacts in Objective-C
-(void) getContact
{
[self.liveClient getWithPath:@"contact.f347aa9f000000000000000000000000"
delegate:self];
}
-(void) liveOperationSucceeded:(LiveOperation *)operation
{
NSString *firstName = [operation.result objectForKey:@"first_name"];
NSString *lastName = [operation.result objectForKey:@"last_name"];
NSString *gender = [operation.result objectForKey:@"gender"];
self.displayLabel.text = [NSString stringWithFormat:@"Last Name: %@\n First Name: %@\n Gender: %@", lastName, firstName, gender];
}
Writing contacts in Objective-C
- (void) createContact
{
NSString *firstName = firstNameTextField.text;
NSString *lastName = lastNameTextField.text;
NSDictionary *postBody = [NSDictionary dictionaryWithObjectsAndKeys:
firstName, @"first_name",
lastName, @"last_name", nil];
[self.liveClient postWithPath:@"me/contacts"
dictBody:postBody
delegate:self
userState:@"create contact"];
}
- (void) liveOperationSucceeded:(LiveOperation *)operation
{
if ([operation.userState isEqual:@"create contact"]) {
NSString *contactId = [operation.result objectForKey:@"id"];
NSString *firstName = [operation.result objectForKey:@"first_name"];
NSString *lastName = [operation.result objectForKey:@"last_name"];
self.statusLabel.text = [NSString stringWithFormat: @"The contact(id: %@, first_name: %@, last_name: %@) was created.", contactId, firstName, lastName];
}
}
- (void) liveOperationFailed:(NSError *)error
operation:(LiveOperation *)operation
{
if ([operation.userState isEqual:@"create contact"]) {
self.statusLabel.text = @"The contact creation failed.";
}
}
Reading and writing contacts in Java for Android
Reading contacts in Java
public void readContact() { final String contactId = "contact.c1678ab4000000000000000000000000"; final LiveOperationListener opListener = new LiveOperationListener() { public void onError(LiveOperationException exception, LiveOperation operation) { resultTextView.setText("Error getting contact info: " + exception.getMessage()); } public void onComplete(LiveOperation operation) { JSONObject result = operation.getResult(); resultTextView.setText("Contact's name is " + result.optString("name")); } }; auth.login(this, Arrays.asList(new String[] { "wl.basic" }), new LiveAuthListener() { public void onAuthError(LiveAuthException exception, Object userState) { resultTextView.setText("Error signing in: " + exception.getMessage()); } public void onAuthComplete(LiveStatus status, LiveConnectSession session, Object userState) { client.getAsync(contactId, opListener); } }); }
Writing contacts in Java
public void createContact() { JSONObject contact = new JSONObject(); try { contact.put("first_name", "Roberto"); contact.put("last_name", "Tamburello"); } catch (JSONException e) { resultTextView.setText("Error building contact: " + e.getMessage()); return; } client.postAsync("me/contacts", contact, new LiveOperationListener() { public void onComplete(LiveOperation operation) { JSONObject result = operation.getResult(); resultTextView.setText("Contact created. Contact ID = " + result.optString("id") + ", name = " + result.optString("name")); } public void onError(LiveOperationException exception, LiveOperation operation) { resultTextView.setText("Error creating contact: " + exception.getMessage()); } }); }
In the preceding code, you can change me to USER_ID, where USER_ID represents the signed-in user's user ID.
For details about the minimum required and optional structures that your app must provide when using POST, see the "Contact object" section in REST reference.
Reading and writing contacts using REST
Reading contacts using REST
GET https://apis.live.net/v5.0/contact.de3413e6000000000000000000000000?access_token=ACCESS_TOKEN
Writing contacts using REST
POST https://apis.live.net/v5.0/me/contacts
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"first_name": "Roberto",
"last_name": "Tamburello"
}
