Downloading a complete set of customer holdings gives you the ability to populate the holdings into another application, such as a reporting system, or maintain a local cache of holdings. The process to download a set of customer holdings consists of the following steps:

Request a new export file of holdings data (optional, a previously created export of holdings data can be used if available).
Retrieve the export record for a set of holdings data.
Download the customer holdings.

Request a New Export File

Before you can download a set of customer holdings, an export file of holdings data needs to be created. The export files of holdings data can be accessed by export id. If an export file already exists of your desired holdings data, you do not need to request that an export file be created. You can retrieve the details about the exports of your holdings using the GET /{custid}/exports endpoint.

To Create a New Export File of Holdings Data (example):

Request

POST https://sandbox.ebsco.io/rm/rmaccounts/CUSTID/exports

Response

202 ACCEPTED

{
  "custId": "testid",
  "id": "096dea08-c57e-4dc5-a984-51a99830ffff",
  "type": "STANDARD",
  "fileName": "testExport_standard_csv",
  "status": "QUEUED",
  "created": "2023-06-01T19:31:40.241315Z",
  "format": "CSV"
}

If your request to populate holdings has been accepted for processing, a 202 is returned. The 202 is an indication that your request has been accepted, but the processing has not been completed.

Customers can make changes such as removing a title, selecting a title or hiding a title in their holdings at any time. If a customer has made holdings changes since the holdings data export file was created, you need to create a new holdings data export file with a fresh POST request. The fresh POST request ensures that you have all of the latest changes reflected in the holdings data export file.

For more information on the POST holdings resource, please refer to our API reference documentation.

Retrieve a Holdings Data Export Record

After you have either created a new holdings data export or retrieved the details of a previously created export, you need to retrieve the export record.

To Retrieve the Holdings Data Export Record (example):

Gather the following information for the request:

The export id of the holdings data.

Request

GET https://sandbox.ebsco.io/rm/rmaccounts/CUSTID/exports/{exportid}

Response

200 OK


{
  "id": "096dea08-c57e-4dc5-a984-51a94afff2",
  "type": "STANDARD",
  "fileName": "testExport_standard_csv",
  "status": "COMPLETED",
  "created": "2023-06-01T19:31:40.241Z",
  "format": "CSV",
  "links": [
    {
      "href": "https://s3.amazonaws.com/cdn.hhm.ebsco.com/testid/096dea08-c57e-4dc5-a984-51a94a30fff2/testExport_standard_csv?response-content-disposition=attachment%3B%20filename%3D%22testExport_standard_csv.csv%22%3B&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEIz%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJIMEYCIQCskpH4pByB%2Bm%2FP2fua5wzyB82UXZQ5yhDYY9ElO%2FKQIhAN9n83O6JCxI15DGh695wQrXdNpqK6czz%2BFlUVMhAUUnKo4FCMX%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQBBoMNjA0MTY2NTIxMzA3IgxN6Of%2Bj9PEFdNoAAcq4gTlsq0keJGhwE8WmDBd%2BK2K6Oh0acpAE9%2F4fW%2BL3yaLHwf7TT%2BBluU9VFFXYj6H0WILz2SWovjlUxb9wVxR00EmEZvKGPFv2rjZfURW3XCCEYFSvzg5PpwBTZuRx5zZHZ1%2BeGDaU26APjpPjdoQfMlSB%2F3G8QAS0hJV2pYdemY1sbo8EKR57xYjzqIsb36C0UxTg4HwI%2wJWwETGV4VczH7s4NW1AqnbeGcfZmhy%2Bn7UzgV4ISFmC74S8r%2FmCk%2FjNGleRg%2FSMOILes4yFGQk%2BEJ82iB9GQ1UbOFuBdOfaegE4iHRKzKCmqhEcHkmTVrX5vsKoJqKjBi2hluYBUutGtGFCdUTvD9%2BbvpuE9TIIgZkqa6PHcYKNoUsTqNkfoPNXnamIgGytFPNjoHOsOvFfgEpN2lmTj4hAIYYN7cx2doaPlQrSRrSOU6wZFBr0sK0d4t1ICtDDSv8MMrNe6FgWwxXjMKvp%2FsLLy0vLVrpniAtVhh0ofryyyfOgbPjZl5%2FmJJV7aIbnmpHvQXXUkiNuo0qicnTVIvgphioNLhq0DRQSPBdyt35nl06ejQJ%2FH367XfezlXtcNIhw98J2x7GS3gZzH2v8QMkigZ%2Fx2jWCw4RzGIVixD8w4NGcdraj0vhBcs7TIH8eWEWLj7Chw7XGeQ5fo4gJ6MxsiUzxYdWVOlUjCGQG1vnSn6AEK5TnGYYQn8Ao6zNQRLQL0LVuKIw64QZuWptLqeWNlnjEnuqBbNKYttsjRaqeki3j9RTNN09KiGqNK0D0Z3s4RRMQaHta42MNwexjzKulEGPdbLMOvt46MGOpkBbqi7YXGV5VeubNZZpJF7WPVNYeTQg1UOPT4MacxJOvPekE0uX46Cv5MHViNBS3ZKKitKa5FWyeQg2mv%2BoCWJFTMH%2Ba4IfIHUCTiam8ePAtnOoUEmbNRELCrWA%2Fc3Q%2FZoU4M5PqaFOhci4yK8jrupcCa5OwScXdsZ2p5Z5XbM2Wkk4hJMzUbJQxqZ%2BwxQNmtDvKCUlVnOS&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230601T195211Z&X-Amz-SignedHeaders=host&X-Amz-Expires=604800&X-Amz-Credential=ASIAYZKZBQHN5YM5EI6H%2F20230601%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=ea94d56886d3b8053a074dd5ed8dd0dced742092e8f026368bcc84aa11b03b1",
      "rel": "download"
    }
  ],
  "size": 2386715,
  "customerHoldingsCounts": {
    "totalResourceCount": "4612",
    "managedResourceCount": "4604",
    "customResourceCount": "8",
    "totalManagedPackageCount": "16",
    "totalCustomPackageCount": "3",
    "uniqueResourceCount": "4582",
    "uniqueManagedResourceCount": "4574",
    "uniqueCustomResourceCount": "8"
  }
}

