Check upload status via API

The Status API endpoint allows customers to check the status of an import operation using the referenceId provided during the upload process.

This endpoint is essential for tracking the progress and success of your data imports, enabling you to quickly identify and address any issues that may arise.

Status Endpoint

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

Note: The {referenceId} is a placeholder for the unique identifier you received during the upload process (see section above). Replace {referenceId} with the actual ID to check the status of your specific import operation.

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

https://{TAO_ADVANCE_URL}/api/v1/upload/api/v1/status/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 status 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 check the status of an import operation:

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

• location: Status check API endpoint URL: https://{TAO_ADVANCE_URL}/api/v1/uploadpi/v1/status/{referenceId}

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

Upon successfully requesting the status of a file using the Status API endpoint, the response should look similar to the following JSON structure:

{
    "result": {
        "status": "processed",
        "fileLine": 2,
        "messages": []
    }
}

Response Fields

• status: Indicates the current state of the import. Possible values are:

  • "processed": The import has been successfully completed.

  • "pending": The import is still in progress.

  • "failed": The import has encountered errors and was not successful.

• fileLine: The number of lines from the CSV file that have been imported or processed. This provides insight into how much of the file has been handled.

• messages: An array that contains any error messages that occurred during the import process. If the import was successful, this array will be empty. If errors occurred, detailed messages will be provided to help diagnose and resolve issues.

Possible Errors

When using the Status 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" }