Names in the Person API

The Person API contains several types and sources of names for its persons. This document supplements the API specification to provide more details on names in the Person API. If a person has a prefix or suffix for their name, it will only be displayed on their Workday names.

"Primary" Names

The primary name is a name relationship derived from a collection of names among all the data sources feeding into the Person API.

It is indicated by a nameType of primary , and has a source of IAM .

"IAM" Sources

A name relationship with a source of IAM indicates that it comes from an identity system managed on behalf of the originating institution by the Universities of Wisconsin.

Some examples of this include SIS and Workday.

When a person is present in multiple IAM systems (e.g. a student who is also an employee would be present in the originating institution's Workday and SIS), the name chosen will be based on that person's primary relationship with their institution.

"Workday" Sources

A name relationship with a source of Workday was specifically set in Workday and may contain a prefix or a suffix .

"SIS" sources

A name relationship with a source of SIS is a person's legal name.

SIS legal names are currently UW-Madison exclusive and are only available if requested and granted during the access request process.

"Name In Use" Names

The name in use is a name relationship created directly in the API via the POST /people/{id}/names endpoint ( Person API documentation , Mock Person API documentation ) or is derived from profile sources.

nameInUse is currently UW-Madison exclusive.

It is indicated by a nameType of nameInUse , and has a source of profile .

"Profile" Sources

A name relationship with a source of profile indicates that it comes from a system managed directly by the originating institution.

Examples of this include the UW-Madison Personal Information Profile .

"Preferred" Names

Users may set a preferred name in the Workday. These names are available in the API with a nameType of preferred and a source of Workday . This name may contain UTF8 characters and has 1,024 byte limit.

The Root Person Object's Name

If a Person has a nameInUse name relationship, the root person object's firstName and lastName attributes will default to that, falling back to the primary name relationship otherwise.

Webhooks and the Root Person Object's Name Attributes

Since the root person object's name attributes are derived from its name relationships, depending on how you configure your webhook, webhook events will be sent for some or all changes to name relationships.

However, a change to the root person object's name may not occur at the same time as a change to one of the name relationships due to the asynchronous nature of root person object updates and the fact that not all name relationship updates will modify the root person object (e.g. a middle name changing will not affect the root person object, as it does not have a middle name attribute).

Therefore, we recommend using webhook relationship filters to get webhook events for only the names that are needed:

• If your application specifically needs to know when changes occur to primary or nameInUse name relationships, create webhook relationship filters on the names relationship.
• If your application only cares when the root person object's firstName and/or lastName attributes change, create webhook relationship filters on the self relationship.

Legal Names Vs. Name In Use

Currently, the Person API does not distinguish between legal names vs. other names.

If you have specific requirements for legal names, please contact us.

Contact

If you have any questions about which name your application should use, please email us: api@doit.wisc.edu

Glossary

• Root person/root person object - The base Person, such as that which is returned from the GET /people/{id} endpoint ( Person API reference , Mock Person API reference ).
• Name relationship - A specific name resource object associated with a specific Person, such as that which is returned from the GET /people/{id}/names/{nameId} endpoint ( Person API reference , Mock Person API reference ).
• Name relationships - All name resource objects associated with a specific Person, such as those which are returned from the GET /people/{id}/names endpoint ( Person API reference , Mock Person API reference ).