{
"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."
},
"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.",
"summary": "Get people.",
"operationId": "get_people",
"tags": [
"people"
],
"parameters": [
{
"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"
}
}
}
},
{
"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 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"
}
},
{
"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. Offset pagination is also supported using `page[number]` parameter (example: `page[number]=4&page[size]=10`), but it is disabled by default. The `page[number]` determines the page to display. Offset pagination has significantly worse performance than cursor pagination, so it should only be used by applications that can't support cursor pagination. Contact the developers if you would like to enable it.",
"required": false,
"style": "deepObject",
"explode": true,
"schema": {
"type": "object",
"properties": {
"size": {
"type": "integer",
"example": 50,
"maximum": 1000,
"minimum": 1,
"default": 100,
"description": "Size of page for paginated results."
},
"after": {
"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"
},
"before": {
"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"
},
"number": {
"type": "integer",
"example": 1,
"minimum": 1,
"description": "Page number for paginated results. This parameter is disabled by default. Contact the developers if you would like to enable it."
}
}
}
}
],
"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.",
"example": "12345"
},
"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",
"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
}
}
},
"relationships": {
"type": "object",
"required": [
"identifiers",
"jobs",
"names",
"wiscard"
],
"properties": {
"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"
}
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"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",
"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."
}
}
}
}
}
},
"links": {
"description": "Self and pagination links",
"allOf": [
{
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
{
"description": "The links associated with a paginated collection",
"type": "object",
"properties": {
"self": {
"description": "The current page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[after]=6"
},
"prev": {
"description": "The previous page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[before]=7"
},
"next": {
"description": "The next page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[after]=8"
},
"first": {
"description": "Available when using offset pagination. The first page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[number]=1"
},
"last": {
"description": "Available when using offset pagination. The last page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[number]=10"
}
}
}
]
},
"meta": {
"type": "object",
"properties": {
"paging": {
"type": "object",
"properties": {
"totalPeople": {
"type": "integer",
"example": 100,
"description": "The total number of people available for the collection"
}
},
"example": 100,
"description": "The total number of people in the collection"
}
}
},
"included": {
"description": "Included related resources",
"type": "array",
"items": {
"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": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
},
"/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": [
{
"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": "700",
"required": true,
"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.",
"example": "12345"
}
},
{
"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"
}
},
{
"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"
}
}
}
}
],
"responses": {
"200": {
"description": "A single person",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"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.",
"example": "12345"
},
"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",
"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
}
}
},
"relationships": {
"type": "object",
"required": [
"identifiers",
"jobs",
"names",
"wiscard"
],
"properties": {
"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"
}
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"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",
"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."
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"included": {
"description": "Included related resources",
"type": "array",
"items": {
"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": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
},
"/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": [
{
"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": "700",
"required": true,
"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.",
"example": "12345"
}
},
{
"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": "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"
}
}
}
}
],
"responses": {
"200": {
"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). Identifiers also include `library patron Id`, `campusId` (from the Student Information System -SIS), and `predicted photo Id` as documented in this [KB article](https://kb.wisc.edu/iam/page.php?id=95753#toc12).",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"description": "A collection of identifiers",
"type": "array",
"items": {
"description": "An identifier",
"type": "object",
"required": [
"type",
"id",
"attributes",
"relationships"
],
"properties": {
"type": {
"type": "string",
"example": "identifiers"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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, libraryPatronId, campusId, predictedPhotoId, and photoId."
},
"source": {
"type": "string",
"example": "IAM",
"enum": [
"IAM",
"HRS",
"SIS",
"LIBRARY",
"WISCARD"
],
"description": "The source of this identifier."
},
"value": {
"type": "string",
"example": "UW123A456"
},
"current": {
"description": "Property that indicates if this identifier is currently used.",
"type": "boolean",
"example": true
}
}
},
"relationships": {
"type": "object",
"properties": {
"person": {
"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"
}
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
},
"/people/{id}/jobs": {
"get": {
"description": "Get jobs for a person.",
"summary": "Get jobs.",
"operationId": "get_person_jobs",
"tags": [
"jobs"
],
"parameters": [
{
"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": "700",
"required": true,
"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.",
"example": "12345"
}
},
{
"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": "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"
}
}
}
},
{
"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"
}
}
],
"responses": {
"200": {
"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": {
"description": "A job",
"type": "object",
"required": [
"type",
"id",
"attributes",
"relationships"
],
"properties": {
"type": {
"type": "string",
"example": "jobs"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"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.",
"nullable": true
},
"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": {
"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"
}
}
}
}
},
"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"
}
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"included": {
"description": "Included related resources",
"type": "array",
"items": {
"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": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
},
"/people/{id}/wiscard": {
"get": {
"description": "Details and metadata about a person's Wiscard.",
"summary": "Get Wiscard.",
"operationId": "get_person_wiscard",
"tags": [
"wiscard"
],
"parameters": [
{
"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": "700",
"required": true,
"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.",
"example": "12345"
}
},
{
"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"
}
}
}
}
],
"responses": {
"200": {
"description": "Details and metadata about a person's Wiscard.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"links"
],
"properties": {
"data": {
"description": "Details and metadata from someone's Wiscard.",
"type": "object",
"required": [
"type",
"id",
"attributes",
"relationships"
],
"properties": {
"type": {
"type": "string",
"example": "wiscard"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"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": {
"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"
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"included": {
"description": "Included related resources",
"type": "array",
"items": {
"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": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
},
"/people/{id}/names": {
"get": {
"description": "Get a person's names, split into separate resource objects depending on the type of name. Refer to the [Names Documentation](/person-api/names) for more information.",
"summary": "Get names.",
"operationId": "get_person_names",
"tags": [
"names"
],
"parameters": [
{
"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": "700",
"required": true,
"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.",
"example": "12345"
}
},
{
"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"
}
}
}
}
],
"responses": {
"200": {
"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": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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",
"nullable": true
},
"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"
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"properties": {
"person": {
"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"
}
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
},
"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. Refer to the [Names Documentation](/person-api/names) for more information.",
"summary": "Create a name.",
"operationId": "create_person_name",
"tags": [
"names"
],
"requestBody": {
"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": {
"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",
"nullable": true
},
"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"
}
}
}
}
}
}
}
}
}
},
"parameters": [
{
"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": "700",
"required": true,
"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.",
"example": "12345"
}
}
],
"responses": {
"201": {
"description": "A single name.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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",
"nullable": true
},
"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"
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"properties": {
"person": {
"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"
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"202": {
"description": "Name created, but additional processing is needed for it to show in the API."
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"403": {
"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": {
"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"
}
}
}
}
}
},
"examples": {
"name-update-example": {
"value": {
"errors": [
{
"status": 403,
"title": "Forbidden",
"detail": "Client is not allowed to create, update, or delete a person's name."
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
},
"/people/{id}/names/{nameId}": {
"get": {
"description": "Get a name by ID. Refer to the [Names Documentation](/person-api/names) for more information.",
"summary": "Get a name.",
"operationId": "get_person_name",
"tags": [
"names"
],
"parameters": [
{
"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": "700",
"required": true,
"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.",
"example": "12345"
}
},
{
"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": "710",
"required": true,
"schema": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"responses": {
"200": {
"description": "A single name.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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",
"nullable": true
},
"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"
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"properties": {
"person": {
"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"
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
},
"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. Refer to the [Names Documentation](/person-api/names) for more information.",
"summary": "Update a name.",
"operationId": "update_person_name",
"tags": [
"names"
],
"requestBody": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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",
"nullable": true
},
"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"
}
}
}
}
}
}
}
}
}
},
"parameters": [
{
"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": "700",
"required": true,
"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.",
"example": "12345"
}
},
{
"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": "710",
"required": true,
"schema": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"responses": {
"200": {
"description": "A single name.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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",
"nullable": true
},
"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"
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"properties": {
"person": {
"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"
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"202": {
"description": "Name updated, but additional processing is needed for the updates to show in the API."
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"403": {
"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": {
"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"
}
}
}
}
}
},
"examples": {
"name-update-example": {
"value": {
"errors": [
{
"status": 403,
"title": "Forbidden",
"detail": "Client is not allowed to create, update, or delete a person's name."
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
},
"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. Refer to the [Names Documentation](/person-api/names) for more information.",
"summary": "Delete a name.",
"operationId": "delete_person_name",
"tags": [
"names"
],
"parameters": [
{
"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": "700",
"required": true,
"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.",
"example": "12345"
}
},
{
"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": "710",
"required": true,
"schema": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"responses": {
"202": {
"description": "Name deleted, but additional processing is needed before the name will stop appearing in the API."
},
"204": {
"description": "Name deleted. Empty response."
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"403": {
"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": {
"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"
}
}
}
}
}
},
"examples": {
"name-update-example": {
"value": {
"errors": [
{
"status": 403,
"title": "Forbidden",
"detail": "Client is not allowed to create, update, or delete a person's name."
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
},
"/people/{id}/addresses": {
"get": {
"description": "Get a person's addresses, split into separate resource objects depending on the type and source of address.",
"summary": "Get addresses.",
"operationId": "get_person_addresses",
"tags": [
"addresses"
],
"parameters": [
{
"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": "700",
"required": true,
"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.",
"example": "12345"
}
},
{
"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"
}
}
}
}
],
"responses": {
"200": {
"description": "A collection of addresses.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"description": "A collection of addresses",
"type": "array",
"items": {
"description": "Details about the addresses associated with a person.",
"type": "object",
"required": [
"type",
"id",
"attributes",
"links",
"relationships"
],
"properties": {
"type": {
"type": "string",
"example": "addresses"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"required": [
"line1",
"line2",
"line3",
"line4",
"city",
"state",
"county",
"country",
"postalCode",
"source",
"addressType"
],
"properties": {
"line1": {
"description": "Line 1 of the address.",
"type": "string",
"example": "123 Main Street"
},
"line2": {
"description": "Line 2 of the address.",
"type": "string",
"example": "Apartment 1"
},
"line3": {
"description": "Line 3 of the address.",
"type": "string"
},
"line4": {
"description": "Line 4 of the address.",
"type": "string"
},
"city": {
"description": "The city associated with the address.",
"type": "string",
"example": "Madison"
},
"state": {
"description": "The state associated with the address.",
"type": "string",
"example": "WI"
},
"county": {
"description": "The county associated with the address.",
"type": "string",
"example": "Dane"
},
"country": {
"description": "The country associated with the address.",
"type": "string",
"example": "US"
},
"postalCode": {
"description": "The postal/zip code associated with the address.",
"type": "string",
"example": "53715"
},
"source": {
"description": "The source of the address.",
"type": "string",
"enum": [
"HRS",
"UW-Madison Special Populations",
"UW Hospital and Clinics",
"UW Medical Foundation"
],
"example": "HRS"
},
"addressType": {
"description": "The type of address.",
"type": "string",
"enum": [
"office"
],
"example": "office"
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"properties": {
"person": {
"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"
}
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"examples": {
"example-addresses": {
"value": {
"data": [
{
"attributes": {
"line1": "700 Regent Street",
"line2": "Unit 200",
"line3": null,
"line4": null,
"city": "Madison",
"state": "WI",
"county": "Dane",
"country": "US",
"postalCode": "53715",
"source": "HRS",
"addressType": "office"
},
"id": "100",
"relationships": {
"person": {
"data": {
"id": "100",
"type": "people"
},
"links": {
"related": "https://api.wisc.edu/people/100"
}
}
},
"type": "addresses"
}
],
"links": {
"self": "https://api.wisc.edu/people/100/addresses"
}
}
}
}
}
}
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
},
"/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": {
"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": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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."
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"required": [
"replay",
"webhookFilters",
"webhookRelationshipFilters"
],
"properties": {
"replay": {
"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"
}
}
}
}
},
"webhookFilters": {
"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"
}
}
}
}
}
},
"webhookRelationshipFilters": {
"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"
}
}
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
},
"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": {
"description": "A webhook request body.",
"required": true,
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"type",
"attributes"
],
"properties": {
"type": {
"type": "string",
"example": "webhooks"
},
"attributes": {
"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."
}
}
}
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "A single just created webhook.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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."
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"required": [
"replay",
"webhookFilters",
"webhookRelationshipFilters"
],
"properties": {
"replay": {
"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"
}
}
}
}
},
"webhookFilters": {
"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"
}
}
}
}
}
},
"webhookRelationshipFilters": {
"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"
}
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"403": {
"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": {
"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"
}
}
}
}
}
},
"examples": {
"name-update-example": {
"value": {
"errors": [
{
"status": 403,
"title": "Forbidden",
"detail": "Client is not allowed to create, update, or delete a person's name."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"415": {
"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": {
"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"
}
}
}
}
}
},
"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"
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
},
"/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": [
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"responses": {
"200": {
"description": "A single webhook.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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."
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"required": [
"replay",
"webhookFilters",
"webhookRelationshipFilters"
],
"properties": {
"replay": {
"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"
}
}
}
}
},
"webhookFilters": {
"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"
}
}
}
}
}
},
"webhookRelationshipFilters": {
"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"
}
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
},
"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": [
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"requestBody": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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."
}
}
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "A single webhook.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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."
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"required": [
"replay",
"webhookFilters",
"webhookRelationshipFilters"
],
"properties": {
"replay": {
"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"
}
}
}
}
},
"webhookFilters": {
"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"
}
}
}
}
}
},
"webhookRelationshipFilters": {
"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"
}
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"415": {
"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": {
"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"
}
}
}
}
}
},
"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"
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
},
"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": [
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"responses": {
"204": {
"description": "Webhook deleted. Empty response."
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
},
"/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": [
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"requestBody": {
"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": {
"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."
}
}
}
}
}
}
}
}
}
},
"responses": {
"202": {
"description": "Webhook replayed. Empty response."
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
},
"/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": [
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"responses": {
"200": {
"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": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "webhookFilters"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"relationships": {
"type": "object",
"required": [
"webhook"
],
"properties": {
"webhook": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
},
"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": [
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"requestBody": {
"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": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
}
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "A single webhook filter.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "webhookFilters"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"relationships": {
"type": "object",
"required": [
"webhook"
],
"properties": {
"webhook": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"415": {
"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": {
"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"
}
}
}
}
}
},
"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"
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
},
"/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": [
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
},
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"responses": {
"200": {
"description": "A single webhook filter.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "webhookFilters"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"relationships": {
"type": "object",
"required": [
"webhook"
],
"properties": {
"webhook": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
},
"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": [
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
},
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"requestBody": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "A single webhook filter.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "webhookFilters"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"relationships": {
"type": "object",
"required": [
"webhook"
],
"properties": {
"webhook": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"415": {
"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": {
"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"
}
}
}
}
}
},
"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"
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
},
"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": [
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
},
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"responses": {
"204": {
"description": "Name deleted. Empty response."
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
},
"/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": [
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"responses": {
"200": {
"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": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "webhookRelationshipFilters"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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 will not be sent to you."
}
}
},
"relationships": {
"type": "object",
"required": [
"webhook"
],
"properties": {
"webhook": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
},
"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": [
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"requestBody": {
"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": {
"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 will not be sent to you."
}
}
}
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "A single webhook relationship filter.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "webhookRelationshipFilters"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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 will not be sent to you."
}
}
},
"relationships": {
"type": "object",
"required": [
"webhook"
],
"properties": {
"webhook": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"415": {
"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": {
"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"
}
}
}
}
}
},
"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"
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
},
"/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": [
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
},
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"responses": {
"200": {
"description": "A single webhook relationship filter.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "webhookRelationshipFilters"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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 will not be sent to you."
}
}
},
"relationships": {
"type": "object",
"required": [
"webhook"
],
"properties": {
"webhook": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
},
"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": [
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
},
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"requestBody": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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 will not be sent to you."
}
}
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "A single webhook relationship filter.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "webhookRelationshipFilters"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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 will not be sent to you."
}
}
},
"relationships": {
"type": "object",
"required": [
"webhook"
],
"properties": {
"webhook": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"415": {
"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": {
"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"
}
}
}
}
}
},
"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"
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
},
"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": [
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
},
{
"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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"responses": {
"204": {
"description": "Webhook relationship filter deleted. Empty response."
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
},
"/people/exports": {
"get": {
"description": "Get a collection of exports. Refer to the [exports documentation](/person-api/exports) for more information.",
"summary": "Get exports.",
"operationId": "get_exports",
"tags": [
"exports"
],
"responses": {
"200": {
"description": "A collection of exports.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"description": "A collection of exports.",
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "exports"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"properties": {
"relationships": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"names",
"jobs"
],
"description": "Relationships to include in the exported data. By default, only the root person data will be included."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"description": "Filters to apply when generating the exported data."
},
"status": {
"type": "string",
"enum": [
"Pending",
"Completed",
"Deleted",
"Error"
],
"readOnly": true,
"example": "Pending",
"description": "Status of the exported data. If the status is Error, please contact api@doit.wisc.edu for further investigation."
},
"exportUrl": {
"type": "string",
"format": "url",
"readOnly": true,
"description": "URL of the exported data. This field will only contain the URL when the status of the export is \"Done\"."
},
"requestTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"example": "2024-01-01T00:00:00Z",
"description": "The time the export request was created."
},
"completionTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"example": "2024-01-01T00:05:00Z",
"description": "The time the export was done processing.",
"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"
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"examples": {
"example-exports": {
"value": {
"data": [
{
"attributes": {
"relationships": [
"names",
"jobs"
],
"filters": [
{
"attribute": "jobs.divisionCode",
"operator": "STARTS_WITH",
"values": [
"A192",
"A193"
]
}
],
"status": "Done",
"exportUrl": "https://example.com/person-export123.json?signature=456",
"requestTime": "2024-01-01T00:00:00Z",
"completionTime": "2024-01-01T00:05:00Z"
},
"id": "123",
"links": {
"self": "https://api.wisc.edu/people/exports/123"
},
"type": "exports"
}
],
"links": {
"self": "https://api.wisc.edu/people/exports"
}
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
},
"post": {
"description": "Create an export. Refer to the [exports documentation](/person-api/exports) for more information.",
"summary": "Create an export.",
"operationId": "create_export",
"tags": [
"exports"
],
"requestBody": {
"description": "An export request body. Only the attributes \"relationships\" and \"filters\" can be set in a request.",
"required": true,
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"example": "exports"
},
"attributes": {
"type": "object",
"properties": {
"relationships": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"names",
"jobs"
],
"description": "Relationships to include in the exported data. By default, only the root person data will be included."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"description": "Filters to apply when generating the exported data."
}
}
}
}
}
}
}
}
}
},
"responses": {
"202": {
"description": "A single export.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "exports"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"properties": {
"relationships": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"names",
"jobs"
],
"description": "Relationships to include in the exported data. By default, only the root person data will be included."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"description": "Filters to apply when generating the exported data."
},
"status": {
"type": "string",
"enum": [
"Pending",
"Completed",
"Deleted",
"Error"
],
"readOnly": true,
"example": "Pending",
"description": "Status of the exported data. If the status is Error, please contact api@doit.wisc.edu for further investigation."
},
"exportUrl": {
"type": "string",
"format": "url",
"readOnly": true,
"description": "URL of the exported data. This field will only contain the URL when the status of the export is \"Done\"."
},
"requestTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"example": "2024-01-01T00:00:00Z",
"description": "The time the export request was created."
},
"completionTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"example": "2024-01-01T00:05:00Z",
"description": "The time the export was done processing.",
"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"
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"examples": {
"example-export": {
"value": {
"data": {
"attributes": {
"relationships": [
"names",
"jobs"
],
"filters": [
{
"attribute": "jobs.divisionCode",
"operator": "STARTS_WITH",
"values": [
"A192",
"A193"
]
}
],
"status": "Pending",
"requestTime": "2024-01-01T00:00:00Z"
},
"id": "123",
"links": {
"self": "https://api.wisc.edu/people/exports/123"
},
"type": "exports"
},
"links": {
"self": "https://api.wisc.edu/people/exports/123"
}
}
}
}
}
}
},
"400": {
"description": "A bad request.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"status": 400,
"title": "Bad Request",
"detail": "Invalid properties in query parameters - resource type 'people' has no attribute 'invalid'."
}
]
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"403": {
"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": {
"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"
}
}
}
}
}
},
"examples": {
"name-update-example": {
"value": {
"errors": [
{
"status": 403,
"title": "Forbidden",
"detail": "Client is not allowed to create, update, or delete a person's name."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"415": {
"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": {
"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"
}
}
}
}
}
},
"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"
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
},
"/people/exports/{exportId}": {
"get": {
"description": "Get an export. This endpoint is meant to be checked on a repeated basis when waiting for an export to complete. Requests to this endpoint count towards the overall quota for an application. Refer to the [exports documentation](/person-api/exports) for more information.",
"summary": "Get an export.",
"operationId": "get_export",
"tags": [
"exports"
],
"parameters": [
{
"name": "exportId",
"description": "ID of an export. 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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"responses": {
"200": {
"description": "A single export.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "exports"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"properties": {
"relationships": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"names",
"jobs"
],
"description": "Relationships to include in the exported data. By default, only the root person data will be included."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"description": "Filters to apply when generating the exported data."
},
"status": {
"type": "string",
"enum": [
"Pending",
"Completed",
"Deleted",
"Error"
],
"readOnly": true,
"example": "Pending",
"description": "Status of the exported data. If the status is Error, please contact api@doit.wisc.edu for further investigation."
},
"exportUrl": {
"type": "string",
"format": "url",
"readOnly": true,
"description": "URL of the exported data. This field will only contain the URL when the status of the export is \"Done\"."
},
"requestTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"example": "2024-01-01T00:00:00Z",
"description": "The time the export request was created."
},
"completionTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"example": "2024-01-01T00:05:00Z",
"description": "The time the export was done processing.",
"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"
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"examples": {
"example-export": {
"value": {
"data": {
"attributes": {
"relationships": [
"names",
"jobs"
],
"filters": [
{
"attribute": "jobs.divisionCode",
"operator": "STARTS_WITH",
"values": [
"A192",
"A193"
]
}
],
"status": "Completed",
"exportUrl": "https://example.com/person-export123.json?signature=456",
"requestTime": "2024-01-01T00:00:00Z",
"completionTime": "2024-01-01T00:05:00Z"
},
"id": "123",
"links": {
"self": "https://api.wisc.edu/people/exports/123"
},
"type": "exports"
},
"links": {
"self": "https://api.wisc.edu/people/exports/123"
}
}
}
}
}
}
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
},
"delete": {
"description": "Delete an export. This deletes the export and the exported data. Refer to the [exports documentation](/person-api/exports) for more information.",
"summary": "Delete an export.",
"operationId": "delete_export",
"tags": [
"exports"
],
"parameters": [
{
"name": "exportId",
"description": "ID of an export. 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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
}
],
"responses": {
"204": {
"description": "Name deleted. Empty response."
},
"401": {
"description": "Incorrect or expired OAuth token.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"unauthorized-response": {
"value": {
"errors": [
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid OAuth authentication - InvalidAccessToken"
}
]
}
}
}
}
}
},
"404": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Requested resource not found."
}
]
}
}
}
}
}
},
"406": {
"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": {
"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"
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"429": {
"description": "The API quota has been exceeded.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 429,
"title": "Too Many Requests",
"detail": "The quota has been exceeded."
}
]
}
}
}
}
}
},
"500": {
"description": "An unexpected error.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"examples": {
"not-found-example": {
"value": {
"errors": [
{
"status": 500,
"title": "Internal Server Error",
"detail": "Something went wrong in the server-side."
}
]
}
}
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"OAuth2ClientCredentials": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "https://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": {
"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"
},
"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",
"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
}
}
},
"relationships": {
"type": "object",
"required": [
"identifiers",
"jobs",
"names",
"wiscard"
],
"properties": {
"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"
}
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"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",
"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, libraryPatronId, campusId, predictedPhotoId, and photoId."
},
"source": {
"type": "string",
"example": "IAM",
"enum": [
"IAM",
"HRS",
"SIS",
"LIBRARY",
"WISCARD"
],
"description": "The source of this identifier."
},
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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, libraryPatronId, campusId, predictedPhotoId, and photoId."
},
"source": {
"type": "string",
"example": "IAM",
"enum": [
"IAM",
"HRS",
"SIS",
"LIBRARY",
"WISCARD"
],
"description": "The source of this identifier."
},
"value": {
"type": "string",
"example": "UW123A456"
},
"current": {
"description": "Property that indicates if this identifier is currently used.",
"type": "boolean",
"example": true
}
}
},
"relationships": {
"type": "object",
"properties": {
"person": {
"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"
}
}
}
}
}
}
}
}
},
"jobs": {
"description": "A job",
"type": "object",
"required": [
"type",
"id",
"attributes",
"relationships"
],
"properties": {
"type": {
"type": "string",
"example": "jobs"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"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.",
"nullable": true
},
"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": {
"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"
}
}
}
}
},
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"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": {
"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"
}
}
}
}
}
}
}
}
},
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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",
"nullable": true
},
"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"
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"properties": {
"person": {
"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"
}
}
}
}
}
}
}
}
},
"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",
"nullable": true
},
"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"
}
}
},
"addresses": {
"description": "Details about the addresses associated with a person.",
"type": "object",
"required": [
"type",
"id",
"attributes",
"links",
"relationships"
],
"properties": {
"type": {
"type": "string",
"example": "addresses"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"required": [
"line1",
"line2",
"line3",
"line4",
"city",
"state",
"county",
"country",
"postalCode",
"source",
"addressType"
],
"properties": {
"line1": {
"description": "Line 1 of the address.",
"type": "string",
"example": "123 Main Street"
},
"line2": {
"description": "Line 2 of the address.",
"type": "string",
"example": "Apartment 1"
},
"line3": {
"description": "Line 3 of the address.",
"type": "string"
},
"line4": {
"description": "Line 4 of the address.",
"type": "string"
},
"city": {
"description": "The city associated with the address.",
"type": "string",
"example": "Madison"
},
"state": {
"description": "The state associated with the address.",
"type": "string",
"example": "WI"
},
"county": {
"description": "The county associated with the address.",
"type": "string",
"example": "Dane"
},
"country": {
"description": "The country associated with the address.",
"type": "string",
"example": "US"
},
"postalCode": {
"description": "The postal/zip code associated with the address.",
"type": "string",
"example": "53715"
},
"source": {
"description": "The source of the address.",
"type": "string",
"enum": [
"HRS",
"UW-Madison Special Populations",
"UW Hospital and Clinics",
"UW Medical Foundation"
],
"example": "HRS"
},
"addressType": {
"description": "The type of address.",
"type": "string",
"enum": [
"office"
],
"example": "office"
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"properties": {
"person": {
"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"
}
}
}
}
}
}
}
}
},
"addressAttributes": {
"type": "object",
"required": [
"line1",
"line2",
"line3",
"line4",
"city",
"state",
"county",
"country",
"postalCode",
"source",
"addressType"
],
"properties": {
"line1": {
"description": "Line 1 of the address.",
"type": "string",
"example": "123 Main Street"
},
"line2": {
"description": "Line 2 of the address.",
"type": "string",
"example": "Apartment 1"
},
"line3": {
"description": "Line 3 of the address.",
"type": "string"
},
"line4": {
"description": "Line 4 of the address.",
"type": "string"
},
"city": {
"description": "The city associated with the address.",
"type": "string",
"example": "Madison"
},
"state": {
"description": "The state associated with the address.",
"type": "string",
"example": "WI"
},
"county": {
"description": "The county associated with the address.",
"type": "string",
"example": "Dane"
},
"country": {
"description": "The country associated with the address.",
"type": "string",
"example": "US"
},
"postalCode": {
"description": "The postal/zip code associated with the address.",
"type": "string",
"example": "53715"
},
"source": {
"description": "The source of the address.",
"type": "string",
"enum": [
"HRS",
"UW-Madison Special Populations",
"UW Hospital and Clinics",
"UW Medical Foundation"
],
"example": "HRS"
},
"addressType": {
"description": "The type of address.",
"type": "string",
"enum": [
"office"
],
"example": "office"
}
}
},
"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": {
"self": {
"description": "The current page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[after]=6"
},
"prev": {
"description": "The previous page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[before]=7"
},
"next": {
"description": "The next page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[after]=8"
},
"first": {
"description": "Available when using offset pagination. The first page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[number]=1"
},
"last": {
"description": "Available when using offset pagination. The last page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[number]=10"
}
}
},
"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": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"personId": {
"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"
}
}
},
"genericId": {
"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."
}
}
},
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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."
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"required": [
"replay",
"webhookFilters",
"webhookRelationshipFilters"
],
"properties": {
"replay": {
"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"
}
}
}
}
},
"webhookFilters": {
"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"
}
}
}
}
}
},
"webhookRelationshipFilters": {
"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"
}
}
}
}
}
}
}
}
}
},
"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."
}
}
},
"requestFilterAttributes": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"webhookFilters": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "webhookFilters"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"relationships": {
"type": "object",
"required": [
"webhook"
],
"properties": {
"webhook": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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 will not be sent to you."
}
}
},
"webhookRelationshipFilters": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "webhookRelationshipFilters"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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 will not be sent to you."
}
}
},
"relationships": {
"type": "object",
"required": [
"webhook"
],
"properties": {
"webhook": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"exportAttributes": {
"type": "object",
"properties": {
"relationships": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"names",
"jobs"
],
"description": "Relationships to include in the exported data. By default, only the root person data will be included."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"description": "Filters to apply when generating the exported data."
},
"status": {
"type": "string",
"enum": [
"Pending",
"Completed",
"Deleted",
"Error"
],
"readOnly": true,
"example": "Pending",
"description": "Status of the exported data. If the status is Error, please contact api@doit.wisc.edu for further investigation."
},
"exportUrl": {
"type": "string",
"format": "url",
"readOnly": true,
"description": "URL of the exported data. This field will only contain the URL when the status of the export is \"Done\"."
},
"requestTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"example": "2024-01-01T00:00:00Z",
"description": "The time the export request was created."
},
"completionTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"example": "2024-01-01T00:05:00Z",
"description": "The time the export was done processing.",
"nullable": true
}
}
},
"exportRequestAttributes": {
"type": "object",
"properties": {
"relationships": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"names",
"jobs"
],
"description": "Relationships to include in the exported data. By default, only the root person data will be included."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"description": "Filters to apply when generating the exported data."
}
}
},
"export": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "exports"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"properties": {
"relationships": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"names",
"jobs"
],
"description": "Relationships to include in the exported data. By default, only the root person data will be included."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"description": "Filters to apply when generating the exported data."
},
"status": {
"type": "string",
"enum": [
"Pending",
"Completed",
"Deleted",
"Error"
],
"readOnly": true,
"example": "Pending",
"description": "Status of the exported data. If the status is Error, please contact api@doit.wisc.edu for further investigation."
},
"exportUrl": {
"type": "string",
"format": "url",
"readOnly": true,
"description": "URL of the exported data. This field will only contain the URL when the status of the export is \"Done\"."
},
"requestTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"example": "2024-01-01T00:00:00Z",
"description": "The time the export request was created."
},
"completionTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"example": "2024-01-01T00:05:00Z",
"description": "The time the export was done processing.",
"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"
}
}
}
}
}
},
"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": {
"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",
"nullable": true
},
"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"
}
}
}
}
}
}
}
}
}
},
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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",
"nullable": true
},
"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"
}
}
}
}
}
}
}
}
}
},
"newWebhook": {
"description": "A webhook request body.",
"required": true,
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"type",
"attributes"
],
"properties": {
"type": {
"type": "string",
"example": "webhooks"
},
"attributes": {
"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."
}
}
}
}
}
}
}
}
}
},
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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."
}
}
}
}
}
}
}
}
}
},
"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": {
"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."
}
}
}
}
}
}
}
}
}
},
"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": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
}
}
}
}
}
}
}
},
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
}
}
}
}
}
}
}
},
"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": {
"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 will not be sent to you."
}
}
}
}
}
}
}
}
}
},
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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 will not be sent to you."
}
}
}
}
}
}
}
}
}
},
"newExport": {
"description": "An export request body. Only the attributes \"relationships\" and \"filters\" can be set in a request.",
"required": true,
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"example": "exports"
},
"attributes": {
"type": "object",
"properties": {
"relationships": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"names",
"jobs"
],
"description": "Relationships to include in the exported data. By default, only the root person data will be included."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"description": "Filters to apply when generating the exported data."
}
}
}
}
}
}
}
}
}
}
},
"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": {
"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.",
"example": "12345"
},
"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",
"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
}
}
},
"relationships": {
"type": "object",
"required": [
"identifiers",
"jobs",
"names",
"wiscard"
],
"properties": {
"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"
}
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"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",
"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."
}
}
}
}
}
},
"links": {
"description": "Self and pagination links",
"allOf": [
{
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
{
"description": "The links associated with a paginated collection",
"type": "object",
"properties": {
"self": {
"description": "The current page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[after]=6"
},
"prev": {
"description": "The previous page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[before]=7"
},
"next": {
"description": "The next page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[after]=8"
},
"first": {
"description": "Available when using offset pagination. The first page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[number]=1"
},
"last": {
"description": "Available when using offset pagination. The last page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[number]=10"
}
}
}
]
},
"meta": {
"type": "object",
"properties": {
"paging": {
"type": "object",
"properties": {
"totalPeople": {
"type": "integer",
"example": 100,
"description": "The total number of people available for the collection"
}
},
"example": 100,
"description": "The total number of people in the collection"
}
}
},
"included": {
"description": "Included related resources",
"type": "array",
"items": {
"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": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
}
}
}
},
"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": {
"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.",
"example": "12345"
},
"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",
"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
}
}
},
"relationships": {
"type": "object",
"required": [
"identifiers",
"jobs",
"names",
"wiscard"
],
"properties": {
"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"
}
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"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",
"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."
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"included": {
"description": "Included related resources",
"type": "array",
"items": {
"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": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
}
}
}
},
"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). Identifiers also include `library patron Id`, `campusId` (from the Student Information System -SIS), and `predicted photo Id` as documented in this [KB article](https://kb.wisc.edu/iam/page.php?id=95753#toc12).",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"description": "A collection of identifiers",
"type": "array",
"items": {
"description": "An identifier",
"type": "object",
"required": [
"type",
"id",
"attributes",
"relationships"
],
"properties": {
"type": {
"type": "string",
"example": "identifiers"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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, libraryPatronId, campusId, predictedPhotoId, and photoId."
},
"source": {
"type": "string",
"example": "IAM",
"enum": [
"IAM",
"HRS",
"SIS",
"LIBRARY",
"WISCARD"
],
"description": "The source of this identifier."
},
"value": {
"type": "string",
"example": "UW123A456"
},
"current": {
"description": "Property that indicates if this identifier is currently used.",
"type": "boolean",
"example": true
}
}
},
"relationships": {
"type": "object",
"properties": {
"person": {
"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"
}
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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": {
"description": "A job",
"type": "object",
"required": [
"type",
"id",
"attributes",
"relationships"
],
"properties": {
"type": {
"type": "string",
"example": "jobs"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"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.",
"nullable": true
},
"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": {
"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"
}
}
}
}
},
"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"
}
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"included": {
"description": "Included related resources",
"type": "array",
"items": {
"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": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
}
}
}
},
"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": {
"description": "Details and metadata from someone's Wiscard.",
"type": "object",
"required": [
"type",
"id",
"attributes",
"relationships"
],
"properties": {
"type": {
"type": "string",
"example": "wiscard"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"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": {
"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"
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"included": {
"description": "Included related resources",
"type": "array",
"items": {
"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": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
}
}
}
},
"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": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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",
"nullable": true
},
"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"
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"properties": {
"person": {
"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"
}
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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",
"nullable": true
},
"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"
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"properties": {
"person": {
"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"
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"addresses": {
"description": "A collection of addresses.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"description": "A collection of addresses",
"type": "array",
"items": {
"description": "Details about the addresses associated with a person.",
"type": "object",
"required": [
"type",
"id",
"attributes",
"links",
"relationships"
],
"properties": {
"type": {
"type": "string",
"example": "addresses"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"required": [
"line1",
"line2",
"line3",
"line4",
"city",
"state",
"county",
"country",
"postalCode",
"source",
"addressType"
],
"properties": {
"line1": {
"description": "Line 1 of the address.",
"type": "string",
"example": "123 Main Street"
},
"line2": {
"description": "Line 2 of the address.",
"type": "string",
"example": "Apartment 1"
},
"line3": {
"description": "Line 3 of the address.",
"type": "string"
},
"line4": {
"description": "Line 4 of the address.",
"type": "string"
},
"city": {
"description": "The city associated with the address.",
"type": "string",
"example": "Madison"
},
"state": {
"description": "The state associated with the address.",
"type": "string",
"example": "WI"
},
"county": {
"description": "The county associated with the address.",
"type": "string",
"example": "Dane"
},
"country": {
"description": "The country associated with the address.",
"type": "string",
"example": "US"
},
"postalCode": {
"description": "The postal/zip code associated with the address.",
"type": "string",
"example": "53715"
},
"source": {
"description": "The source of the address.",
"type": "string",
"enum": [
"HRS",
"UW-Madison Special Populations",
"UW Hospital and Clinics",
"UW Medical Foundation"
],
"example": "HRS"
},
"addressType": {
"description": "The type of address.",
"type": "string",
"enum": [
"office"
],
"example": "office"
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"properties": {
"person": {
"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"
}
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"examples": {
"example-addresses": {
"value": {
"data": [
{
"attributes": {
"line1": "700 Regent Street",
"line2": "Unit 200",
"line3": null,
"line4": null,
"city": "Madison",
"state": "WI",
"county": "Dane",
"country": "US",
"postalCode": "53715",
"source": "HRS",
"addressType": "office"
},
"id": "100",
"relationships": {
"person": {
"data": {
"id": "100",
"type": "people"
},
"links": {
"related": "https://api.wisc.edu/people/100"
}
}
},
"type": "addresses"
}
],
"links": {
"self": "https://api.wisc.edu/people/100/addresses"
}
}
}
}
}
}
},
"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": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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."
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"required": [
"replay",
"webhookFilters",
"webhookRelationshipFilters"
],
"properties": {
"replay": {
"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"
}
}
}
}
},
"webhookFilters": {
"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"
}
}
}
}
}
},
"webhookRelationshipFilters": {
"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"
}
}
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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."
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"required": [
"replay",
"webhookFilters",
"webhookRelationshipFilters"
],
"properties": {
"replay": {
"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"
}
}
}
}
},
"webhookFilters": {
"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"
}
}
}
}
}
},
"webhookRelationshipFilters": {
"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"
}
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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": {
"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": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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."
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"relationships": {
"type": "object",
"required": [
"replay",
"webhookFilters",
"webhookRelationshipFilters"
],
"properties": {
"replay": {
"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"
}
}
}
}
},
"webhookFilters": {
"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"
}
}
}
}
}
},
"webhookRelationshipFilters": {
"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"
}
}
}
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "webhookFilters"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"relationships": {
"type": "object",
"required": [
"webhook"
],
"properties": {
"webhook": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "webhookFilters"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"relationships": {
"type": "object",
"required": [
"webhook"
],
"properties": {
"webhook": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "webhookRelationshipFilters"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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 will not be sent to you."
}
}
},
"relationships": {
"type": "object",
"required": [
"webhook"
],
"properties": {
"webhook": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "webhookRelationshipFilters"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"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 will not be sent to you."
}
}
},
"relationships": {
"type": "object",
"required": [
"webhook"
],
"properties": {
"webhook": {
"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"
}
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"exports": {
"description": "A collection of exports.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"description": "A collection of exports.",
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "exports"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"properties": {
"relationships": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"names",
"jobs"
],
"description": "Relationships to include in the exported data. By default, only the root person data will be included."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"description": "Filters to apply when generating the exported data."
},
"status": {
"type": "string",
"enum": [
"Pending",
"Completed",
"Deleted",
"Error"
],
"readOnly": true,
"example": "Pending",
"description": "Status of the exported data. If the status is Error, please contact api@doit.wisc.edu for further investigation."
},
"exportUrl": {
"type": "string",
"format": "url",
"readOnly": true,
"description": "URL of the exported data. This field will only contain the URL when the status of the export is \"Done\"."
},
"requestTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"example": "2024-01-01T00:00:00Z",
"description": "The time the export request was created."
},
"completionTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"example": "2024-01-01T00:05:00Z",
"description": "The time the export was done processing.",
"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"
}
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"examples": {
"example-exports": {
"value": {
"data": [
{
"attributes": {
"relationships": [
"names",
"jobs"
],
"filters": [
{
"attribute": "jobs.divisionCode",
"operator": "STARTS_WITH",
"values": [
"A192",
"A193"
]
}
],
"status": "Done",
"exportUrl": "https://example.com/person-export123.json?signature=456",
"requestTime": "2024-01-01T00:00:00Z",
"completionTime": "2024-01-01T00:05:00Z"
},
"id": "123",
"links": {
"self": "https://api.wisc.edu/people/exports/123"
},
"type": "exports"
}
],
"links": {
"self": "https://api.wisc.edu/people/exports"
}
}
}
}
}
}
},
"singleExport": {
"description": "A single export.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "exports"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"properties": {
"relationships": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"names",
"jobs"
],
"description": "Relationships to include in the exported data. By default, only the root person data will be included."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"description": "Filters to apply when generating the exported data."
},
"status": {
"type": "string",
"enum": [
"Pending",
"Completed",
"Deleted",
"Error"
],
"readOnly": true,
"example": "Pending",
"description": "Status of the exported data. If the status is Error, please contact api@doit.wisc.edu for further investigation."
},
"exportUrl": {
"type": "string",
"format": "url",
"readOnly": true,
"description": "URL of the exported data. This field will only contain the URL when the status of the export is \"Done\"."
},
"requestTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"example": "2024-01-01T00:00:00Z",
"description": "The time the export request was created."
},
"completionTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"example": "2024-01-01T00:05:00Z",
"description": "The time the export was done processing.",
"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"
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"examples": {
"example-export": {
"value": {
"data": {
"attributes": {
"relationships": [
"names",
"jobs"
],
"filters": [
{
"attribute": "jobs.divisionCode",
"operator": "STARTS_WITH",
"values": [
"A192",
"A193"
]
}
],
"status": "Completed",
"exportUrl": "https://example.com/person-export123.json?signature=456",
"requestTime": "2024-01-01T00:00:00Z",
"completionTime": "2024-01-01T00:05:00Z"
},
"id": "123",
"links": {
"self": "https://api.wisc.edu/people/exports/123"
},
"type": "exports"
},
"links": {
"self": "https://api.wisc.edu/people/exports/123"
}
}
}
}
}
}
},
"newCreatedExport": {
"description": "A single export.",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"type": "object",
"required": [
"type",
"id",
"attributes",
"links"
],
"properties": {
"type": {
"type": "string",
"example": "exports"
},
"id": {
"type": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
},
"attributes": {
"type": "object",
"properties": {
"relationships": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"names",
"jobs"
],
"description": "Relationships to include in the exported data. By default, only the root person data will be included."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"description": "Attributes for a filter object when creating a webhook filter (/people/webhooks/{webhookId}/filters) or an export filter (/people/exports).",
"required": [
"attribute",
"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 values. 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 up to 10 non-empty strings. For non-string fields, such as booleans, provide their string equivalents (e.g. \"true\")."
}
}
},
"description": "Filters to apply when generating the exported data."
},
"status": {
"type": "string",
"enum": [
"Pending",
"Completed",
"Deleted",
"Error"
],
"readOnly": true,
"example": "Pending",
"description": "Status of the exported data. If the status is Error, please contact api@doit.wisc.edu for further investigation."
},
"exportUrl": {
"type": "string",
"format": "url",
"readOnly": true,
"description": "URL of the exported data. This field will only contain the URL when the status of the export is \"Done\"."
},
"requestTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"example": "2024-01-01T00:00:00Z",
"description": "The time the export request was created."
},
"completionTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"example": "2024-01-01T00:05:00Z",
"description": "The time the export was done processing.",
"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"
}
}
}
}
},
"links": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
}
}
},
"examples": {
"example-export": {
"value": {
"data": {
"attributes": {
"relationships": [
"names",
"jobs"
],
"filters": [
{
"attribute": "jobs.divisionCode",
"operator": "STARTS_WITH",
"values": [
"A192",
"A193"
]
}
],
"status": "Pending",
"requestTime": "2024-01-01T00:00:00Z"
},
"id": "123",
"links": {
"self": "https://api.wisc.edu/people/exports/123"
},
"type": "exports"
},
"links": {
"self": "https://api.wisc.edu/people/exports/123"
}
}
}
}
}
}
},
"not-found": {
"description": "Unable to find the specified record",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"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": {
"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"
}
}
}
}
}
},
"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": {
"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"
}
}
}
}
}
},
"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": {
"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"
}
}
}
}
}
},
"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": {
"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"
}
}
}
}
}
},
"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": {
"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"
}
}
}
}
}
},
"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": {
"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"
}
}
}
}
}
},
"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": {
"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"
}
}
}
}
}
},
"examples": {
"application/vnd.api+json": {
"value": {
"errors": [
{
"id": null,
"links": {},
"meta": {},
"source": {},
"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": "700",
"required": true,
"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.",
"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": "710",
"required": true,
"schema": {
"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": "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": "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": "string",
"example": "12345",
"description": "Ephemeral ID used to adhere to the JSON:API specification. This ID should not be stored."
}
},
"exportId": {
"name": "exportId",
"description": "ID of an export. 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": "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. Offset pagination is also supported using `page[number]` parameter (example: `page[number]=4&page[size]=10`), but it is disabled by default. The `page[number]` determines the page to display. Offset pagination has significantly worse performance than cursor pagination, so it should only be used by applications that can't support cursor pagination. Contact the developers if you would like to enable it.",
"required": false,
"style": "deepObject",
"explode": true,
"schema": {
"type": "object",
"properties": {
"size": {
"type": "integer",
"example": 50,
"maximum": 1000,
"minimum": 1,
"default": 100,
"description": "Size of page for paginated results."
},
"after": {
"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"
},
"before": {
"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"
},
"number": {
"type": "integer",
"example": 1,
"minimum": 1,
"description": "Page number for paginated results. This parameter is disabled by default. Contact the developers if you would like to enable it."
}
}
}
}
}
}
}