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 field	Data type	Description
created	date-time	Timestamp when the job was created
download_link	string	Link where completed data may be requested
duration	string	Duration the job has been running
finished	date-time	Timestamp when the job was completed
job_id	string	Unique id for the job
link	string	Link to request the status of the job. Response is identical to the initial request
state	string	State 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

State	Description
accepted	Job has been accepted by Vainu and processing will begin shortly
completed	Job has been completed and is ready for download
failure	Job has failed due to error.
process	Job 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.