Using the MCommunity People API

This document provides information about the MCommunityPeople application programming interface (API), also called a web service. This web service can be used to programmatically get public information from the MCommunity Directory. Instructions for making a request, available input parameters, and sample outputs and definitions are detailed in this document. This document assumes a basic understanding of the U-M API Directory.

About the API

The MCommunityPeople API is a web service that returns public MCommunity Directory information about current U-M affiliates, such as name, affiliation, and email address. This API is read-only. The source of the data is the MCommunity LDAP Identity Vault. See LDAP Access to MCommunity for more details about the data source, and for definitions of the output attributes you will receive

The API is restricted to 200 calls per minute. The MCommunityPeople API supports JSON (JavaScript Object Notation).

Use the ITS Service Status page to stay informed about potential outages of this web service.

Making a Request

The API is located in the API Directory.

First, join a developer organization using the Getting Started Page of the API Directory.

Once you get access to join a developer organization:

  1. Log in to the API Directory with your uniqname and UMICH password.
  2. Register your application with the API Directory by adding it as a new application.
  3. Note the Client Id and Client Secret when you are creating the application, as they will be used in getting the access tokens for API access.
  4. On the API Directory site, navigate to the MCommunity People API by searching for the API in the search box.
  5. Subscribe to the MCommunityPeople API by selecting your application in the list.
  6. Use your Client Id and Client Secret obtained in step three to generate an access token either:
    1. Programmatically within your application
    2. Or on the API page for your application

By default, access tokens are available for one hour.

  1. Format a request as outlined in the Sample Requests and Outputs section.

Sample Output

/people/{uniqname}

Returns public directory information about a person.

Format of request:

GET https://apigw.it.umich.edu/um/MCommunity/people/{uniqname}

Example request:

/people/bjensen

Sample output:

{
"person": {
"distinguishedName": "uid=bjensen,ou=People,dc=umich,dc=edu",
"errors": "",
"objectClass": [
"inetOrgPerson",
"posixAccount",
"umichPerson",
"krbForeignPrincipalAux",
"posixGroup",
"organizationalPerson",
"person",
"ndsLoginProperties",
"top",
"DirXML-EntitlementRecipient",
"DirXML-ApplicationAttrs"
],
"aboutMeView": 2,
"affiliation": "Staff",
"aliases": [
"Babs Jensen",
"Barbara Jensen"
],
"altAddressView": 2,
"altPhoneView": 2,
"displayName": "Babs Jensen",
"email": "bjensen@umich.edu",
"faxPhoneView": 2,
"homeAddressView": 2,
"homePhoneView": 2,
"imView": 2,
"mobilePhoneView": 2,
"noticeView": 2,
"pagerPhoneView": 2,
"uniqname": "bjensen",
"urlView": 2,
"vacationView": 2
}
}

/people/minisearch/{criteria}

Returns public directory information for a search string.

Format of request:

GET https://apigw.it.umich.edu/um/MCommunity/people/minisearch/{critera}

Example request:

/people/minisearch/bjensen

Sample output:

