Update contact

Namespace: microsoft.graph

Update the properties of a contact object.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet


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/contactFolders/{id}/childFolders/{id}/.../contacts/{id}
PATCH /users/{id | userPrincipalName}/contactFolders/{id}/childFolders/{id}/contacts/{id}

Request headers

Header Value
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
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, don't include existing values that haven't changed.

When you update structured properties such as homeAddress, you must pass the full property set.

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. Note that later updates to other properties may cause an automatically generated value to overwrite the displayName value you have specified. To preserve a pre-existing value, always include it as displayName in an update operation.
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/partner.
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.


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



The following example shows a request.

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

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


The following example shows the response.

Note: The response object shown here might be shortened for readability.

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

  "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@contoso.com"
  "imAddresses": [
  "jobTitle": "Web Marketing Manager",
  "companyName": "Contoso, Inc.",
  "department": "Sales & Marketing",
  "officeLocation": "20/1101",
  "profession": null,
  "businessHomePage": "https://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": []