ICF 1.5.20.25

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.

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

{
  "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
{
  "_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
{
  "_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
{
  "_id": "671fa173-ad81-41c3-89bf-af939426eee7",
  "contacts": []
}