If the “status” element in the response is “COMPLETED”, the customer holdings data has been populated and the customer holdings are ready to be downloaded.

For more information on the GET Export by Export ID resource, please refer to our API reference documentation.

Download

After the customer holdings data has been successfully exported to an export file, you can download the customer holdings in KBART2, STANDARD, COST or HOLDINGSEVENT format. The links array in the Export object contains a presigned URL to download the export file from. The URL provided is valid for 30 minutes. If the URL expires, a new URL can be requested from the API.

Example URL:

"links": [
    {
      "href": "https://s3.amazonaws.com/cdn.hmm.ebsco.com/testid/096dea08-c57e-4dc5-a984-51a94a30fff2/testExport_standard_csv?response-content-disposition=attachment%3B%20filename%3D%22testExport_standard_csv.csv%22%3B&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEIz%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJIMEYCIQCskpH4pByB%2Bm%2FP2fua5wzyB82UXZQ5yhDYYzElO%2FKQIhAN9n83O6JCxI15DGh695wQrXdNpqK6czz%FlUVMhAUUnKo4FCMX%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQBBoMNjA0MTY2NTIxMzA3IgxOf%2Bj9PEFdNoAAcq4gTlsq0kageJGhwE8WmDBd%2BK2K6Oh0acpAE9%2F4fW%2BL3yaLHwf7TT%2BBluU9VFFXYeRj6H0Lz2SWovjlUxb9wVxR00EmEZvKGPFv2rjZfURW3XCCEYFSvzg5PpwBTZuRx5zZHZ1%2BeGDaU2L6APjpPjdoQfMlSB%2F3G8S0hJV2pYdemY1sbo8EKR57xYjzqIsb36C0UxTg4HwI%2FwJWwETGV4VczH7s4NW1AqnbeGcfZmhy%2Bn7UzgV4ISFmC74S8r%2FmCk%2FjNGleRg%2FSMOILes4GQk%2BEJ82iB9GQ1UbOFuBdOfaegE4iHRKzKCmqhEcHkmTVrX5vsKoJqKjBi2hluYBUutGtGFCdUTvD9%2BbvpuE9TIIgZkqa6PHcYKNoUsTqNkfoPNXnamGytFPNjoHOsOvFfgEpN2lmTj4hAIYYN7cx2doaPlQrSRrSOU6wZFBr0sK0d4t1ICtDDSv8MMrNe6FgWwxXjMKvp%2FsLLy0vLVrpniAtVhh0ofryfOgbPjZl5%2FmJJV7aIbnmpHvQXXUkiNuo0qicnTVIvgphioNLhq0DRQSPBdyt35nl06ejQJ%2FH367XfezlXtcNIhw98J2x7GS3gZzH2v8QMki%2Fx2jWCw4RzGIVixD8w4NGcdraj0vhBcs7TIH8eWEWLj7Chw7XGeQ5fo4gJ6MxsiUzxYdWVOlUjCGQG1vnSn6AEK5TnGYYQn8Ao6zNQRL0LVuKTIw64QZuWptLqeWNlnjEnuqBbNKYttsjRaqeki3BKj9RTNN09KiGqNK0D0Z3s4RRMQaHta42MNwexjzKulEGPdbLMOvt46MGOpkBbqi7YV5VeubNZZpJF7WPVNYeTQg1UOPT4MacxJOvPekE0uX46Cv5MHViNBS3ZKKitKa5FWyeQg2mv%2BoCWJFTMH%2BIfIHUCTiam8ePAtnOoUEmbNRELCrWA%2Fc3Q%2FZoU4M5PqaFOhci4yK8jrupcCa5OwScXdsZ2p5XbM2Wkk4hJMzUbJQxqZ%2BwxQNmtDvKCUlVnOS&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230601T195211Z&X-Amz-SignedHeaders=host&X-Amz-Expires=604800&X-Amz-Credential=ASIAYZKZBQHN5YM5EI6H%2F202601%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=ea94d56886d3b8c053a074dd5ed8dd0dced742092e8f026368bcc84aa11b03b1",
      "rel": "download"
    }
  ]