Update contact

Update the properties of a contact object.

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission type Permissions (from least to most privileged)
Delegated (work or school account) Contacts.ReadWrite
Delegated (personal Microsoft account) Contacts.ReadWrite
Application Contacts.ReadWrite

HTTP request

A contact from a user's default contactFolder.

PATCH /me/contacts/{id}
PATCH /users/{id | userPrincipalName}/contacts/{id}

A contact from a user's top level contactFolder.

PATCH /me/contactFolders/{id}/contacts/{id}
PATCH /users/{id | userPrincipalName}/contactFolders/{id}/contacts/{id}

A contact contained in a child folder of a contactFolder. The example below shows one level of nesting, but a contact can be located in a child of a child and so on.

PATCH /me/contactFolder/{id}/childFolders/{id}/.../contacts/{id}
PATCH /users/{id | userPrincipalName}/contactFolders/{id}/childFolders/{id}/contacts/{id}

Request headers

Header Value
Authorization Bearer {token}. Required.
Content-Type application/json. Required.

Request body

In the request body, supply the values for relevant fields that should be updated. Existing properties that are not included in the request body will maintain their previous values or be recalculated based on changes to other property values. For best performance you shouldn't include existing values that haven't changed.

Property Type Description
assistantName String The name of the contact's assistant.
birthday DateTimeOffset The contact's birthday.
businessAddress PhysicalAddress The contact's business address.
businessHomePage String The business home page of the contact.
businessPhones String The contact's business phone numbers.
categories String The categories associated with the contact.
children String The names of the contact's children.
companyName String The name of the contact's company.
department String The contact's department.
displayName String The contact's display name.
emailAddresses EmailAddress collection The contact's email addresses.
fileAs String The name the contact is filed under.
generation String The contact's generation.
givenName String The contact's given name.
homeAddress PhysicalAddress The contact's home address.
homePhones String collection The contact's home phone numbers.
imAddresses String The contact's instant messaging (IM) addresses.
initials String The contact's initials.
jobTitle String The contact’s job title.
manager String The name of the contact's manager.
middleName String The contact's middle name.
mobilePhone String The contact's mobile phone number.
nickName String The contact's nickname.
officeLocation String The location of the contact's office.
otherAddress PhysicalAddress Other addresses for the contact.
parentFolderId String The ID of the contact's parent folder.
personalNotes String The user's notes about the contact.
profession String The contact's profession.
spouseName String The name of the contact's spouse.
surname String The contact's surname.
title String The contact's title.
yomiCompanyName String The phonetic Japanese company name of the contact. This property is optional.
yomiGivenName String The phonetic Japanese given name (first name) of the contact. This property is optional.
yomiSurname String The phonetic Japanese surname (last name) of the contact. This property is optional.

Response

If successful, this method returns a 200 OK response code and an updated contact object in the response body.

Example

Request

Here is an example of the request.

PATCH https://graph.microsoft.com/v1.0/me/contacts/{id}
Content-type: application/json
Content-length: 1977

{
  "homeAddress": {
    "street": "123 Some street",
    "city": "Seattle",
    "state": "WA",
    "postalCode": "98121"
  },
  "birthday": "1974-07-22"
}
Response

Here is an example of the response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 1977

{
  "id": "AAMkAGI2THk0AAA=",
  "createdDateTime": "2014-10-19T23:08:24Z",
  "lastModifiedDateTime": "2014-10-19T23:08:24Z",
  "changeKey": "EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4",
  "categories": [],
  "parentFolderId": "AAMkAGI2AAEOAAA=",
  "birthday": "1974-07-22",
  "fileAs": "Fort, Garth",
  "displayName": "Garth Fort",
  "givenName": "Garth",
  "initials": "G.F.",
  "middleName": null,
  "nickName": "Garth",
  "surname": "Fort",
  "title": null,
  "yomiGivenName": null,
  "yomiSurname": null,
  "yomiCompanyName": null,
  "generation": null,
  "emailAddresses": [
    {
      "name": "Garth",
      "address": "garth@a830edad9050849NDA1.onmicrosoft.com"
    }
  ],
  "imAddresses": [
    "sip:garthf@a830edad9050849nda1.onmicrosoft.com"
  ],
  "jobTitle": "Web Marketing Manager",
  "companyName": "Contoso, Inc.",
  "department": "Sales & Marketing",
  "officeLocation": "20/1101",
  "profession": null,
  "businessHomePage": "http://www.contoso.com",
  "assistantName": null,
  "manager": null,
  "homePhones": [],
  "mobilePhone": null,
  "businessPhones": [
    "+1 918 555 0101"
  ],
  "homeAddress": {
    "street": "123 Some street",
    "city": "Seattle",
    "state": "WA",
    "postalCode": "98121"
  },
  "businessAddress": {
      "street": "10 Contoso Way",
      "city": "Redmond",
      "state": "WA",
      "countryOrRegion": "USA",
      "postalCode": "98075"  
  },
  "otherAddress": {},
  "spouseName": null,
  "personalNotes": null,
  "children": []
}