Creating and reading Outlook.com contacts

1089 out of 1813 rated this helpful - Rate this topic

Recover your account here

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:

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 me as 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.

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

Note  This code example uses a fictitious contact ID in the path argument. You'll need to replace the value in the example with a valid contact ID.


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;
        }
    );
}


Top

Reading and writing contacts in C# for Windows Store apps and Windows Phone apps

Reading contacts in C#

Note  This code example uses a fictitious contact ID in the GetAsync call. You'll need to replace the value in the example with a valid contact ID.


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


Top

Reading and writing contacts in Objective-C for iOS

Reading contacts in Objective-C

Note  This code example uses a fictitious contact ID in the getWithPath:delegate: call. You'll need to replace the value in the example with a valid contact ID.


-(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.";
    }     
}


Top

Reading and writing contacts in Java for Android

Reading contacts in Java

Note  This code example uses a fictitious contact ID in the contactID string. You'll need to replace the value in the example with a valid contact ID.


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.

Note  The Live Connect APIs don't enable you to create friend entries. However, you can create a contact entry, and then use the Outlook.com UI to invite that contact to become a friend.

Top

Reading and writing contacts using REST

Reading contacts using REST

Note  This code example uses a fictitious contact ID in the path. You'll need to replace the value in the example with a valid contact ID.

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

Top

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.