Authoritative person and identity data for UW-Madison — names, populations, affiliations, contact points, exports and webhooks. 47 operations over 31 paths, JSON:API envelopes, OAuth 2.0 client credentials. Gated: production access requires an approved institutional request. This is the closest thing in the estate to SCIM, expressed in UW-local terms.
---
openapi: "3.0.2"
info:
title: "Person API"
version: "1.0.0"
contact:
name: "DoIT Enterprise Integration API Team"
email: "api@doit.wisc.edu"
url: "https://go.wisc.edu/k701y6"
description: "For more information on the Person API, including instructions for\
\ getting access, check out the <a href=\"https://kb.wisc.edu/uw-apis/159390\"\
>Person API KB</a>.\n"
servers:
- url: "https://api.wisc.edu"
security:
- OAuth2ClientCredentials: []
externalDocs:
description: "Read more about JSON:API here"
url: "https://jsonapi.org/"
paths:
/people:
get:
description: "Get a collection of people. The attributes `dateOfBirth`, `deceased`,\
\ and `legalSex` will only show up if you have the 'Sensitive Person Demographics'\
\ permission."
summary: "Get people."
operationId: "get_people"
tags:
- "people"
parameters:
- name: "advancedFilter"
in: "query"
description: "Filter results of query using the [Advanced Filter](https://kb.wisc.edu/uw-apis/158404#advanced-filters)."
required: false
style: "deepObject"
explode: true
schema:
type: "object"
additionalProperties: false
properties:
attribute:
type: "string"
example: "and(equals(firstName, \"John\"), equals(lastName, \"Doe\"\
))"
- name: "filterIncluded"
in: "query"
description: "Filter the resources returned in the `included` section of the\
\ response. Refer to the [Person API Documentation](https://kb.wisc.edu/uw-apis/158404#filter-included)\
\ for more information about the `filterIncluded` query param."
required: false
style: "deepObject"
explode: true
schema:
type: "object"
additionalProperties: false
properties:
relationship:attribute:
type: "string"
example: "jobs:title"
attribute:
type: "string"
example: "firstName"
- name: "fields"
in: "query"
description: "Specify the list of fields you would like to return for each\
\ resource type. For example, `fields[people]=firstName,lastName` will\
\ just return the names for people. If you are including related resources\
\ with 'includes' you can also specify fields on those resources as well.\
\ For example, `includes=jobs&fields[people]=jobs&fields[jobs]=title` will\
\ just return titles for jobs. See [Sparse Fieldsets](https://jsonapi.org/format/#fetching-sparse-fieldsets)\
\ for more details."
required: false
style: "deepObject"
explode: true
schema:
type: "object"
additionalProperties: false
properties:
type:
type: "string"
example: "people"
- name: "include"
in: "query"
description: "[include related resources](https://jsonapi.org/format/#fetching-includes).\
\ The relationships can be direct or nested relationships. Direct relationships,\
\ i.e. `include=jobs,identifiers`, will just include those relationships.\
\ Nested relationships, i.e. `include=jobs.costAllocations.worktags`, will\
\ include all intermediate relationships, i.e. jobs, jobs.costAllocations,\
\ and jobs.costAllocations.worktags. The total number of included relationships,\
\ accounting for intermediate relationships, is limited to 10."
schema:
type: "string"
enum:
- "academicAppointments"
- "addresses"
- "affiliations"
- "degrees"
- "emailAddresses"
- "identifiers"
- "jobs"
- "names"
- "organizationStructures"
- "phoneNumbers"
- "socialSecurityNumbers"
- "wiscard"
- name: "filter[relationship.attribute]"
in: "query"
required: false
description: "Filter results using the [filter query parameter family](https://jsonapi.org/recommendations/#filtering).\
\ Refer to the [Person API Documentation](https://kb.wisc.edu/uw-apis/158404)\
\ for more information. Filter resources by `relationship.attribute`."
schema:
type: "string"
nullable: true
- name: "filter[firstName]"
in: "query"
required: false
description: "Filter results using the [filter query parameter family](https://jsonapi.org/recommendations/#filtering).\
\ Refer to the [Person API Documentation](https://kb.wisc.edu/uw-apis/158404)\
\ for more information. Filter `people` resources by `firstName`."
schema:
type: "string"
nullable: true
- name: "filter[lastName]"
in: "query"
required: false
description: "Filter results using the [filter query parameter family](https://jsonapi.org/recommendations/#filtering).\
\ Refer to the [Person API Documentation](https://kb.wisc.edu/uw-apis/158404)\
\ for more information. Filter `people` resources by `lastName`."
schema:
type: "string"
nullable: true
- name: "filter[emailAddress]"
in: "query"
required: false
description: "Filter results using the [filter query parameter family](https://jsonapi.org/recommendations/#filtering).\
\ Refer to the [Person API Documentation](https://kb.wisc.edu/uw-apis/158404)\
\ for more information. Filter `people` resources by `emailAddress`."
schema:
type: "string"
nullable: true
- name: "filter[officeAddress]"
in: "query"
required: false
description: "Filter results using the [filter query parameter family](https://jsonapi.org/recommendations/#filtering).\
\ Refer to the [Person API Documentation](https://kb.wisc.edu/uw-apis/158404)\
\ for more information. Filter `people` resources by `officeAddress`."
schema:
type: "string"
nullable: true
- name: "filter[officePhoneNumber]"
in: "query"
required: false
description: "Filter results using the [filter query parameter family](https://jsonapi.org/recommendations/#filtering).\
\ Refer to the [Person API Documentation](https://kb.wisc.edu/uw-apis/158404)\
\ for more information. Filter `people` resources by `officePhoneNumber`."
schema:
type: "string"
nullable: true
- name: "filter[dateOfBirth]"
in: "query"
required: false
description: "Filter results using the [filter query parameter family](https://jsonapi.org/recommendations/#filtering).\
\ Refer to the [Person API Documentation](https://kb.wisc.edu/uw-apis/158404)\
\ for more information. Filter `people` resources by `dateOfBirth`."
schema:
type: "string"
format: "date"
pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$"
- name: "filter[legalSex]"
in: "query"
required: false
description: "Filter results using the [filter query parameter family](https://jsonapi.org/recommendations/#filtering).\
\ Refer to the [Person API Documentation](https://kb.wisc.edu/uw-apis/158404)\
\ for more information. Filter `people` resources by `legalSex`."
schema:
type: "string"
enum:
- "Female"
- "Male"
- "Non-binary"
- "Other"
- "Unknown"
- name: "filter[deceased]"
in: "query"
required: false
description: "Filter results using the [filter query parameter family](https://jsonapi.org/recommendations/#filtering).\
\ Refer to the [Person API Documentation](https://kb.wisc.edu/uw-apis/158404)\
\ for more information. Filter `people` resources by `deceased`."
schema:
type: "boolean"
nullable: true
- name: "filter[continuousServiceDate]"
in: "query"
required: false
description: "Filter results using the [filter query parameter family](https://jsonapi.org/recommendations/#filtering).\
\ Refer to the [Person API Documentation](https://kb.wisc.edu/uw-apis/158404)\
\ for more information. Filter `people` resources by `continuousServiceDate`."
schema:
type: "string"
format: "date"
pattern: "^[1-9][0-9]{3}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$"
- name: "page[size]"
in: "query"
required: false
description: "Number of resources to return per page. Maximum 1000, default\
\ 100."
schema:
type: "integer"
minimum: 1
maximum: 1000
default: 100
- name: "page[after]"
in: "query"
required: false
description: "Cursor for the next page — the ID of the last resource on the\
\ previous page. Use the value returned in response `links.next`."
schema:
type: "string"
description: "An ephemeral identifier used only in the Person API to adhere\
\ to the [JSON:API specification](https://jsonapi.org/format/#document-resource-object-identification).\
\ This ID may change if a person is split into two people or two people\
\ are merged into one person. This ID is used for paginating results or\
\ following other links returned in the API response. This ID should not\
\ be stored in a consuming system. Concatenating parts of the URL to form\
\ a link is discouraged. Instead, use the fully-formed links returned\
\ in an API response."
- name: "page[before]"
in: "query"
required: false
description: "Cursor for the previous page — the ID of the first resource\
\ on the next page. Use the value returned in response `links.prev`."
schema:
type: "string"
description: "An ephemeral identifier used only in the Person API to adhere\
\ to the [JSON:API specification](https://jsonapi.org/format/#document-resource-object-identification).\
\ This ID may change if a person is split into two people or two people\
\ are merged into one person. This ID is used for paginating results or\
\ following other links returned in the API response. This ID should not\
\ be stored in a consuming system. Concatenating parts of the URL to form\
\ a link is discouraged. Instead, use the fully-formed links returned\
\ in an API response."
- name: "page[number]"
in: "query"
required: false
description: "Page number for offset pagination. Disabled by default — contact\
\ the developers to enable. Prefer cursor pagination (page[after] / page[before])\
\ for better performance."
schema:
type: "integer"
minimum: 1
responses:
"200":
description: "A collection of people"
content:
application/vnd.api+json:
schema:
type: "object"
required:
- "data"
- "links"
properties:
data:
description: "A collection of people"
type: "array"
items:
description: "A person."
type: "object"
required:
- "type"
- "id"
- "attributes"
- "relationships"
- "links"
- "meta"
properties:
type:
type: "string"
example: "people"
id:
type: "string"
description: "An ephemeral identifier used only in the Person\
\ API to adhere to the [JSON:API specification](https://jsonapi.org/format/#document-resource-object-identification).\
\ This ID may change if a person is split into two people\
\ or two people are merged into one person. This ID is\
\ used for paginating results or following other links\
\ returned in the API response. This ID should not be\
\ stored in a consuming system. Concatenating parts of\
\ the URL to form a link is discouraged. Instead, use\
\ the fully-formed links returned in an API response."
attributes:
type: "object"
required:
- "firstName"
- "lastName"
- "emailAddress"
- "officeAddress"
- "officePhoneNumber"
- "dateOfBirth"
- "legalSex"
- "deceased"
properties:
firstName:
type: "string"
example: "John"
description: "First name, derived from the person's\
\ current UW affiliations."
lastName:
type: "string"
example: "Smith"
description: "Last name, derived from the person's current\
\ UW affiliations."
emailAddress:
type: "string"
example: "john.smith@wisc.edu"
description: "The email address this person has designated\
\ as their primary, if set. Otherwise, their Campus\
\ Business Email, or other email derived from their\
\ current UW affiliations."
nullable: true
officeAddress:
type: "string"
description: "Primary work-related address derived from\
\ the person's current UW affiliations. May or may\
\ not be a fully-formed street address."
example: "1210 W. Dayton Street Madison, WI 53706-1613"
nullable: true
officePhoneNumber:
type: "string"
example: "608-262-1204"
description: "Primary work-related phone number derived\
\ from the person's current UW affiliations. May\
\ or may not be associated with the officeAddress."
nullable: true
dateOfBirth:
type: "string"
format: "date"
example: "1980-01-01"
description: "Date of birth. This is a sensitive attribute\
\ and is only available if the requesting application\
\ has the 'Sensitive Person Demographics' permission."
nullable: true
legalSex:
type: "string"
enum:
- "Female"
- "Male"
- "Non-binary"
- "Other"
- "Unknown"
example: "Male"
description: "Legal sex. This is a sensitive attribute\
\ and is only available if the requesting application\
\ has the 'Sensitive Person Demographics' permission."
deceased:
type: "boolean"
example: false
description: "Indicates whether or not this person is\
\ deceased. This is a sensitive attribute and is\
\ only available if the requesting application has\
\ the 'Sensitive Person Demographics' permission."
nullable: true
continuousServiceDate:
type: "string"
format: "date"
example: "2000-01-01"
description: "Adjusted date of civil service employment\
\ with the state of Wisconsin - required for a classified\
\ permanent job. The adjusted continuous service date\
\ is used, for example, to allocate annual vacation\
\ for leave accounting, and to rank employees for\
\ layoff provisions, including reinstatements, etc.\
\ Please see https://policy.wisc.edu/library/UW-5029\
\ for more details."
nullable: true
relationships:
type: "object"
required:
- "identifiers"
- "jobs"
- "names"
- "wiscard"
- "addresses"
- "phoneNumbers"
- "emailAddresses"
- "affiliations"
properties:
academicAppointments:
description: "A generic relationship object"
type: "object"
properties:
links:
type: "object"
properties:
related:
type: "string"
example: "https://api.wisc.edu/link/to/related/object"
data:
type: "array"
items:
type: "object"
properties:
type:
type: "string"
example: "sampleType"
id:
type: "string"
example: "sampleId"
affiliations:
description: "A generic relationship object"
type: "object"
properties:
links:
type: "object"
properties:
related:
type: "string"
example: "https://api.wisc.edu/link/to/related/object"
data:
type: "array"
items:
type: "object"
properties:
type:
type: "string"
example: "sampleType"
id:
type: "string"
example: "sampleId"
addresses:
description: "A generic relationship object"
type: "object"
properties:
links:
type: "object"
properties:
related:
type: "string"
example: "https://api.wisc.edu/link/to/related/object"
data:
type: "array"
items:
type: "object"
properties:
type:
type: "string"
example: "sampleType"
id:
type: "string"
example: "sampleId"
degrees:
description: "A generic relationship object"
type: "object"
properties:
links:
type: "object"
properties:
related:
type: "string"
example: "https://api.wisc.edu/link/to/related/object"
data:
type: "array"
items:
type: "object"
properties:
type:
type: "string"
example: "sampleType"
id:
type: "string"
example: "sampleId"
emailAddresses:
description: "A generic relationship object"
type: "object"
properties:
links:
type: "object"
properties:
related:
type: "string"
example: "https://api.wisc.edu/link/to/related/object"
data:
type: "array"
items:
type: "object"
properties:
type:
type: "string"
example: "sampleType"
id:
type: "string"
example: "sampleId"
identifiers:
description: "A generic relationship object"
type: "object"
properties:
links:
type: "object"
properties:
related:
type: "string"
example: "https://api.wisc.edu/link/to/related/object"
data:
type: "array"
items:
type: "object"
properties:
type:
type: "string"
example: "sampleType"
id:
type: "string"
example: "sampleId"
jobs:
description: "A generic relationship object"
type: "object"
properties:
links:
type: "object"
properties:
related:
type: "string"
example: "https://api.wisc.edu/link/to/related/object"
data:
type: "array"
items:
type: "object"
properties:
type:
type: "string"
example: "sampleType"
id:
type: "string"
example: "sampleId"
names:
description: "A generic relationship object"
type: "object"
properties:
links:
type: "object"
properties:
related:
type: "string"
example: "https://api.wisc.edu/link/to/related/object"
data:
type: "array"
items:
type: "object"
properties:
type:
type: "string"
example: "sampleType"
id:
type: "string"
example: "sampleId"
organizationStructures:
description: "A generic relationship object"
type: "object"
properties:
links:
type: "object"
properties:
related:
type: "string"
example: "https://api.wisc.edu/link/to/related/object"
data:
type: "array"
items:
type: "object"
properties:
type:
type: "string"
example: "sampleType"
id:
type: "string"
example: "sampleId"
phoneNumbers:
description: "A generic relationship object"
type: "object"
properties:
links:
type: "object"
properties:
related:
type: "string"
example: "https://api.wisc.edu/link/to/related/object"
data:
type: "array"
items:
type: "object"
properties:
type:
type: "string"
example: "sampleType"
id:
type: "string"
example: "sampleId"
socialSecurityNumbers:
description: "A generic relationship object"
type: "object"
properties:
links:
type: "object"
properties:
related:
type: "string"
example: "https://api.wisc.edu/link/to/related/object"
data:
type: "array"
items:
type: "object"
properties:
type:
type: "string"
example: "sampleType"
id:
type: "string"
example: "sampleId"
wiscard:
description: "A generic relationship object"
type: "object"
properties:
links:
type: "object"
properties:
related:
type: "string"
example: "https://api.wisc.edu/link/to/related/object"
data:
type: "object"
properties:
type:
type: "string"
example: "sampleType"
id:
type: "string"
example: "sampleId"
nullable: true
links:
description: "The link to access a resource itself"
type: "object"
properties:
self:
type: "string"
example: "https://api.wisc.edu/link/to/self"
meta:
type: "object"
required: []
properties:
ferpa:
type: "boolean"
example: false
description: "Indicates whether or not a student has\
\ elected FERPA coverage on one or more of their attributes.\
\ Please see https://registrar.wisc.edu/ferpa/ for\
\ more details about how to handle FERPA data."
ferpaAttributes:
type: "array"
items:
type: "string"
description: "Lists attributes on the base person resource\
\ that are covered by FERPA. Currently, only 'emailAddress'\
\ is eligible to be covered by FERPA."
privateAttributes:
# --- truncated at 32 KB (1751 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/university-of-wisconsin-madison/refs/heads/main/openapi/university-of-wisconsin-madison-person-api-openapi.yml