Download results via API

The Download API endpoint allows customers to retrieve a signed URL that can be used to download the result of an import operation. This endpoint is accessed using the referenceId provided during the upload process.

Download Endpoint

https://{TAO_ADVANCE_URL}/api/v1/upload/api/v1/download/{referenceId}

Note: The {referenceId} is a placeholder for the unique identifier you received during the upload process. Replace {referenceId} with the actual ID to download the results of a specific import operation.

Example: If your referenceId is 12345, the endpoint URL would be:

https://{TAO_ADVANCE_URL}/api/v1/upload/api/v1/download/12345

Prerequisite

To use this endpoint, customers must authenticate by providing a valid Bearer token in the Authorization header. For more information, see Importing rostering data via API | Authentication.

Authentication and download instructions (example)

To obtain the Bearer token required for authorization when using the Upload API endpoint, you can fetch it by making a request to the Auth Server.

The following curl command demonstrates how to retrieve the token:

curl --location 'https://{TAO_ADVANCE_URL}/api/v1/upload/v1/oauth2/tokens' \
     --form 'grant_type="client_credentials"' \
     --form 'client_id="{{CLIENT_ID}}"' \
     --form 'client_secret="{{CLIENT_SECRET}}"'

The response from this request should be OAuth2-compliant and must be in JSON format. The access_token field in the response contains the token that should be used in the Authorization header for the Upload API endpoint. The following example displays how the relevant part of the response might look:

{
    "access_token": "<your_access_token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    ...
}

The following curl command demonstrates how to format the download request:

curl --location 'https://{TAO_ADVANCE_URL}/api/v1/upload/api/v1/download' \
     --header 'Authorization: Bearer <your_access_token>'

• location: Download API endpoint URL: https://{TAO_ADVANCE_URL}/api/v1/upload/api/v1/download/{referenceId}

• header Authorization: Use this access_token value as the Bearer token in the Authorization header when making the download request.

Upon successfully uploading a file using the Upload API endpoint, the response should look similar to the following JSON structure:

{
    "signedUrl": "<signed url>"
}

Once you receive the signed URL, you can use it to download the result file directly from your browser or through any tool that can make HTTP requests, such as curl or Postman. The file will contain the processed data or any error details that occurred during the import operation, depending on the status of the import. This download URL is secure and time-limited, meaning it will expire after a certain period, so it's recommended to download the file as soon as possible after receiving the URL.

Possible Errors

When using the Download API endpoint, several errors may occur. Below are the common errors you might encounter, along with their corresponding response codes and messages:

{ "message": "Reference ID not found. File not found in pending bucket." }

{ "message": "<Details of the specific error>" }

{ "message": "Insufficient scope" }