Update contact

Important: APIs under the /beta version in Microsoft Graph are in preview and are subject to change. Use of these APIs in production applications is not supported.

Update the properties of contact object.


One of the following scopes is required to execute this API: Contacts.ReadWrite

HTTP request

A contact from 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.
categories String The categories associated with the contact.
children String
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.
gender String The contact's gender.
generation String The contact's generation.
givenName String The contact's given name.
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.
nickName String The contact's nickname.
officeLocation String The location of the contact's office.
parentFolderId String The ID of the contact's parent folder.
personalNotes String The user's notes about the contact.
phones phone collection Phone numbers associated with the contact, for example, home phone, mobile phone, and business phone.
postalAddresses physicalAddress collection Addresses associated with the contact, for example, home address and business address.
profession String The contact's profession.
spouseName String The name of the contact's spouse/partner.
surname String The contact's surname.
title String The contact's title.
websites website collection Web sites associated with the contact.
weddingAnniversary Date The contact's wedding anniversary.
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.

Since the contact resource supports extensions, you can use the PATCH operation to add, update, or delete your own app-specific data in custom properties of an extension in an existing contact instance.


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



Here is an example of the request.

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

  "postalAddresses": [{
    "type": "business",
    "postOfficeBox": "P.O. Box 100",
    "street": "123 Some street",
    "city": "Seattle",
    "state": "WA",
    "countryOrRegion": "USA",
    "postalCode": "98121"
  "birthday": "1974-07-22"

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": [
  "jobTitle": "Web Marketing Manager",
  "companyName": "Contoso, Inc.",
  "department": "Sales & Marketing",
  "officeLocation": "20/1101",
  "profession": null,
  "assistantName": null,
  "manager": null,
  "phones": [{
    "type": "business",
    "number": "+1 918 555 0101"
  "postalAddresses": [{
    "type": "business",
    "postOfficeBox": "P.O. Box 100",
    "street": "123 Some street",
    "city": "Seattle",
    "state": "WA",
    "countryOrRegion": "USA",
    "postalCode": "98121"
  "spouseName": null,
  "personalNotes": null,
  "children": [], 
  "gender": null,
  "websites": [{
      "type": "work",
      "address": "http://www.contoso.com",
      "name": "Contoso"
  "weddingAnniversary": null

See also