Universe API - Async jobs

Technical Information

This technical document explains the proper flow to use the Clarity AI Universe API that our customers can use to get all Clarity AI's scores for a given security type (FUND, EQUITY, FIXED_INCOME) and a given set of Scores. Please refer to the specific endpoint for a complete description of the requirements for that endpoint.

As the request can take some time depending on the volume of data and the number of desired scores, we have implemented an asynchronous process to respond in the best possible way.

The first step, as with every Clarity API endpoint, is getting a token to authorize your calls. This is the same step and the same token you need for any other call. Please check the documentation here.

Depending on the type of universe you want to request, you'll need to call one endpoint or another: you will have one endpoint for ESG Risk scores, another one for ESG Impact scores, and in general, for every type of request you'll need to call a specific endpoint with specific parameters. For example, in the case of the ESG Risk Universe call, you'll need to send the scoreId and securityTypes you want, but this may change for other endpoints.

As response, you will get a unique identifier (UUID) for your request. You have to store it locally as it's needed for subsequent calls.

The response for this initial call will be an HTTP 200 code (if all parameters are good), then Clarity's servers will start processing your request asynchronously in the background.

From this point onward, the set of needed calls will be the same regardless of the original endpoint.

You'll need to poll our system from time to time (recommendation here is about 5 minutes) to know the status of your request. You can do it by calling our jobStatus endpoint sending as a parameter the UUID you got in the first call. If your work it's still being processed, server will respond to you with an HTTP 202 (Accepted, but processing not complete) code. If some error has occurred while processing, the response will be an HTTP 422 (Unprocessable Entity) code.

Finally, if everything goes well and your request is ready for download, you'll get an HTTP 302 (Found) code.

When your request is ready to be served, just call our jobDownload endpoint (again, you'll send us the UUID from the first call) and we'll send you the URL of the file with the requested information that you can download using a standard HTTP call.

Workflow diagrams

Let's see some diagrams to clarify this chain of calls:

Golden path

Job processing error

Wrong job request