> For the complete documentation index, see [llms.txt](https://docs.coresignal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coresignal.com/guides/bulk-collect-guide.md). # Step-by-step Bulk Collect guide Submit a bulk data request, track its status, and download the completed file. [Bulk Collect](/api-introduction/requests/bulk-collect.md) 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. {% embed url="" %} *** {% stepper %} {% step %} ### 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](/api-introduction/requests/bulk-collect/post-requests.md). Supported endpoints depend on the data entity you want to use. Check the related API article for [supported endpoints](/api-introduction/requests/bulk-collect.md#discover-products). | 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 | | {% endstep %} | | | {% step %} ### 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. ```json 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 ```json { "webhook_url": "(optional)", "limit": "(optional integer)", "filters": {} // or "es_dsl_query", "ids", "shorthand_names", "urls" } ``` {% endstep %} {% step %} ### 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. {% code title="Response example" %} ```json { "request_id": "123456ab-123a-1abc-1a23-ab1cd23456e7" } ``` {% endcode %} {% endstep %} {% step %} ### 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: {% code title="Response example" %} ```json { "data_request_files": ["json/part-1234-example.json.gz"] } ``` {% endcode %} {% hint style="info" %} If you get `"detail": "Insufficient credits"`, resubmit the POST with a `"limit"` parameter. {% endhint %} {% endstep %} {% step %} ### 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 ``` {% endstep %} {% endstepper %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.coresignal.com/guides/bulk-collect-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.