---
title: Contacts (MS Graph API)
description: A contact is a resource type in Microsoft Outlook used to organize and store information about an associated object. Contacts use the /user endpoint. For more information, refer to the Microsoft Graph documentation.
component: openicf
page_id: openicf:connector-reference:msgraph-contacts
canonical_url: https://docs.pingidentity.com/openicf/connector-reference/msgraph-contacts.html
section_ids:
  msgraph-add-contacts: Add contacts to a user
  msgraph-read-user-contacts: Return a user entry with contacts
  msgraph-update-user-contacts: Update a user's contacts
  msgraph-remove-contacts: Remove a user's contacts
---

# Contacts (MS Graph API)

A contact is a resource type in Microsoft Outlook used to organize and store information about an associated object. Contacts use the `/user` endpoint. For more information, refer to the [Microsoft Graph documentation](https://learn.microsoft.com/en-us/graph/api/resources/contact?view=graph-rest-1.0).

The MS Graph API connector offers limited support for contacts and includes the following write-only attributes:

```json
{
  "type": "array",
  "items": {
    "type": "object",
    "nativeType": "object"
  },
  "nativeName": "__addContacts__",
  "nativeType": "object",
  "flags": [
    "NOT_READABLE",
    "NOT_RETURNED_BY_DEFAULT"
  ]
},
{
  "type": "array",
  "items": {
    "type": "string",
    "nativeType": "string"
  },
  "nativeName": "__removeContacts__",
  "nativeType": "string",
  "flags": [
    "NOT_READABLE",
    "NOT_RETURNED_BY_DEFAULT"
  ]
},
{
  "type": "array",
  "items": {
    "type": "object",
    "nativeType": "object"
  },
  "nativeName": "__updateContacts__",
  "nativeType": "object",
  "flags": [
    "NOT_READABLE",
    "NOT_RETURNED_BY_DEFAULT"
  ]
}
```

## Add contacts to a user

|   |                                            |
| - | ------------------------------------------ |
|   | You must add contacts to an existing user. |

```
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--header "If-Match: *" \
--request PUT \
--data '{
  "_id": "671fa173-ad81-41c3-89bf-af939426eee7",
  "__addContacts__": {
    "givenName": "Test-Contact",
    "businessAddress": {
      "city": "exampleCity",
      "state": "exampleState",
      "postalCode": "99999",
      "street": "example st",
      "countryOrRegion": "United States"
    }
  }
}' \
"http://localhost:8080/openidm/system/azuread/user/671fa173-ad81-41c3-89bf-af939426eee7"
```

## Return a user entry with contacts

Request

```
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request GET \
'http://localhost:8080/openidm/system/azuread/user/671fa173-ad81-41c3-89bf-af939426eee7?_fields="_id,contacts"'
```

Response

```json
{
  "_id": "671fa173-ad81-41c3-89bf-af939426eee7",
  "contacts": [
    {
      "id": "{CONTACT-ID}",
      "givenName": "Test-Contact",
      "businessAddress": {
        "city": "exampleCity",
        "state": "exampleState",
        "postalCode": "99999",
        "street": "example st",
        "countryOrRegion": "United States"
      }
    }
  ]
}
```

## Update a user's contacts

Request

```
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--header "If-Match: *" \
--request PUT \
--data '{
  "_id": "671fa173-ad81-41c3-89bf-af939426eee7",
  "__updateContacts__": {
    "id": "{CONTACT-ID}",
    "givenName": "Test-Contact-Updated",
    "businessAddress": {
      "city": "exampleCity",
      "state": "exampleState",
      "postalCode": "99999",
      "street": "example st",
      "countryOrRegion": "United States"
    }
  }
}' \
"http://localhost:8080/openidm/system/azuread/user/671fa173-ad81-41c3-89bf-af939426eee7"
```

After updating the user's contacts, a subsequent read on the user with the contacts field returns the updated contacts:

Request

```
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request GET \
'http://localhost:8080/openidm/system/azuread/user/671fa173-ad81-41c3-89bf-af939426eee7?_fields="_id,contacts"'
```

Response

```json
{
  "_id": "671fa173-ad81-41c3-89bf-af939426eee7",
  "contacts": [
    {
      "id": "{CONTACT-ID}",
      "givenName": "Test-Contact-Updated",
      "businessAddress": {
        "city": "exampleCity",
        "state": "exampleState",
        "postalCode": "99999",
        "street": "example st",
        "countryOrRegion": "United States"
      }
    }
  ]
}
```

## Remove a user's contacts

Request

```
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--header "If-Match: *" \
--request PUT \
--data '{
  "_id": "671fa173-ad81-41c3-89bf-af939426eee7",
  "__removeContacts__": [
    "{CONTACT-ID}"
  ]
}' \
"http://localhost:8080/openidm/system/azuread/user/671fa173-ad81-41c3-89bf-af939426eee7"
```

After removing the user's contacts, a subsequent read on the user with the contacts field returns an empty contacts array:

Request

```
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request GET \
'http://localhost:8080/openidm/system/azuread/user/671fa173-ad81-41c3-89bf-af939426eee7?_fields="_id,contacts"'
```

Response

```json
{
  "_id": "671fa173-ad81-41c3-89bf-af939426eee7",
  "contacts": []
}
```