Person API Wiscards
The Person API provides data from a person's Wiscard, the UW-Madison ID card, in the wiscard resource. Wiscards are only available for UW-Madison people.
Wiscard Photos
The wiscard resource includes a link to the person's Wiscard ID card photo in the photoUrl attribute and a checksum of that photo in the photoSha attribute. Photos are JPEG images. Photo dimensions and file sizes vary from person to person.
If a person has a Wiscard but no photo, photoUrl and photoSha will be null.
Getting Access to Photos
The photoUrl and photoSha attributes are only available to applications with the Wiscard Photos permission. If your application does not have this permission, these attributes will be left out of the wiscard resource. To request the Wiscard Photos permission, follow the instructions in Getting Access to the Person API.
Important Information on Photo URLs
The Person API does not return the photo itself, but instead provides a link in the photoUrl attribute where the photo can be retrieved. The link is unique and should not be shared with anyone. Make sure to treat the link itself like a password and handle it securely. This link contains a cryptographic signature so that it cannot be guessed by anyone who doesn't know it. Anyone who has the link can view the photo until the link expires, without any other authentication.
Do not log photo URLs, store them where they can be viewed by others, or send them to a web browser (for example, as the src of an <img> tag). If your application displays photos to users, download the photo on your server and serve it to users from your application.
If a photo URL was accidentally shared or leaked, contact the DoIT API Team: api@doit.wisc.edu.
Retrieving a Photo
Follow these steps to retrieve a person's Wiscard photo.
- Get the person's
wiscardresource, either by making aGETrequest to/people/{id}/wiscardor by including thewiscardrelationship in a request for people (e.g.GET https://api.wisc.edu/people?include=wiscard). - Send a
GETrequest to the URL in thephotoUrlattribute. Do not send your Person API access token or any otherAuthorizationheader with this request. The response body is the JPEG image.
For example, this request gets a person's Wiscard:
GET https://api.wisc.edu/people/e2118c5a-aae2-4475-a661-bb0592effefa/wiscard
Authorization: Bearer <your_access_token>
The response will include the photo attributes:
{
"data": {
"attributes": {
"wiscardId": "1234567890",
"issueCode": "0",
"expirationDate": "2122-07-01",
"photoUrl": "https://storage.googleapis.com/...",
"photoSha": "9F86D081884C7D659A2FEAA0C55AD015A3BF4F1B2B0B822CD15D6C15B0F00A08",
"institution": "UW-Madison"
},
"id": "e4a251ee-ad7c-4877-b2d2-af0edd5547d4",
"type": "wiscard"
}
}
Photo URL Expiration
Photo URLs expire. The Person API generates a new photoUrl for every photo each day, and each URL remains valid for 3 days after it was generated. This means a URL you get from the Person API will be valid for at least 2 days.
Do not store photo URLs for later use. Instead, download the photo shortly after getting the URL, or get the person's wiscard resource again when you need the photo. A request to an expired URL will fail with a 4xx status code (typically 400), in which case get a new URL from the Person API.
Because the URL changes every day even when the photo has not changed, do not use photoUrl to detect changes to a person's photo. Use photoSha instead.
Detecting Photo Changes
The photoSha attribute is the SHA-256 hash of the photo, formatted as uppercase hexadecimal. It only changes when the person's photo changes. If your application stores copies of photos, store the photoSha along with each photo and only download a photo again when its photoSha changes.
You can also find the person with a specific photo by filtering on photoSha, for example: GET https://api.wisc.edu/people?filter[wiscard.photoSha]=<photoSha>
Photos in Webhooks and Exports
For applications with the Wiscard Photos permission, photoUrl and photoSha are included in the wiscard resource in Person API Webhooks and Person API Exports.
- Webhook events are sent when a person's photo is added, changed, or removed. Webhook events are not sent when the Person API generates a new
photoUrlfor an unchanged photo. - Photo URLs in webhook events and exports expire the same way as photo URLs from other Person API requests. Webhook events can be retried or replayed for up to 7 days, so the
photoUrlin a retried or replayed event may have already expired. If a photo URL from a webhook event or export has expired, get the person'swiscardresource from the Person API to get a new URL. - Webhook events for photos added to people when Wiscard photos were first added to the Person API count as new data. See Person API Webhooks for more information on new data events.