Person API Wiscards

Information about Wiscards in the Person API, including Wiscard photos.

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.

  1. Get the person's wiscard resource, either by making a GET request to /people/{id}/wiscard or by including the wiscard relationship in a request for people (e.g. GET https://api.wisc.edu/people?include=wiscard).
  2. Send a GET request to the URL in the photoUrl attribute. Do not send your Person API access token or any other Authorization header 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 photoUrl for 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 photoUrl in a retried or replayed event may have already expired. If a photo URL from a webhook event or export has expired, get the person's wiscard resource 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.


Keywords:
person-api 
Doc ID:
165567
Owned by:
Jared K. in DoIT Enterprise Integration - API Team
Created:
2026-11-19
Updated:
2026-11-19
Sites:
DoIT Enterprise Integration - API Team