Upload via API

The Upload API endpoint facilitates the uploading of CSV files, which are then asynchronously imported into the Portal application.

Upload API Endpoint

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

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 upload 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 Bearer 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 upload the CSV file to the endpoint:

curl --location 'https://{TAO_ADVANCE_URL}/api/v1/upload/api/v1/upload' \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'Content-Type: multipart/form-data' \
    --form 'file=@"/path/to/files/users.csv"'

• location: Upload API endpoint URL: https://{TAO_ADVANCE_URL}/api/v1/upload/api/v1/upload

• header Authorization: Use the access_token value as the Bearer token in the Authorization header when making the upload request.
  header Content-Type: The content type must be set to multipart/form-data.

• form: The path to the CSV file. When uploading a file, it must be included in the request as a file form property.

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

{
    "result": {
        "message": "File uploaded to import-csv/pending/<reference_id>.csv",
        "referenceId": "<reference_id>"
    }
}

The referenceId provided in the response is a unique identifier used to track the file during the import process. This referenceId is essential for identifying the specific upload and import operation. If any issues arise, you can reference this ID when reporting the problem to assist in troubleshooting and resolution.

Possible Errors

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

{ "message": "No file found in the request" }

{ "message": "Error: File extension \"<extension>\" is not allowed. 

{ "message": "File size exceeds the allowed limit of XXX bytes" }

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

{ "message": "Insufficient scope" }