Forked from
interop / iics / IICS Swagger File Public Repository
245 commits behind the upstream repository.
-
Rebecca Wheeler authoredRebecca Wheeler authored
Code owners
Assign users and groups as approvers for specific file changes. Learn more.
process-objects.json 438.70 KiB
{
"openapi": "3.0.2",
"info": {
"title": "Mock 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": "A mock implementation of the Person API. This mock API returns data in the same structure as the real API, with the same features, but with fake data. The API is implemented using [JSON:API](https://jsonapi.org/) and supports the ISO/IEC 8859 character set. A quota of 30 requests per minute is enforced. The mock Person API can be used to evaluate fit of the real Person API, or to start integrating with the Person API while waiting to get access. There is no need to request access after creating an application and subscribing to the mock Person API, approval is instantaneous. The structure of the mock Person API is subject to change and it is not meant for production use. Please contact the API Team with questions or feedback: [api@doit.wisc.edu](mailto:api@doit.wisc.edu). More information on the [non-mock Person API can be found here](../../person-api/1/overview)."
},
"servers": [{
"url": "https://mock.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.",
"required": false,
"style": "deepObject",
"explode": true,
"schema": {
"type": "object",
"properties": {
"size": {
"type": "integer",
"example": 50,
"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"
}
}
}
}
],
"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"
},
"officePhoneNumber": {
"type": "string",
"example": "608-262-1204",
"description": "Primary work-related phone number derived from the person's current UW affiliations. May or may not be associated with the officeAddress."
}
}
},
"relationships": {
"type": "object",
"required": [
"identifiers",
"jobs",
"names",
"wiscard"
],
"properties": {
"identifiers": {
"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": {
"prev": {
"description": "The previous page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[number]=4"
},
"next": {
"description": "The next page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[number]=6"
}
}
}
]
},
"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": "100",
"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"
}, "officePhoneNumber": {
"type": "string",
"example": "608-262-1204",
"description": "Primary work-related phone number derived from the person's current UW affiliations. May or may not be associated with the officeAddress."
}
}
},
"relationships": {
"type": "object",
"required": [
"identifiers",
"jobs",
"names",
"wiscard"
],
"properties": {
"identifiers": {
"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."
}
]
}
}
}
}
}
}
}
}
}
},
"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"
},
"officePhoneNumber": {
"type": "string",
"example": "608-262-1204",
"description": "Primary work-related phone number derived from the person's current UW affiliations. May or may not be associated with the officeAddress."
}
}
},
"relationships": {
"type": "object",
"required": [
"identifiers",
"jobs",
"names",
"wiscard"
],
"properties": {
"identifiers": {
"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, and photoId."
},
"source": {
"type": "string",
"example": "IAM",
"description": "The source of this identifier. We have identifiers from IAM, HRS, SIS, and WISCARD."
},
"value": {
"type": "string",
"example": "UW123A456"
},
"current": {
"description": "Property that indicates if this identifier is currently used.",
"type": "boolean",
"example": true
}
}
},
"identifiers": {
"description": "An identifier",
"type": "object",
"required": [
"type",
"id",
"attributes",
"relationships"
],
"properties": {
"type": {
"type": "string",
"example": "identifiers"
},
"id": {
"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, and photoId."
},
"source": {
"type": "string",
"example": "IAM",
"description": "The source of this identifier. We have identifiers from IAM, HRS, SIS, and WISCARD."
},
"value": {
"type": "string",
"example": "UW123A456"
},
"current": {
"description": "Property that indicates if this identifier is currently used.",
"type": "boolean",
"example": true
} }
},
"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."
},
"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"
},
"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"
},
"lastName": {
"description": "A last name for this person. For the `nameType` of `nameInUse`, this field can only be edited to change capitalization, space characters, single quotes, and hyphens.",
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Za-z '-]*$",
"example": "Smith"
},
"nameType": {
"description": "The type of name for the person.",
"type": "string",
"enum": [
"nameInUse",
"primary"
],
"example": "nameInUse"
},
"source": {
"description": "The source of the name.",
"type": "string",
"enum": [
"profile",
"IAM"
],
"example": "profile"
}
}
},
"errors": {
"description": "An error",
"type": "object",
"properties": { "status": {
"type": "integer",
"example": 400
},
"title": {
"type": "string",
"example": "Error title"
},
"detail": {
"type": "string",
"example": "Additional details about the error"
},
"links": {
"type": "object"
},
"meta": {
"type": "object"
},
"source": {
"type": "object"
}
}
},
"selfLink": {
"description": "The link to access a resource itself",
"type": "object",
"properties": {
"self": {
"type": "string",
"example": "https://api.wisc.edu/link/to/self"
}
}
},
"pagination": {
"description": "The links associated with a paginated collection",
"type": "object",
"properties": {
"prev": {
"description": "The previous page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[number]=4"
},
"next": {
"description": "The next page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[number]=6"
}
}
},
"toManyRelationshipObject": {
"description": "A generic relationship object",
"type": "object",
"properties": {
"links": {
"type": "object",
"properties": {
"related": {
"type": "string",
"example": "https://api.wisc.edu/link/to/related/object"
}
}
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": { "type": "string",
"example": "sampleType"
},
"id": {
"type": "string",
"example": "sampleId"
}
}
}
}
}
},
"toOneRelationshipObject": {
"description": "A generic relationship object",
"type": "object",
"properties": {
"links": {
"type": "object",
"properties": {
"related": {
"type": "string",
"example": "https://api.wisc.edu/link/to/related/object"
}
}
},
"data": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "sampleType"
},
"id": {
"type": "string",
"example": "sampleId"
}
}
}
}
},
"resourceObject": {
"description": "A generic resource object",
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "sampleType"
},
"id": {
"type": "string",
"example": "sampleId"
},
"attributes": {
"type": "object",
"properties": {
"attribute1": {
"type": "string",
"example": "sampleStringAttribute"
},
"attribute2": {
"type": "number",
"example": 123
}
}
},
"relationships": {
"type": "object",
"properties": {
"relatedResource": {
"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."
}
}
},
"webhookFilterAttributes": {
"type": "object",
"required": [
"attribute",
"operator",
"values"
],
"properties": { "attribute": {
"type": "string",
"example": "jobs.divisionCode",
"description": "A valid attribute or relationship attribute on the people resource."
},
"operator": {
"type": "string",
"example": "STARTS_WITH",
"description": "The comparison to be performed on the balues. Valid operators are - 'STARTS_WITH', 'ENDS_WITH', 'CONTAINS', or 'EQUALS'."
},
"values": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"A192",
"A193"
],
"description": "A list of values to compare against. Values are required and must be a list of upto 10 non-empty strings. 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",
"required": [
"attribute",
"operator",
"values"
],
"properties": {
"attribute": {
"type": "string",
"example": "jobs.divisionCode",
"description": "A valid attribute or relationship attribute on the people resource."
},
"operator": {
"type": "string",
"example": "STARTS_WITH",
"description": "The comparison to be performed on the balues. Valid operators are - 'STARTS_WITH', 'ENDS_WITH', 'CONTAINS', or 'EQUALS'."
},
"values": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"A192",
"A193"
],
"description": "A list of values to compare against. Values are required and must be a list of upto 10 non-empty strings. 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 won't 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 won't 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"
}
}
} }
}
},
"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"
},
"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"
},
"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",
"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",
"required": [
"attribute",
"operator",
"values"
],
"properties": {
"attribute": {
"type": "string",
"example": "jobs.divisionCode",
"description": "A valid attribute or relationship attribute on the people resource."
},
"operator": {
"type": "string",
"example": "STARTS_WITH",
"description": "The comparison to be performed on the balues. Valid operators are - 'STARTS_WITH', 'ENDS_WITH', 'CONTAINS', or 'EQUALS'."
},
"values": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"A192",
"A193"
],
"description": "A list of values to compare against. Values are required and must be a list of upto 10 non-empty strings. 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",
"required": [
"attribute",
"operator",
"values"
],
"properties": {
"attribute": {
"type": "string",
"example": "jobs.divisionCode",
"description": "A valid attribute or relationship attribute on the people resource."
},
"operator": {
"type": "string",
"example": "STARTS_WITH",
"description": "The comparison to be performed on the balues. Valid operators are - 'STARTS_WITH', 'ENDS_WITH', 'CONTAINS', or 'EQUALS'."
},
"values": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"A192",
"A193"
],
"description": "A list of values to compare against. Values are required and must be a list of upto 10 non-empty strings. 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 won't 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 won't be sent to you."
} }
}
}
}
}
}
}
}
}
},
"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"
},
"officePhoneNumber": {
"type": "string",
"example": "608-262-1204",
"description": "Primary work-related phone number derived from the person's current UW affiliations. May or may not be associated with the officeAddress."
}
}
},
"relationships": {
"type": "object",
"required": [
"identifiers",
"jobs",
"names",
"wiscard"
],
"properties": {
"identifiers": {
"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": {
"prev": {
"description": "The previous page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[number]=4"
},
"next": {
"description": "The next page of data",
"type": "string",
"format": "uri-reference",
"example": "https://api.wisc.edu/people?page[number]=6"
}
} }
]
},
"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"
},
"officePhoneNumber": {
"type": "string",
"example": "608-262-1204",
"description": "Primary work-related phone number derived from the person's current UW affiliations. May or may not be associated with the officeAddress."
}
}
},
"relationships": {
"type": "object",
"required": [
"identifiers",
"jobs",
"names",
"wiscard"
],
"properties": {
"identifiers": {
"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).",
"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, and photoId."
},
"source": {
"type": "string",
"example": "IAM",
"description": "The source of this identifier. We have identifiers from IAM, HRS, SIS, and WISCARD."
},
"value": {
"type": "string",
"example": "UW123A456"
},
"current": {
"description": "Property that indicates if this identifier is currently used.",
"type": "boolean",
"example": true
}
}
},
"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."
},
"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"
},
"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"
},
"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"
}
}
}
}
}
}
},
"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",
"required": [
"attribute",
"operator",
"values"
],
"properties": {
"attribute": {
"type": "string",
"example": "jobs.divisionCode",
"description": "A valid attribute or relationship attribute on the people resource."
},
"operator": {
"type": "string",
"example": "STARTS_WITH",
"description": "The comparison to be performed on the balues. Valid operators are - 'STARTS_WITH', 'ENDS_WITH', 'CONTAINS', or 'EQUALS'."
},
"values": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"A192",
"A193"
],
"description": "A list of values to compare against. Values are required and must be a list of upto 10 non-empty strings. 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",
"required": [
"attribute",
"operator",
"values"
],
"properties": {
"attribute": {
"type": "string",
"example": "jobs.divisionCode",
"description": "A valid attribute or relationship attribute on the people resource."
}, "operator": {
"type": "string",
"example": "STARTS_WITH",
"description": "The comparison to be performed on the balues. Valid operators are - 'STARTS_WITH', 'ENDS_WITH', 'CONTAINS', or 'EQUALS'."
},
"values": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"A192",
"A193"
],
"description": "A list of values to compare against. Values are required and must be a list of upto 10 non-empty strings. 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 won't 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 won't 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"
}
}
}
}
}
}
},
"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": "100",
"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": "101",
"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."
}
},
"filter": {
"name": "filter",
"in": "query",
"description": "Filter results of query using the [filter query parameter family](https://jsonapi.org/recommendations/#filtering). Refer to the [Person API Documentation](/person-api/filter-query-parameter) for more information about the `filter` query param.",
"required": false,
"style": "deepObject",
"explode": true,
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"attribute": {
"type": "string",
"example": "firstName"
}
}
}
},
"include": { "name": "include",
"in": "query",
"description": "[include related resources](https://jsonapi.org/format/#fetching-includes). The resources to include need to be direct relationships. Nested relationships are not supported. For example, `include=jobs,identifiers` is supported but `include=person.jobs` is not supported.",
"schema": {
"type": "string"
}
},
"fields": {
"name": "fields",
"in": "query",
"description": "Specify the list of fields you would like to return for each resource type. For example, `fields[people]=firstName,lastName` will just return the names for people. If you are including related resources with 'includes' you can also specify fields on those resources as well. For example, `includes=jobs&fields[people]=jobs&fields[jobs]=title` will just return titles for jobs. See [Sparse Fieldsets](https://jsonapi.org/format/#fetching-sparse-fieldsets) for more details.",
"required": false,
"style": "deepObject",
"explode": true,
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"example": "people"
}
}
}
},
"page": {
"name": "page",
"in": "query",
"description": "Define options for pagination of responses. For example, `page[size]=5&page[after]=400&page[before]=800` will return a response with data about 5 people whose `id` value falls after `400` but before `800`. So `page[size]` determines the number of people resources in a response, `page[after]` is the ID of the person at the end of the previous page, `page[before]` is the ID of the person at the start of the next page.",
"required": false,
"style": "deepObject",
"explode": true,
"schema": {
"type": "object",
"properties": {
"size": {
"type": "integer",
"example": 50,
"description": "Size of page for paginated results."
},
"after": {
"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"
}
}
}
}
}
}
}