Person API Exports

Bulk person data can be exported by creating an export request . An export request initiates an asynchronous process that generates a JSON file of people data based on the export parameters. The exported data can be generated using filters and by indicating which relationships (e.g. jobs) should be included.

Important Information on Exported Data

The Person API exports endpoints do not return the exported data, but instead provide a link in the attribute exportUrl where the data can be retrieved externally. 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.

The exportUrl expires 3 minutes after the time indicated in the attribute completionTime . If the exportUrl was accidentally shared or leaked before it expired, make a DELETE request to the export resource . This will delete the export request and its exported data.

The exported data does not change after being generated.

Instructions

Follow these steps to create an export and use the exported data.

1. Create an export request and indicate which data should be included using the relationships , filters and advancedFilter attributes. By default, no filters will be applied and only the root person object's data will be included.

For example, this request will create an export that contains people who have a job with a division code that starts with A192 . The export will contain each person's root object as well as their name resources.

POST https://api.wisc.edu/people/exports

Content-Type: application/vnd.api+json

Authorization: Bearer <your_access_token>

{
  "data": {
    "attributes": {
      "filters": [
        {
          "attribute": "degrees.degree",
          "operator": "STARTS_WITH",
          "values": [
            "BA"
          ]
        }
      ],
      "relationships": ["names"]
    },
    "type": "exports"
  }
}

Or the equivalent body using advanced filtering:

{
  "data": {
    "attributes": {
      "advancedFilter": "degrees(startsWith(degree, \"BA\"))",
      "relationships": ["names"]
    },
    "type": "exports"
  }
}

A 202 Accepted response will indicate the export request has been received.

2. Use the self link (e.g. https://api.wisc.edu/people/exports/123 ) returned in the response when creating the export to check on its status by making a GET request .
3. When the status of the export is Completed , send a GET request to the URL provided in the exportUrl attribute to retrieve the exported data.

Exported Data Format

The exported data will mirror the structure of the data returned by the /people endpoint .

Timeouts

Exports are expected finish in less than 120 minutes after creating an export request. If an export has not completed in 120 minutes, the status will be set to Error . Please contact the DoIT API Team if you continue to get exports that result in an error status: api@doit.wisc.edu