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. See the Help page on the API Directory website for information about the 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 60 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 at https://api-gw.it.umich.edu/Mcommunity/People/v1.

First, register your application in the API Directory.

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.

Then, follow these steps to make a request.

1. On the API Directory site, navigate to the MCommunityPeople API.

2. Subscribe to the MCommunityPeople API by selecting your application in the drop-down list. Note your consumer key and consumer secret.

3. Use your consumer key and consumer secret obtained in step two to generate an access token either:

   1. Programmatically within your application (see Generating and Renewing Access Tokens)

   2. Or on the subscription page for your application

   By default, access tokens are available for one hour.

4. 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 http://api-gw.it.umich.edu/Mcommunity/People/v1/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": "[email protected]",
"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 http://api-gw.it.umich.edu/Mcommunity/People/v1/people/minisearch/{criteria}

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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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"
}
]
}

/people/compact/search/{criteria}

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

Format of request:

Example request:

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