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 |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
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/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 aren't included in the request body maintain their previous values or are 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. |
Response
If successful, this method returns a 200 OK
response code and an updated contact object in the response body.
Examples
Request
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"
}
Response
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": "[email protected]"
}
],
"imAddresses": [
"sip:[email protected]"
],
"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": []
}