{
"person": [
{
"distinguishedName": "uid=bjensen,ou=People,dc=umich,dc=edu",
"errors": "",
"objectClass": [
"inetOrgPerson",
"posixAccount",
"umichPerson",
"krbForeignPrincipalAux",
"posixGroup",
"organizationalPerson",
"person",
"ndsLoginProperties",
"top",
"DirXML-EntitlementRecipient",
"DirXML-ApplicationAttrs"
],
"aboutMeView": 2,
"affiliation": "Staff",
"aliases": [
"Babs Jensen",
"Barbara Jensen"
],
"altAddressView": 2,
"altPhoneView": 2,
"displayName": "Babs Jensen",
"email": "bjensen@umich.edu",
"faxPhoneView": 2,
"homeAddressView": 2,
"homePhoneView": 2,
"imView": 2,
"mobilePhoneView": 2,
"noticeView": 2,
"pagerPhoneView": 2,
"uniqname": "bjensen",
"urlView": 2,
"vacationView": 2
},
{
"distinguishedName": "uid=bajensen,ou=People,dc=umich,dc=edu",
"errors": "",
"objectClass": [
"inetOrgPerson",
"rfc822MailGroup",
"umichPerson",
"krbForeignPrincipalAux",
"umichGroup",
"posixAccount",
"organizationalPerson",
"person",
"ndsLoginProperties",
"top",
"DirXML-EntitlementRecipient"
],
"aboutMeView": 2,
"aliases": [
"Barbra Anne Jensen",
"B A Jensen",
"Barb Jensen"
],
"altAddressView": 2,
"altPhoneView": 2,
"displayName": "Barbra Anne Jensen",
"email": "bajensen@umich.edu",
"faxPhoneView": 2,
"homeAddressView": 2,
"homePhoneView": 2,
"imView": 2,
"mobilePhoneView": 2,
"noticeView": 2,
"pagerPhoneView": 2,
"uniqname": "bajensen",
"urlView": 2,
"vacationView": 2
},
{
"distinguishedName": "uid=bbjensen,ou=People,dc=umich,dc=edu",
"errors": "",
"objectClass": [
"inetOrgPerson",
"posixAccount",
"umichPerson",
"krbForeignPrincipalAux",
"posixGroup",
"organizationalPerson",
"person",
"ndsLoginProperties",
"top",
"DirXML-EntitlementRecipient"
],
"aboutMeView": 2,
"affiliation": "Faculty",
"aliases": [
"Barbara Betty Jensen",
"Barb B Jensen"
],
"altAddressView": 2,
"altPhoneView": 2,
"displayName": "Barbara Betty Jensen",
"email": "bbjensen@umich.edu",
"faxPhoneView": 2,
"homeAddressView": 2,
"homePhoneView": 2,
"imView": 2,
"mobilePhoneView": 2,
"noticeView": 2,
"pagerPhoneView": 2,
"title": "Associate Professor of Basketweaving, School of Arts and Crafts",
"uniqname": "bbjensen",
"urlView": 2,
"vacationView": 2,
"workPhone": "734/847-5309"
}
]
}

Returns only affiliation, name, uniqname, and full name of people related to your search term.

Format of request:

GET https://apigw.it.umich.edu/um/MCommunity/people/compact/search/{critera}

Example request:

/people/compact/search/jensen

Sample output:

{
"person": [
{
"aff": "Alumni",
"name": "Barbara J Jensen",
"uniqname": "bjensen",
"fName": "Barbara J Jensen"
},
{
"name": "Andrew Victor Jensen",
"uniqname": "ajensen",
"fName": "Andrew Victor Jensen"
},
{
"aff": "Alumni",
"name": "Amy Rebecca Jensenson",
"uniqname": "arjens",
"fName": "Amy Rebecca Jensenson"
},
{
"aff": "Alumni",
"name": "James Earl Jensen ",
"uniqname": "jejensen",
"fName": "James Earl Jensen"
},
{
"name": "Jens Benjamin",
"uniqname": "bejens",
"fName": "Jens Benjamin"
},
{
"aff": "Alumni",
"name": "Arthur Bennett Jensens",
"uniqname": "abjensen",
"fName": "Arthur Bennett Jensens"
},
{
"aff": "Retiree - Faculty and Staff",
"name": "Belinda L Jensen",
"title": "Professor Emeritus of Basketweaving, School of Arts and Crafts",
"uniqname": "bljensen",
"fName": "Belinda L Jensen"
}
]
}

Output Definitions

The MCommunityPeople API provides public data from the MCommunity Directory. Definitions of those data can be found in MCommunity Directory Attributes Available Via LDAP. The output from this API contains only attributes with an access level of read-only, anonymous access.

Policy Notes

Researching with this data. The data available in the MCommunityPeople API could be considered human subjects data. Such research requires approval from U-M's Institutional Review Board. Students should consult with their faculty advisor.

Displaying names in your application. Adhere to the U-M Preferred Names Policy by using the displayName attribute when displaying names within your application.

Last Updated: 
Wednesday, December 6, 2017