Step-by-step Bulk Collect guide

Bulk Collect lets you retrieve large volumes of data in a single job instead of making individual requests per record. You submit a POST request with your query, receive a request_id, and then use a GET request to download the result once it is ready. This guide walks you through each step and applies regardless of the entity or endpoint type you are using.

---

1

Pick your input method

Choose how you will supply the data you want to collect. This determines which endpoint suffix to use in your POST request. Read about bulk collect request methods.

Supported endpoints depend on the data entity you want to use. Check the related API article for supported endpoints.

Method	Endpoint	Notes
Search Filters	/filter	Set a list of filters
Elasticsearch DSL	/es_dsl	Advanced queries
ID list (inline) ID file upload	/ids /id_file	Numeric IDs only, either in the request body or in a file (depends on the supported endpoint)
Shorthand names	/shorthand_names	Available only in the Clean Employee API and Base Employee API
URLs	/urls	Use profile URLs. Available only in the Clean Employee API and Base Employee API

2

Send the POST request

/v2/data_requests/{entity}/{method} request submits your bulk job. Construct the request using your chosen method's endpoint and fill in your entity, API key, and query body. Credits are deducted at this point based on the number of matched records.

curl -X 'POST' \
'https://api.coresignal.com/cdapi/v2/data_requests/{entity}/{method}' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{}'

Body fields by method:

• filters - insert the required filters and values

• es_dsl_query - use Elasticsearch DSL for advanced search options

• ids - add a list of IDs to the body to retrieve data

• shorthand_names - use profile shorthand names

• urls - enter profile URLs

{
  "webhook_url": "(optional)",
  "limit": "(optional integer)",
  "filters": {}        // or "es_dsl_query", "ids", "shorthand_names", "urls"
}

3

Save the Request ID

The POST response returns a unique request_id. You will need it for subsequent GET requests to check status and download the file.

Response example

{ "request_id": "123456ab-123a-1abc-1a23-ab1cd23456e7" }

4

Get the file name

Send a GET request /v2/data_requests/{request_id}/files with entered request_id to check whether the data is ready.

GET https://api.coresignal.com/cdapi/v2/data_requests/123456ab-123a-1abc-1a23-ab1cd23456e7/files

Data preparation takes time. Repeat the GET request to /v2/data_requests/{request_id}/files until a file name appears in the response. The file name in the response looks like this:

Response example

{ "data_request_files": ["json/part-1234-example.json.gz"] }

If you get "detail": "Insufficient credits", resubmit the POST with a "limit" parameter.

5

Download the data

Use the request_id and data_request_files from the previous steps to fetch the actual data from the /v2/data_requests/{request_id}/files/{data_request_files} endpoint. The JSON file can be downloaded multiple times within 30 days of the original submission.

GET https://api.coresignal.com/cdapi/v2/data_requests/123456ab-123a-1abc-1a23-ab1cd23456e7/files/json/part-1234-example.json.gz