-
Jared Balkman authoredJared Balkman authored
Code owners
Assign users and groups as approvers for specific file changes. Learn more.
ER-22752.json 113.59 KiB
{
"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": "An API for interacting with person data at UW-Madison. Refer to the [Person API Documentation](/person-api) for more information about this API."
},
"externalDocs": {
"description": "Read more about JSON:API here",
"url": "https://jsonapi.org/"
},
"servers": [
{
"url": "https://doit.dev.api.wisc.edu"
}
],
"security": [
{
"OAuth2ClientCredentials": []
}
],
"paths": {
"/people": {
"get": {
"description": "Get a collection of people.",
"summary": "Get people.",
"operationId": "get_people",
"tags": [
"people"
],
"parameters": [
{
"$ref": "#/components/parameters/filter"
},
{
"$ref": "#/components/parameters/fields"
},
{
"$ref": "#/components/parameters/include"
},
{
"$ref": "#/components/parameters/page"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/people"
},
"400": {
"$ref": "#/components/responses/bad-request"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
} },
"/people/{id}": {
"get": {
"description": "Get a person. It is not recommended to manually build this URL or other URLs that contain path parameters, for example, by using concatenation. Instead, use the fully-qualified links returned in other resources to use this resource and other \"Get By ID\" resources.",
"summary": "Get a person.",
"operationId": "get_person",
"tags": [
"people"
],
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/include"
},
{
"$ref": "#/components/parameters/fields"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/people-id"
},
"400": {
"$ref": "#/components/responses/bad-request"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
}
},
"/people/{id}/identifiers": {
"get": {
"description": "Get identifiers for a person. This endpoint returns all current and past identifiers for the person..",
"summary": "Get identifiers.",
"operationId": "get_person_identifiers",
"tags": [
"identifiers"
],
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/fields"
},
{
"$ref": "#/components/parameters/filter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/identifiers"
},
"400": {
"$ref": "#/components/responses/bad-request" },
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
}
},
"/people/{id}/jobs": {
"get": {
"description": "Get jobs for a person.",
"summary": "Get jobs.",
"operationId": "get_person_jobs",
"tags": [
"jobs"
],
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/fields"
},
{
"$ref": "#/components/parameters/filter"
},
{
"$ref": "#/components/parameters/include"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/jobs"
},
"400": {
"$ref": "#/components/responses/bad-request"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
}
},
"/people/{id}/wiscard": {
"get": {
"description": "Details and metadata about a person's Wiscard.",
"summary": "Get Wiscard.", "operationId": "get_person_wiscard",
"tags": [
"wiscard"
],
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/fields"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/wiscard"
},
"400": {
"$ref": "#/components/responses/bad-request"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
}
},
"/people/{id}/names": {
"get": {
"description": "Get a person's names, split into separate resource objects depending on the type of name.",
"summary": "Get names.",
"operationId": "get_person_names",
"tags": [
"names"
],
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/fields"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/names"
},
"400": {
"$ref": "#/components/responses/bad-request"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": { "$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
},
"post": {
"description": "Please contact api@doit.wisc.edu if you need access to this endpoint. Create a name for a person. Only names with `nameType` of `nameInUse` can be created. Client-generated IDs are not supported.",
"summary": "Create a name.",
"operationId": "create_person_name",
"tags": [
"names"
],
"requestBody": {
"$ref": "#/components/requestBodies/newName"
},
"parameters": [
{
"$ref": "#/components/parameters/id"
}
],
"responses": {
"201": {
"$ref": "#/components/responses/singleName"
},
"202": {
"description": "Name created, but additional processing is needed for it to show in the API."
},
"400": {
"$ref": "#/components/responses/bad-request"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"403": {
"$ref": "#/components/responses/forbidden"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
}
},
"/people/{id}/names/{nameId}": {
"get": {
"description": "Get a name by ID.",
"summary": "Get a name.",
"operationId": "get_person_name",
"tags": [
"names"
],
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/nameId"
}
],
"responses": { "200": {
"$ref": "#/components/responses/singleName"
},
"400": {
"$ref": "#/components/responses/bad-request"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
},
"patch": {
"description": "Please contact api@doit.wisc.edu if you need access to this endpoint. Update a name for a person. Only names with `nameType` of `nameInUse` can be updated. Updating the ID is not allowed.",
"summary": "Update a name.",
"operationId": "update_person_name",
"tags": [
"names"
],
"requestBody": {
"$ref": "#/components/requestBodies/updatedName"
},
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/nameId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/singleName"
},
"202": {
"description": "Name updated, but additional processing is needed for the updates to show in the API."
},
"400": {
"$ref": "#/components/responses/bad-request"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"403": {
"$ref": "#/components/responses/forbidden"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
} },
"delete": {
"description": "Please contact api@doit.wisc.edu if you need access to this endpoint. Delete a name for a person. Only names with `nameType` of `nameInUse` can be deleted.",
"summary": "Delete a name.",
"operationId": "delete_person_name",
"tags": [
"names"
],
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/nameId"
}
],
"responses": {
"202": {
"description": "Name deleted, but additional processing is needed before the name won't appear in the API."
},
"204": {
"description": "Name deleted. Empty response."
},
"400": {
"$ref": "#/components/responses/bad-request"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"403": {
"$ref": "#/components/responses/forbidden"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
}
},
"/people/webhooks": {
"get": {
"description": "Get a collection of webhooks. Refer to the [Webhook Documentation](/person-api/webhooks) for more information.",
"summary": "Get webhooks.",
"operationId": "get_webhooks",
"tags": [
"webhooks"
],
"responses": {
"200": {
"$ref": "#/components/responses/webhooks"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error" }
}
},
"post": {
"description": "Create a webhook. A maximum of 1 webhook per Developer Portal application is allowed. Refer to the [Webhook Documentation](/person-api/webhooks) for more information.",
"summary": "Create a webhook.",
"operationId": "create_webhook",
"tags": [
"webhooks"
],
"requestBody": {
"$ref": "#/components/requestBodies/newWebhook"
},
"responses": {
"201": {
"$ref": "#/components/responses/createdWebhook"
},
"400": {
"$ref": "#/components/responses/bad-request"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"403": {
"$ref": "#/components/responses/forbidden"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"415": {
"$ref": "#/components/responses/unsupported-media-type"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
}
},
"/people/webhooks/{webhookId}": {
"get": {
"description": "Get a single webhook. Refer to the [Webhook Documentation](/person-api/webhooks) for more information.",
"summary": "Get a webhook.",
"operationId": "get_webhook",
"tags": [
"webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/webhookId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/singleWebhook"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
}, "500": {
"$ref": "#/components/responses/internal-server-error"
}
}
},
"patch": {
"description": "Update a webhook. Refer to the [Webhook Documentation](/person-api/webhooks) for more information.",
"summary": "Update a webhook.",
"operationId": "update_webhook",
"tags": [
"webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/webhookId"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/updatedWebhook"
},
"responses": {
"200": {
"$ref": "#/components/responses/singleWebhook"
},
"400": {
"$ref": "#/components/responses/bad-request"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"415": {
"$ref": "#/components/responses/unsupported-media-type"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
},
"delete": {
"description": "Delete a webhook. Refer to the [Webhook Documentation](/person-api/webhooks) for more information.",
"summary": "Delete a webhook.",
"operationId": "delete_webhook",
"tags": [
"webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/webhookId"
}
],
"responses": {
"204": {
"description": "Webhook deleted. Empty response."
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": { "$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
}
},
"/people/webhooks/{webhookId}/replay": {
"post": {
"description": "Replay events for a webhook. Refer to the [Webhook Documentation](/person-api/webhooks) for more information.",
"summary": "Replay events.",
"operationId": "replay_events_for_webhook",
"tags": [
"webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/webhookId"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/replayWebhook"
},
"responses": {
"202": {
"description": "Webhook replayed. Empty response."
},
"400": {
"$ref": "#/components/responses/bad-request"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
}
},
"/people/webhooks/{webhookId}/filters": {
"get": {
"description": "Get all filters for a webhook. Refer to the [Webhook Documentation](/person-api/webhooks) for more information.",
"summary": "Get all filters for a webhook.",
"operationId": "get_all_filters_for_webhook",
"tags": [
"webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/webhookId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/webhookFilters"
},
"401": { "$ref": "#/components/responses/unauthorized"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
},
"post": {
"description": "Create a filter for a webhook. Refer to the [Webhook Documentation](/person-api/webhooks) for more information.",
"summary": "Create a filter for a webhook.",
"operationId": "create_filter_for_webhook",
"tags": [
"webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/webhookId"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/newWebhookFilter"
},
"responses": {
"201": {
"$ref": "#/components/responses/singleWebhookFilter"
},
"400": {
"$ref": "#/components/responses/bad-request"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"415": {
"$ref": "#/components/responses/unsupported-media-type"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
}
},
"/people/webhooks/{webhookId}/filters/{filterId}": {
"get": {
"description": "Get a filter for a webhook. Refer to the [Webhook Documentation](/person-api/webhooks) for more information.",
"summary": "Get a filter for a webhook.",
"operationId": "get_filter_for_webhook",
"tags": [
"webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/webhookId"
},
{
"$ref": "#/components/parameters/filterId" }
],
"responses": {
"200": {
"$ref": "#/components/responses/singleWebhookFilter"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
},
"patch": {
"description": "Update a filter for a webhook. Refer to the [Webhook Documentation](/person-api/webhooks) for more information.",
"summary": "Update a filter for a webhook.",
"operationId": "update_filter_for_webhook",
"tags": [
"webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/webhookId"
},
{
"$ref": "#/components/parameters/filterId"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/updateWebhookFilter"
},
"responses": {
"200": {
"$ref": "#/components/responses/singleWebhookFilter"
},
"400": {
"$ref": "#/components/responses/bad-request"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"415": {
"$ref": "#/components/responses/unsupported-media-type"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
},
"delete": {
"description": "Delete a filter for a webhook. Refer to the [Webhook Documentation](/person-api/webhooks) for more information.", "summary": "Delete a filter for a webhook.",
"operationId": "delete_filter_for_webhook",
"tags": [
"webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/webhookId"
},
{
"$ref": "#/components/parameters/filterId"
}
],
"responses": {
"204": {
"description": "Name deleted. Empty response."
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
}
},
"/people/webhooks/{webhookId}/relationshipFilters": {
"get": {
"description": "Get all relationship filters for a webhook. Refer to the [Webhook Documentation](/person-api/webhooks) for more information.",
"summary": "Get all relationship filters for a webhook.",
"operationId": "get_all_relationship_filters_for_webhook",
"tags": [
"webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/webhookId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/webhookRelationshipFilters"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
},
"post": {
"description": "Create a relationship filter for a webhook. Refer to the [Webhook Documentation](/person-api/webhooks) for more information.",
"summary": "Create a relationship filter for a webhook.",
"operationId": "create_relationship_filter_for_webhook", "tags": [
"webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/webhookId"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/newWebhookRelationshipFilter"
},
"responses": {
"201": {
"$ref": "#/components/responses/singleWebhookRelationshipFilter"
},
"400": {
"$ref": "#/components/responses/bad-request"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"415": {
"$ref": "#/components/responses/unsupported-media-type"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
}
},
"/people/webhooks/{webhookId}/relationshipFilters/{relationshipFilterId}": {
"get": {
"description": "Get a relationship filter for a webhook. Refer to the [Webhook Documentation](/person-api/webhooks) for more information.",
"summary": "Get a relationship filter for a webhook.",
"operationId": "get_relationship_filter_for_webhook",
"tags": [
"webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/webhookId"
},
{
"$ref": "#/components/parameters/relationshipFilterId"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/singleWebhookRelationshipFilter"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests" },
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
},
"patch": {
"description": "Update a relationship filter for a webhook. Refer to the [Webhook Documentation](/person-api/webhooks) for more information.",
"summary": "Update a relationship filter for a webhook.",
"operationId": "update_relationship_filter_for_webhook",
"tags": [
"webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/webhookId"
},
{
"$ref": "#/components/parameters/relationshipFilterId"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/updateWebhookRelationshipFilter"
},
"responses": {
"200": {
"$ref": "#/components/responses/singleWebhookRelationshipFilter"
},
"400": {
"$ref": "#/components/responses/bad-request"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"415": {
"$ref": "#/components/responses/unsupported-media-type"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
},
"delete": {
"description": "Delete a relationship filter for a webhook. Refer to the [Webhook Documentation](/person-api/webhooks) for more information.",
"summary": "Delete a relationship filter for a webhook.",
"operationId": "delete_relationship_filter_for_webhook",
"tags": [
"webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/webhookId"
},
{
"$ref": "#/components/parameters/relationshipFilterId"
}
],
"responses": {
"204": {
"description": "Webhook relationship filter deleted. Empty response."
}, "401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/not-found"
},
"406": {
"$ref": "#/components/responses/not-acceptable"
},
"429": {
"$ref": "#/components/responses/too-many-requests"
},
"500": {
"$ref": "#/components/responses/internal-server-error"
}
}
}
}
},
"components": {
"securitySchemes": {
"OAuth2ClientCredentials": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "https://doit.dev.api.wisc.edu/oauth/token",
"scopes": {}
}
}
}
},
"schemas": {
"people": {
"description": "A person",
"type": "object",
"required": [
"type",
"id",
"attributes",
"relationships",
"links",
"meta"
],
"properties": {
"type": {
"type": "string",
"example": "people"
},
"id": {
"$ref": "#/components/schemas/personId"
},
"attributes": {
"type": "object",
"required": [
"firstName",
"lastName",
"emailAddress",
"officeAddress",
"officePhoneNumber"
],
"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."
},
"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"
},
"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."
}
}
},
"relationships": {
"type": "object",
"required": [
"identifiers",
"jobs",
"names",
"wiscard"
],
"properties": {
"identifiers": {
"$ref": "#/components/schemas/toManyRelationshipObject"
},
"jobs": {
"$ref": "#/components/schemas/toManyRelationshipObject"
},
"names": {
"$ref": "#/components/schemas/toManyRelationshipObject"
},
"wiscard": {
"$ref": "#/components/schemas/toOneRelationshipObject"
}
}
},
"links": {
"$ref": "#/components/schemas/selfLink"
},
"meta": {
"type": "object",
"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": "Not currently used."
},
"privateAttributes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Not currently used."
}
}
}
}
}, "identifierAttributes": {
"type": "object",
"required": [
"name",
"source",
"value",
"current"
],
"properties": {
"name": {
"type": "string",
"example": "pvi",
"description": "The name of this identifier. We currently support pvi, netId, emplId, and photoId."
},
"source": {
"type": "string",
"example": "IAM",
"description": "The source of this identifier. We have identifiers from IAM, HRS, SIS, and WISCARD."
},
"value": {
"type": "string",
"example": "UW123A456"
},
"current": {
"description": "Property that indicates if this identifier is currently used.",
"type": "boolean",
"example": true
}
}
},
"identifiers": {
"description": "An identifier",
"type": "object",
"required": [
"type",
"id",
"attributes",
"relationships"
],
"properties": {
"type": {
"type": "string",
"example": "identifiers"
},
"id": {
"$ref": "#/components/schemas/genericId"
},
"attributes": {
"$ref": "#/components/schemas/identifierAttributes"
},
"relationships": {
"type": "object",
"properties": {
"person": {
"$ref": "#/components/schemas/toOneRelationshipObject"
}
}
}
}
},
"jobs": {
"description": "A job",
"type": "object",
"required": [
"type",
"id",
"attributes",
"relationships"
],
"properties": { "type": {
"type": "string",
"example": "jobs"
},
"id": {
"$ref": "#/components/schemas/genericId"
},
"attributes": {
"type": "object",
"required": [
"title",
"division",
"divisionCode",
"departmentUnit",
"beginDate",
"endDate",
"effectiveDate",
"fullTimeEquivalent",
"payBasis",
"employeeCategoryCode",
"employeeCategory",
"jobCode",
"businessTitle",
"position",
"current"
],
"properties": {
"title": {
"type": "string",
"example": "Software Eng/Developer I",
"description": "Title of the person's position at this job."
},
"division": {
"type": "string",
"example": "INFORMATION TECHNOLOGY",
"description": "High level organizational unit where the job is located."
},
"divisionCode": {
"type": "string",
"example": "A067040",
"description": "Code for the location of the job."
},
"departmentUnit": {
"type": "string",
"example": "L&S/COMPUTER SCI/COMP SCI",
"description": "Organization path where the job is located."
},
"beginDate": {
"type": "string",
"format": "date",
"example": "2018-01-01",
"description": "The date the job began."
},
"endDate": {
"type": "string",
"format": "date",
"example": "2025-01-01",
"description": "The date the job ended."
},
"effectiveDate": {
"type": "string",
"format": "date",
"example": "2018-01-01",
"description": "The date the newest action on this job is effective."
},
"fullTimeEquivalent": {
"type": "string",
"example": "0.5",
"description": "The full time equivalency of the job."
}, "payBasis": {
"type": "string",
"enum": [
"Academic",
"Annual",
"Hourly",
"Lump",
"No Pay Basis",
"Summer Service",
"Summer Session",
"Unknown"
],
"example": "Annual",
"description": "The pay basis for this position."
},
"employeeCategoryCode": {
"type": "string",
"example": "AS",
"description": "Unique identifier for an employee category."
},
"employeeCategory": {
"type": "string",
"example": "Academic Staff",
"description": "See this document for information on this field: https://kb.wisc.edu/ohr/policies/page.php?id=53496"
},
"jobCode": {
"type": "string",
"example": "IT002",
"description": "Unique identifier for the job title."
},
"businessTitle": {
"type": "string",
"example": "Software Engineer/Developer",
"description": "Business title of the person's position at this job."
},
"position": {
"type": "string",
"example": "00123456-1",
"description": "An identifier to be used to uniquely identify a job for a person. This is a concatenation of the position and job record from Peoplesoft HRS, separated by a hyphen '-' (without quotes). It is not recommended to parse this value, but instead use it as an opaque identifier."
},
"current": {
"type": "boolean",
"example": true,
"description": "Property that indicates if this job is current."
}
}
},
"relationships": {
"type": "object",
"required": [
"person",
"supervisor"
],
"properties": {
"person": {
"$ref": "#/components/schemas/toOneRelationshipObject"
},
"supervisor": {
"description": "The supervisor for the job. If the job reports to a position that has 0 or greater than 2 people occupying it, this relationship is empty. If the job reports to a position occupied by 2 people, this relationship points to the person with the most recently entered job.",
"type": "object",
"properties": {
"links": {
"type": "object",
"properties": {
"related": {
"type": "string",
"example": "https://api.wisc.edu/people/123"
}
}
}, "data": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "people"
},
"id": {
"type": "string",
"example": "123"
}
}
}
}
}
}
}
}
},
"wiscard": {
"description": "Details and metadata from someone's Wiscard.",
"type": "object",
"required": [
"type",
"id",
"attributes",
"relationships"
],
"properties": {
"type": {
"type": "string",
"example": "wiscard"
},
"id": {
"$ref": "#/components/schemas/genericId"
},
"attributes": {
"type": "object",
"required": [
"wiscardId",
"expirationDate",
"issueCode"
],
"properties": {
"wiscardId": {
"description": "The ID number printed on this Wiscard.",
"type": "string",
"example": "123213213"
},
"expirationDate": {
"description": "The date this Wiscard will expire.",
"type": "string",
"format": "date",
"example": "2024-01-01"
},
"issueCode": {
"description": "The number of times a new Wiscard was issued for the holder of this Wiscard, starting with 0.",
"type": "string",
"example": "0"
}
}
},
"relationships": {
"type": "object",
"properties": {
"person": {
"$ref": "#/components/schemas/toOneRelationshipObject"
}
}
} }
},
"names": {
"description": "Details about the names used to refer to a person.",
"type": "object",
"required": [
"type",
"id",
"attributes",
"links",
"relationships"
],
"properties": {
"type": {
"type": "string",
"example": "names"
},
"id": {
"$ref": "#/components/schemas/genericId"
},
"attributes": {
"$ref": "#/components/schemas/nameAttributes"
},
"links": {
"$ref": "#/components/schemas/selfLink"
},
"relationships": {
"type": "object",
"properties": {
"person": {
"$ref": "#/components/schemas/toOneRelationshipObject"
}
}
}
}
},
"nameAttributes": {
"type": "object",
"required": [
"firstName",
"middleName",
"lastName",
"nameType",
"source"
],
"properties": {
"firstName": {
"description": "A first name for this person. For the `nameType` of `nameInUse`, this name can only contain A-Z and a-z characters, space characters, single quotes, and hyphens.",
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Za-z '-]*$",
"example": "Amy"
},
"middleName": {
"description": "A middle name for this person. For the `nameType` of `nameInUse`, this name can only contain A-Z and a-z characters, space characters, single quotes, and hyphens.",
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Za-z '-]*$",
"example": "Marie"
},
"lastName": {
"description": "A last name for this person. For the `nameType` of `nameInUse`, this field can only be edited to change capitalization, space characters, single quotes, and hyphens.",
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Za-z '-]*$",
"example": "Smith"
}, "nameType": {
"description": "The type of name for the person.",
"type": "string",
"enum": [
"nameInUse",
"primary"
],
"example": "nameInUse"
},
"source": {
"description": "The source of the name.",
"type": "string",
"enum": [
"profile",
"IAM"
],
"example": "profile"
}
}
},
"errors": {
"description": "An error",
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 400
},
"title": {
"type": "string",
"example": "Error title"
},
"detail": {
"type": "string",
"example": "Additional details about the error"
},
"links": {
"type": "object"
},
"meta": {
"type": "object"
},
"source": {
"type": "object"
}
}
},
"selfLink": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"pagination": {
"description": "The links associated with a paginated collection",
"type": "object",
"properties": {
"prev": {
"description": "The previous page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[number]=4"
},
"next": {
"description": "The next page of data",
"type": "string", "format": "uri-reference",
"example": "https://api.wisc.edu/people?page[number]=6"
}
}
},
"toManyRelationshipObject": {
"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"
}
}
}
}
}
},
"toOneRelationshipObject": {
"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"
}
}
}
}
},
"resourceObject": {
"description": "A generic resource object",
"type": "object",
"properties": {
"type": {
"type": "string", "example": "sampleType"
},
"id": {
"type": "string",
"example": "sampleId"
},
"attributes": {
"type": "object",
"properties": {
"attribute1": {
"type": "string",
"example": "sampleStringAttribute"
},
"attribute2": {
"type": "number",
"example": 123
}
}
},
"relationships": {
"type": "object",
"properties": {
"relatedResource": {
"$ref": "#/components/schemas/toOneRelationshipObject"
}
}
},
"links": {
"$ref": "#/components/schemas/selfLink"
}
}
},
"personId": {
"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.",
"example": "12345"
},
"genericId": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"webhookAttributes": {
"type": "object",
"required": [
"url",
"expired"
],
"properties": {
"url": {
"type": "string",
"format": "url",
"example": "https://department.wisc.edu/person-api-webhook",
"description": "URL that accepts Person API webhook events. This URL must use HTTPS."
},
"token": {
"type": "string",
"readOnly": true,
"description": "A secret token sent with each webhook event. A server must verify this token when receiving a webhook from the Person API to ensure it is authenticate. This token is only returned when creating a webhook and cannot be set by the client. It cannot be retrieved again in future requests."
},
"expired": {
"type": "boolean",
"readOnly": false,
"description": "Indicates whether the webhook subscription has expired. This value can be set to false to un-expire a webhook but can not be set to true to expire it."
}
}
},
"webhookRequestAttributes": {
"type": "object",
"properties": { "url": {
"type": "string",
"format": "url",
"example": "https://department.wisc.edu/person-api-webhook",
"description": "URL that accepts Person API webhook events. This URL must use HTTPS."
},
"expired": {
"type": "boolean",
"example": false,
"description": "Indicates whether the webhook subscription has expired. This value can be set to false to un-expire a webhook but can not be set to true to expire it."
}
}
},
"webhooks": {
"description": "A webhook represents the configuration for an application to subscribe to events for the Person API. A webhook is an HTTP request that will be sent to a server when data changes about a person.",
"type": "object",
"required": [
"type",
"id",
"attributes",
"links",
"relationships"
],
"properties": {
"type": {
"type": "string",
"example": "webhooks"
},
"id": {
"$ref": "#/components/schemas/genericId"
},
"attributes": {
"$ref": "#/components/schemas/webhookAttributes"
},
"links": {
"$ref": "#/components/schemas/selfLink"
},
"relationships": {
"type": "object",
"required": [
"replay",
"webhookFilters",
"webhookRelationshipFilters"
],
"properties": {
"replay": {
"$ref": "#/components/schemas/toOneRelationshipObject"
},
"webhookFilters": {
"$ref": "#/components/schemas/toManyRelationshipObject"
},
"webhookRelationshipFilters": {
"$ref": "#/components/schemas/toManyRelationshipObject"
}
}
}
}
},
"replayWebhookRequestAttributes": {
"type": "object",
"required": [
"replayFromTime"
],
"properties": {
"replayFromTime": {
"type": "string",
"format": "date-time",
"example": "2019-01-01T00:00:00Z",
"description": "The time to start replaying events from. This is an ISO 8601 date and time with the following format : YYYY-MM-DDTHH:MM:SSZ. The time must be in UTC."
} }
},
"webhookFilterAttributes": {
"type": "object",
"required": [
"attribute",
"operator",
"values"
],
"properties": {
"attribute": {
"type": "string",
"example": "jobs.divisionCode",
"description": "A valid attribute or relationship attribute on the people resource."
},
"operator": {
"type": "string",
"example": "STARTS_WITH",
"description": "The comparison to be performed on the balues. Valid operators are - 'STARTS_WITH', 'ENDS_WITH', 'CONTAINS', or 'EQUALS'."
},
"values": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"A192",
"A193"
],
"description": "A list of values to compare against. Values are required and must be a list of upto 10 non-empty strings."
}
}
},
"webhookFilters": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "webhookFilters"
},
"id": {
"$ref": "#/components/schemas/genericId"
},
"attributes": {
"$ref": "#/components/schemas/webhookFilterAttributes"
},
"relationships": {
"type": "object",
"required": [
"webhook"
],
"properties": {
"webhook": {
"$ref": "#/components/schemas/toOneRelationshipObject"
}
}
},
"links": {
"$ref": "#/components/schemas/selfLink"
}
}
},
"webhookRelationshipFilterAttributes": {
"type": "object", "required": [
"relationship"
],
"properties": {
"relationship": {
"type": "string",
"example": "jobs",
"description": "A valid relationship on the people resource. If there are no changes to this relationship in a webhook event, the webhook event won't be sent to you."
}
}
},
"webhookRelationshipFilters": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "webhookRelationshipFilters"
},
"id": {
"$ref": "#/components/schemas/genericId"
},
"attributes": {
"$ref": "#/components/schemas/webhookRelationshipFilterAttributes"
},
"relationships": {
"type": "object",
"required": [
"webhook"
],
"properties": {
"webhook": {
"$ref": "#/components/schemas/toOneRelationshipObject"
}
}
},
"links": {
"$ref": "#/components/schemas/selfLink"
}
}
}
},
"requestBodies": {
"newName": {
"description": "A name request body.",
"required": true,
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"type",
"attributes"
],
"properties": {
"type": {
"type": "string",
"example": "names"
},
"attributes": {
"$ref": "#/components/schemas/nameAttributes"
} }
}
}
}
}
}
},
"updatedName": {
"description": "A name request body.",
"required": true,
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"type",
"id",
"attributes"
],
"properties": {
"type": {
"type": "string",
"example": "names"
},
"id": {
"$ref": "#/components/schemas/genericId"
},
"attributes": {
"$ref": "#/components/schemas/nameAttributes"
}
}
}
}
}
}
}
},
"newWebhook": {
"description": "A webhook request body.",
"required": true,
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"type",
"attributes"
],
"properties": {
"type": {
"type": "string",
"example": "webhooks"
},
"attributes": {
"$ref": "#/components/schemas/webhookRequestAttributes"
}
}
}
}
}
}
}
},
"updatedWebhook": { "description": "A webhook request body.",
"required": true,
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"type": {
"type": "string",
"example": "webhooks"
},
"id": {
"$ref": "#/components/schemas/genericId"
},
"attributes": {
"$ref": "#/components/schemas/webhookRequestAttributes"
}
}
}
}
}
}
}
},
"replayWebhook": {
"description": "A webhook replay request body.",
"required": true,
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"type",
"attributes"
],
"properties": {
"type": {
"type": "string",
"example": "replay"
},
"attributes": {
"$ref": "#/components/schemas/replayWebhookRequestAttributes"
}
}
}
}
}
}
}
},
"newWebhookFilter": {
"description": "A webhook filter request body.",
"required": true,
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object", "required": [
"type",
"attributes"
],
"properties": {
"type": {
"type": "string",
"example": "webhookFilters"
},
"attributes": {
"$ref": "#/components/schemas/webhookFilterAttributes"
}
}
}
}
}
}
}
},
"updateWebhookFilter": {
"description": "A webhook filter request body.",
"required": true,
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"example": "webhookFilters"
},
"id": {
"$ref": "#/components/schemas/genericId"
},
"attributes": {
"$ref": "#/components/schemas/webhookFilterAttributes"
}
}
}
}
}
}
}
},
"newWebhookRelationshipFilter": {
"description": "A webhook relationship filter request body.",
"required": true,
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"type",
"attributes"
],
"properties": {
"type": {
"type": "string",
"example": "webhookRelationshipFilters"
},
"attributes": { "$ref": "#/components/schemas/webhookRelationshipFilterAttributes"
}
}
}
}
}
}
}
},
"updateWebhookRelationshipFilter": {
"description": "A webhook relationship filter request body.",
"required": true,
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"example": "webhookRelationshipFilters"
},
"id": {
"$ref": "#/components/schemas/genericId"
},
"attributes": {
"$ref": "#/components/schemas/webhookRelationshipFilterAttributes"
}
}
}
}
}
}
}
}
},
"responses": {
"people": {
"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": {
"$ref": "#/components/schemas/people"
}
},
"links": {
"description": "Self and pagination links",
"allOf": [
{
"$ref": "#/components/schemas/selfLink"
},
{
"$ref": "#/components/schemas/pagination"
}
] },
"included": {
"description": "Included related resources",
"type": "array",
"items": {
"$ref": "#/components/schemas/resourceObject"
}
}
}
},
"examples": {
"example-people": {
"value": {
"data": [
{
"attributes": {
"emailAddress": "john.smith@wisc.edu",
"firstName": "John",
"lastName": "Smith",
"officeAddress": "1210 W Dayton St, Madison, WI 53706",
"officePhoneNumber": "608-555-1234"
},
"id": "100",
"links": {
"self": "https://api.wisc.edu/people/100"
},
"meta": {
"ferpa": false,
"ferpaAttributes": [],
"privateAttributes": []
},
"relationships": {
"identifiers": {
"data": [
{
"id": "100",
"type": "identifiers"
}
],
"links": {
"related": "https://api.wisc.edu/people/100/identifiers"
}
},
"jobs": {
"data": [
{
"id": "100",
"type": "jobs"
}
],
"links": {
"related": "https://api.wisc.edu/people/100/jobs"
}
},
"names": {
"data": [
{
"id": "100",
"type": "names"
}
],
"links": {
"related": "https://api.wisc.edu/people/100/names"
}
},
"wiscard": {
"data": {
"id": "100",
"type": "wiscard"
}, "links": {
"related": "https://api.wisc.edu/people/100/wiscard"
}
}
},
"type": "people"
}
],
"links": {
"self": "https://api.wisc.edu/people"
}
}
}
}
}
}
},
"people-id": {
"description": "A single person",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"$ref": "#/components/schemas/people"
},
"links": {
"$ref": "#/components/schemas/selfLink"
},
"included": {
"description": "Included related resources",
"type": "array",
"items": {
"$ref": "#/components/schemas/resourceObject"
}
}
}
},
"examples": {
"example-people": {
"value": {
"data": {
"attributes": {
"emailAddress": "john.smith@wisc.edu",
"firstName": "John",
"lastName": "Smith",
"officeAddress": "1210 W Dayton St, Madison, WI 53706",
"officePhoneNumber": "608-555-1234"
},
"id": "100",
"links": {
"self": "https://api.wisc.edu/people/100"
},
"meta": {
"ferpa": false
},
"relationships": {
"identifiers": {
"data": [
{
"id": "100",
"type": "identifiers"
}
],
"links": { "related": "https://api.wisc.edu/people/100/identifiers"
}
},
"jobs": {
"data": [
{
"id": "100",
"type": "jobs"
}
],
"links": {
"related": "https://api.wisc.edu/people/100/jobs"
}
},
"names": {
"data": [
{
"id": "100",
"type": "names"
}
],
"links": {
"related": "https://api.wisc.edu/people/100/names"
}
},
"wiscard": {
"data": {
"id": "100",
"type": "wiscard"
},
"links": {
"related": "https://api.wisc.edu/people/100/wiscard"
}
}
},
"type": "people"
},
"links": {
"self": "https://api.wisc.edu/people"
}
}
}
}
}
}
},
"identifiers": {
"description": "A collection of identifiers. These may be: `pvi` (Publicly Visible Identifier, a unique value from DoIT Identity and Access Management), `netId` (username for the NetID Login Service), `photoId` (from a person's Wiscard), or `emplId` (from Human Resources System - HRS - for employees, or from Student Information System - SIS -for students).",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"description": "A collection of identifiers",
"type": "array",
"items": {
"$ref": "#/components/schemas/identifiers"
}
},
"links": {
"$ref": "#/components/schemas/selfLink"
}
}
},
"examples": { "example-identifiers-current": {
"value": {
"data": [
{
"attributes": {
"name": "pvi",
"source": "IAM",
"value": "UW123A456",
"current": true
},
"id": "100",
"relationships": {
"person": {
"data": {
"id": "100",
"type": "people"
},
"links": {
"related": "https://api.wisc.edu/people/100"
}
}
},
"type": "identifiers"
}
],
"links": {
"self": "https://api.wisc.edu/people/100/identifiers"
}
}
},
"example-identifier-historical": {
"value": {
"data": [
{
"attributes": {
"name": "pvi",
"source": "IAM",
"value": "UW123A123",
"current": false
},
"id": "100",
"relationships": {
"person": {
"data": {
"id": "100",
"type": "people"
},
"links": {
"related": "https://api.wisc.edu/people/100"
}
}
},
"type": "identifiers"
}
],
"links": {
"self": "https://api.wisc.edu/people/100/identifiers"
}
}
}
}
}
}
},
"jobs": {
"description": "A collection of jobs",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object", "required": [
"data",
"links"
],
"properties": {
"data": {
"description": "A collection of jobs",
"type": "array",
"items": {
"$ref": "#/components/schemas/jobs"
}
},
"links": {
"$ref": "#/components/schemas/selfLink"
},
"included": {
"description": "Included related resources",
"type": "array",
"items": {
"$ref": "#/components/schemas/resourceObject"
}
}
}
},
"examples": {
"example-jobs": {
"value": {
"data": [
{
"attributes": {
"departmentUnit": "DOIT/AIS/ENTERPRISE INTEGRAT",
"division": "INFORMATION TECHNOLOGY",
"divisionCode": "A067040",
"title": "Product Manager",
"beginDate": "2020-01-01",
"endDate": "2080-01-01",
"effectiveDate": "2020-01-01",
"fullTimeEquivalent": "1",
"payBasis": "Annual",
"employeeCategory": "Academic Staff",
"employeeCategoryCode": "AS",
"jobCode": "IT002",
"businessTitle": "Department Product Manager",
"position": "00123456-1",
"current": true
},
"id": "100",
"relationships": {
"person": {
"data": {
"id": "100",
"type": "people"
},
"links": {
"related": "https://api.wisc.edu/people/100"
}
},
"supervisor": {
"data": {
"id": "200",
"type": "people"
},
"links": {
"related": "https://api.wisc.edu/people/200"
}
}
},
"type": "jobs"
}
], "links": {
"self": "https://api.wisc.edu/people/100/jobs"
}
}
}
}
}
}
},
"wiscard": {
"description": "Details and metadata about a person's Wiscard.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"links"
],
"properties": {
"data": {
"$ref": "#/components/schemas/wiscard"
},
"links": {
"$ref": "#/components/schemas/selfLink"
},
"included": {
"description": "Included related resources",
"type": "array",
"items": {
"$ref": "#/components/schemas/resourceObject"
}
}
}
},
"examples": {
"example-wiscard": {
"value": {
"data": {
"attributes": {
"wiscardId": "1234567890",
"issueCode": "0",
"expirationDate": "2122-07-01"
},
"id": "100",
"relationships": {
"person": {
"data": {
"id": "100",
"type": "people"
},
"links": {
"related": "https://api.wisc.edu/people/100"
}
}
},
"type": "wiscard"
},
"links": {
"self": "https://api.wisc.edu/people/100/wiscard"
}
}
}
}
}
}
},
"names": {
"description": "A collection of names.",
"content": {
"application/vnd.api+json": { "schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"description": "A collection of names",
"type": "array",
"items": {
"$ref": "#/components/schemas/names"
}
},
"links": {
"$ref": "#/components/schemas/selfLink"
}
}
},
"examples": {
"example-names": {
"value": {
"data": [
{
"attributes": {
"firstName": "Amy",
"middleName": "Marie",
"lastName": "Smith",
"nameType": "nameInUse",
"source": "profile"
},
"id": "100",
"relationships": {
"person": {
"data": {
"id": "100",
"type": "people"
},
"links": {
"related": "https://api.wisc.edu/people/100"
}
}
},
"type": "names",
"links": {
"self": "https://api.wisc.edu/people/100/names/200"
}
}
],
"links": {
"self": "https://api.wisc.edu/people/100/names"
}
}
}
}
}
}
},
"singleName": {
"description": "A single name.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": { "$ref": "#/components/schemas/names"
},
"links": {
"$ref": "#/components/schemas/selfLink"
}
}
},
"examples": {
"example-names": {
"value": {
"data": {
"attributes": {
"firstName": "Amy",
"middleName": "Marie",
"lastName": "Smith",
"nameType": "nameInUse",
"source": "profile"
},
"id": "100",
"relationships": {
"person": {
"data": {
"id": "100",
"type": "people"
},
"links": {
"related": "https://api.wisc.edu/people/100"
}
}
},
"type": "names",
"links": {
"self": "https://api.wisc.edu/people/100/names/200"
}
},
"links": {
"self": "https://api.wisc.edu/people/100/names/100"
}
}
}
}
}
}
},
"webhooks": {
"description": "A collection of webhooks.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"description": "A collection of webhooks.",
"type": "array",
"items": {
"$ref": "#/components/schemas/webhooks"
}
},
"links": {
"$ref": "#/components/schemas/selfLink"
}
}
},
"examples": {
"example-webhooks": {
"value": { "data": [
{
"attributes": {
"url": "https://department.wisc.edu/person-api-webhook",
"expired": false
},
"id": "100",
"links": {
"self": "https://api.wisc.edu/people/webhooks/100"
},
"type": "webhooks",
"relationships": {
"replay": {
"links": {
"related": "https://api.wisc.edu/people/webhooks/100/replay"
}
},
"webhookFilters": {
"data": [],
"links": {
"related": "https://api.wisc.edu/people/webhooks/100/filters"
}
},
"webhookRelationshipFilters": {
"data": [],
"links": {
"related": "https://api.wisc.edu/people/webhooks/100/relationshipFilters"
}
}
}
}
],
"links": {
"self": "https://api.wisc.edu/people/webhooks"
}
}
}
}
}
}
},
"singleWebhook": {
"description": "A single webhook.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"$ref": "#/components/schemas/webhooks"
},
"links": {
"$ref": "#/components/schemas/selfLink"
}
}
},
"examples": {
"example-webhook": {
"value": {
"data": {
"attributes": {
"url": "https://department.wisc.edu/person-api-webhook",
"expired": false
},
"id": "100",
"links": { "self": "https://api.wisc.edu/people/webhooks/100"
},
"type": "webhooks",
"relationships": {
"replay": {
"links": {
"related": "https://api.wisc.edu/people/webhooks/100/replay"
}
},
"webhookFilters": {
"data": [],
"links": {
"related": "https://api.wisc.edu/people/webhooks/100/filters"
}
},
"webhookRelationshipFilters": {
"data": [],
"links": {
"related": "https://api.wisc.edu/people/webhooks/100/relationshipFilters"
}
}
}
},
"links": {
"self": "https://api.wisc.edu/people/webhooks/100"
}
}
}
}
}
}
},
"createdWebhook": {
"description": "A single just created webhook.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"$ref": "#/components/schemas/webhooks"
},
"links": {
"$ref": "#/components/schemas/selfLink"
}
}
},
"examples": {
"example-webhook": {
"value": {
"data": {
"attributes": {
"url": "https://department.wisc.edu/person-api-webhook",
"token": "16f6f440-7317-41f2-9239-6207519b3ad0",
"expired": false
},
"id": "100",
"links": {
"self": "https://api.wisc.edu/people/webhooks/100"
},
"type": "webhooks",
"relationships": {
"replay": {
"links": {
"related": "https://api.wisc.edu/people/webhooks/100/replay"
} },
"webhookFilters": {
"data": [],
"links": {
"related": "https://api.wisc.edu/people/webhooks/100/filters"
}
},
"webhookRelationshipFilters": {
"data": [],
"links": {
"related": "https://api.wisc.edu/people/webhooks/100/relationshipFilters"
}
}
}
},
"links": {
"self": "https://api.wisc.edu/people/webhooks/100"
}
}
}
}
}
}
},
"webhookFilters": {
"description": "A collection of webhook filters.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"description": "A collection of webhook filters.",
"type": "array",
"items": {
"$ref": "#/components/schemas/webhookFilters"
}
},
"links": {
"$ref": "#/components/schemas/selfLink"
}
}
},
"examples": {
"example-webhookFilters": {
"value": {
"data": [
{
"attributes": {
"attribute": "firstName",
"operator": "STARTS_WITH",
"values": [
"Ben",
"Ber",
"Bel",
"Bes"
]
},
"id": "123",
"links": {
"self": "https://api.wisc.edu/people/webhooks/100/filters/123"
},
"relationships": {
"webhook": {
"data": {
"id": "100", "type": "webhooks"
},
"links": {
"related": "https://api.wisc.edu/people/webhooks/100"
}
}
},
"type": "webhookFilters"
}
],
"links": {
"self": "https://api.wisc.edu/people/webhooks/100/filters"
}
}
}
}
}
}
},
"singleWebhookFilter": {
"description": "A single webhook filter.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"$ref": "#/components/schemas/webhookFilters"
},
"links": {
"$ref": "#/components/schemas/selfLink"
}
}
},
"examples": {
"example-webhookFilter": {
"value": {
"data": {
"attributes": {
"attribute": "firstName",
"operator": "STARTS_WITH",
"values": [
"Ben",
"Ber",
"Bel",
"Bes"
]
},
"id": "123",
"links": {
"self": "https://api.wisc.edu/people/webhooks/100/filters/123"
},
"relationships": {
"webhook": {
"data": {
"id": "100",
"type": "webhooks"
},
"links": {
"related": "https://api.wisc.edu/people/webhooks/100"
}
}
},
"type": "webhookFilters"
},
"links": { "self": "https://api.wisc.edu/people/webhooks/100/filters"
}
}
}
}
}
}
},
"webhookRelationshipFilters": {
"description": "A collection of webhook relationship filters.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"description": "A collection of webhook filters.",
"type": "array",
"items": {
"$ref": "#/components/schemas/webhookRelationshipFilters"
}
},
"links": {
"$ref": "#/components/schemas/selfLink"
}
}
},
"examples": {
"example-webhookRelationshipFilters": {
"value": {
"data": [
{
"attributes": {
"relationship": "identifiers"
},
"id": "123",
"links": {
"self": "https://api.wisc.edu/people/webhooks/100/relationshipFilters/123"
},
"relationships": {
"webhook": {
"data": {
"id": "100",
"type": "webhooks"
},
"links": {
"related": "https://api.wisc.edu/people/webhooks/100"
}
}
},
"type": "webhookRelationshipFilters"
}
],
"links": {
"self": "https://api.wisc.edu/people/webhooks/100/relationshipFilters"
}
}
}
}
}
}
},
"singleWebhookRelationshipFilter": {
"description": "A single webhook relationship filter.",
"content": {
"application/vnd.api+json": { "schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"$ref": "#/components/schemas/webhookRelationshipFilters"
},
"links": {
"$ref": "#/components/schemas/selfLink"
}
}
},
"examples": {
"example-webhookFilter": {
"value": {
"data": {
"attributes": {
"relationship": "identifiers"
},
"id": "123",
"links": {
"self": "https://api.wisc.edu/people/webhooks/100/relationshipFilters/123"
},
"relationships": {
"webhook": {
"data": {
"id": "100",
"type": "webhooks"
},
"links": {
"related": "https://api.wisc.edu/people/webhooks/100"
}
}
},
"type": "webhookRelationshipFilters"
},
"links": {
"self": "https://api.wisc.edu/people/webhooks/100/relationshipFilters"
}
}
}
}
}
}
},
"not-found": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/errors"
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found", "detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"not-acceptable": {
"description": "Servers respond with a 406 Not Acceptable status code if a request’s Accept header contains the JSON:API media type and all instances of that media type are modified with media type parameters.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/errors"
}
}
}
},
"examples": {
"not-acceptable-example": {
"value": {
"errors": [
{
"status": 406,
"title": "Not Acceptable",
"detail": "Request's Accept header contained the JSON:API media type and all instances of that media type were modified with media type parameters."
}
]
}
}
}
}
}
},
"unsupported-media-type": {
"description": "Request includes a body but not the valid JSON API Content-Type header: application/vnd.api+json",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/errors"
}
}
}
},
"examples": {
"unsupported-media-type-example": {
"value": {
"errors": [
{
"status": 415,
"title": "Unsupported Media Type",
"detail": "Requests with a body must include the Content-Type header with a value of application/vnd.api+json"
}
]
}
}
}
}
} },
"forbidden": {
"description": "The API call is authenticated but the client isn't allowed to perform the requested operation. This can occur when trying to update a resource when granted read-only access.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/errors"
}
}
}
},
"examples": {
"name-update-example": {
"value": {
"errors": [
{
"status": 403,
"title": "Forbidden",
"detail": "Client is not allowed to create, update, or delete a person's name."
}
]
}
}
}
}
}
},
"too-many-requests": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/errors"
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"unauthorized": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": { "errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/errors"
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"internal-server-error": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/errors"
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
},
"bad-request": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/errors"
}
}
}
}, "examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
}
},
"parameters": {
"id": {
"name": "id",
"description": "ID of a person. This parameter should not be manually built/concatenated, but instead be used by following the fully-formed links returned in an API response. To get a person by an ID, use query parameters to search by a specific identifier. Example: /people?filter[identifiers.name]=netId&filter[identifiers.value]=bbadger",
"in": "path",
"example": "100",
"required": true,
"schema": {
"type": "object",
"properties": {
"personId": {
"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.",
"example": "12345"
}
}
}
},
"nameId": {
"name": "nameId",
"description": "ID of a name. This parameter should not be manually built/concatenated, but instead be used by following the fully-formed links returned in an API response.",
"in": "path",
"example": "101",
"required": true,
"schema": {
"type": "object",
"properties": {
"genericId": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
}
},
"webhookId": {
"name": "webhookId",
"description": "ID of a webhook. This parameter should not be manually built/concatenated, but instead be used by following the fully-formed links returned in an API response.",
"in": "path",
"example": "100",
"required": true,
"schema": {
"type": "object",
"properties": {
"genericId": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
}
},
"filterId": { "name": "filterId",
"description": "ID of a webhook filter. This parameter should not be manually built/concatenated, but instead be used by following the fully-formed links returned in an API response.",
"in": "path",
"example": "100",
"required": true,
"schema": {
"type": "object",
"properties": {
"genericId": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
}
},
"relationshipFilterId": {
"name": "relationshipFilterId",
"description": "ID of a webhook relationship filter. This parameter should not be manually built/concatenated, but instead be used by following the fully-formed links returned in an API response.",
"in": "path",
"example": "100",
"required": true,
"schema": {
"type": "object",
"properties": {
"genericId": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
}
},
"filter": {
"name": "filter",
"in": "query",
"description": "Filter results of query using the [filter query parameter family](https://jsonapi.org/recommendations/#filtering). Refer to the [Person API Documentation](/person-api/filter-query-parameter) for more information about the `filter` query param.",
"required": false,
"style": "deepObject",
"explode": true,
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"attribute": {
"type": "string",
"example": "firstName"
}
}
}
},
"include": {
"name": "include",
"in": "query",
"description": "[include related resources](https://jsonapi.org/format/#fetching-includes). The resources to include need to be direct relationships. Nested relationships are not supported. For example, `include=jobs,identifiers` is supported but `include=person.jobs` is not supported.",
"schema": {
"type": "string"
}
},
"fields": {
"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"
}
}
}
},
"page": {
"name": "page",
"in": "query",
"description": "Define options for pagination of responses. For example, `page[size]=5&page[after]=400&page[before]=800` will return a response with data about 5 people whose `id` value falls after `400` but before `800`. So `page[size]` determines the number of people resources in a response, `page[after]` is the ID of the person at the end of the previous page, `page[before]` is the ID of the person at the start of the next page.",
"required": false,
"style": "deepObject",
"explode": true,
"schema": {
"type": "object",
"properties": {
"size": {
"type": "integer",
"example": 50,
"description": "Size of page for paginated results."
},
"after": {
"$ref": "#/components/schemas/personId"
},
"before": {
"$ref": "#/components/schemas/personId"
}
}
}
}
}
}
}