Asynchronous requests

Asynchronous requests

Get Companies endpoint of Vainu API supports asynchronous operations. This is especially handy with complex queries or with larger datasets, where response times might be slower.

With asynchronous requests, Vainu API responds with job details or begins a process to generate a file to be downloaded. API can be used for follow-up queries to get the status of the job and eventually to get a download link for the response.


Limit for asynchronous request

Note that the default maximum limit of 1000 returned objects applies to the asynchronous endpoint. This can be changed. Contact your Vainu representative or support for requests.

Making an asynchronous task

Asynchronous endpoint has a separate endpoint but utilizes the same filtering capabilities as a normal GET companies endpoint. Instead of an immediate response, the API will respond with the job ID and details.

Following fields will be included in the initial and follow-up request responses.

Data fieldData typeDescription
createddate-timeTimestamp when the job was created
download_linkstringLink where completed data may be requested
durationstringDuration the job has been running
finisheddate-timeTimestamp when the job was completed
job_idstringUnique id for the job
linkstringLink to request the status of the job. Response is identical to the initial request
statestringState of the job. Expected statuses are accepted, process, completed, and failure

Status of the asynchronous task

The initial response of the initiated job includes a field called link. This field may be used for follow-up queries to see the state and job details. The response will be identical to the first request.

Expected states of the job are following

acceptedJob has been accepted by Vainu and processing will begin shortly
completedJob has been completed and is ready for download
failureJob has failed due to error.
processJob is in process and will be completed shortly.

Getting results of a completed task

When the job state is "completed" the results can be downloaded from the download_link found at the initial or follow-up responses. You can either use the link to download the file or do a simple GET request to get the response programmatically.

Response and data included will be as stated in the initial request. See the Filtering and Response data guides for further instructions on how to manage response data.