> 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/turning-a-natural-language-query-into-an-api-integration.md). # Turning a Natural Language Query Into an API Integration Turn natural-language prompts into validated Elasticsearch DSL queries for Coresignal API integrations. Coresignal's playgrounds are ideal for initial tests and pulling small-scale data, but relying on manual queries can quickly slow your workflow. As demand grows, API integration allows you to automate and scale your workflows. This guide shows you how to use [API Playgrounds](/self-service/features-and-tools/api-playgrounds.md) and [Agentic Search](/self-service/features-and-tools/agentic-search-api-playground.md) to generate and carry a tested query into the appropriate API endpoint. You will learn how to get an Elasticsearch DSL query with a natural language prompt that you can edit to match your search criteria and reuse in production whenever needed. Keep reading for a step-by-step overview of the workflow using both API Playgrounds and Agentic Search, common errors you may run into, and how to solve them. ### Case A: Starting from Agentic Search Agentic Search acts as an automated query builder, translating natural language into an Elasticsearch DSL query that can be executed directly in production pipelines. Because it is fully accessible via API, you can integrate prompt-to-query generation directly into your automated workflows without ever needing to visit the dashboard. {% stepper %} {% step %} **Choose an endpoint** Choose an endpoint to turn your prompt into an Elasticsearch DSL query. [/fast](/agentic-search-api/agentic-search-api.md#v2-agentic_search-fast-endpoint) is the default endpoint for Agentic Search, but if you need more accurate results, try [/reasoning](/agentic-search-api/agentic-search-api.md#v2-agentic_search-reasoning-endpoint). {% endstep %} {% step %} **Write a prompt** Let’s say you want to find senior product managers at fintech companies in London with over five years of experience. Start in Agentic Search by describing your search criteria in plain language: {% prompt description="Find Senior Product Managers at fintech prompt" %} ```markdown Find Senior Product Managers at fintech companies in London with 5+ years of experience. ``` {% endprompt %} Send your prompt to Agentic Search. With `"return_data": true`, the endpoint returns both the generated Elasticsearch DSL query and a preview of up to 20 matching records containing prompt-relevant fields. {% code title="Example request" expandable="true" %} ```json curl -X POST https://api.coresignal.com/cdapi/v2/agentic_search/fast \ -H "apikey: {API key}" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Senior Product Managers at fintech companies in London with 5+ years of experience", "return_data": true, "threshold": 0.97, "entity": "employee" }' ``` {% endcode %} {% hint style="info" %} At this point you need an API key and credits are deducted based on the endpoint you choose. {% endhint %} {% endstep %} {% step %} **Validate the query** Review the Elasticsearch DSL query, then use the result preview to check whether the returned records and prompt-relevant fields match your intended audience. If the preview records do not match your target audience, refine the natural language prompt and rerun the query. Agentic Search data mode currently returns up to 20 records, making it useful for validation before scaling the workflow. {% code title="Example response" expandable="true" %} ```json "query": {...}, "data": [ { "id": 123456789, "full_name": "John Doe", "professional_network_url": "https://www.professional-network.com/john-doe", "active_experience_title": "Senior Product Manager", "active_experience_company_id": 123456789, "company_name": "Company Name", "_score": 51.984005, "location_city": "London", "total_experience_duration_months": 113, "experience": [ { "company_industry": "Financial Services", "company_categories_and_keywords": [ "finance/banking", "finance/accounting_and_auditing", "fintech business banking", "payment", "tax", "information technology" ], "company_id": 123456789, "company_name": "Company Name", "position_title": "Senior Product Manager", "active_experience": 1 } ] }, { "id": 123456789, "full_name": "Jane Doe", "professional_network_url": "https://www.professional-network.com/jane-doe", "active_experience_title": "Product Manager", "active_experience_company_id": 11870735, "company_name": "Company Name", "_score": 51.854782, "location_city": "London", "total_experience_duration_months": 133, "experience": [ { "company_industry": "Financial Services", "company_categories_and_keywords": [ "financial technology", "apis", "banking", "financial-management", "fintech", "financial services" ], "company_id": 123456789, "company_name": "Integrated Finance", "position_title": "Senior Product Manager", "active_experience": 1 } ] }, { "id": 123456789, "full_name": "John Smith", "professional_network_url": "https://www.professional-network.com/john-smith", "active_experience_title": "Senior Product Manager", "active_experience_company_id": 12064400, "company_name": "Company Name", "_score": 51.72257, "location_city": "London", "total_experience_duration_months": 197, "experience": [ { "company_industry": "Financial Services", "company_categories_and_keywords": [ "cryptocurrency", "mobile payments", "technology", "fintech", "payments", "platform" ], "company_id": 123456789, "company_name": "Company Name", "position_title": "Senior Product Manager", "active_experience": 1 } ] }, { "id": 123456789, "full_name": "Tim Tims", "professional_network_url": "https://www.professional-network.com/tim-tims", "active_experience_title": "Senior Product Manager", "active_experience_company_id": 123456789, "company_name": "Company Name", "_score": 51.15603, "location_city": "London", "total_experience_duration_months": 309, "experience": [ { "company_industry": "Financial Services", "company_categories_and_keywords": [ "finance", "financial services", "financial-services", "financial-data", "fintech", "payments" ], "company_id": 123456789, "company_name": "Company Name.", "position_title": "Senior Product Manager", "active_experience": 1 } ] }, { "id": 123456789, "full_name": "Johnny Doe", "professional_network_url": "https://www.professional-network.com/johnny-doe", "active_experience_title": "Senior Product Manager", "active_experience_company_id": 33390655, "company_name": "Company Name", "_score": 51.11158, "location_city": "London", "total_experience_duration_months": 127, "experience": [ { "company_industry": "Financial Services", "company_categories_and_keywords": [ "payment and credit solutions", "fintech", "information technology", "payment solutions", "credit solutions", "business" ], "company_id": 33390655, "company_name": "Company Name", "position_title": "Senior Product Manager", "active_experience": 1 } ] }, .... ``` {% endcode %} {% hint style="info" %} Sample profiles contain fictionalized values for demonstration. {% endhint %} {% endstep %} {% step %} **Transition to production** Once the query is validated, reuse the Elasticsearch DSL query in production against the relevant standard Search endpoint to get all matching IDs. {% code title="Search request example" expandable="true" %} ```json curl --location 'https://api.coresignal.com/cdapi/v2/employee_multi_source/search/es_dsl' --header 'Content-Type: application/json' --header 'apikey: {API key}' '{ "query": { "bool": { "filter": [ { "term": { "is_deleted": 0 } }, { "term": { "is_parent": 1 } }, { "range": { "total_experience_duration_months": { "gte": 60 } } } ], "must": [ { "match_phrase": { "location_city": "London" } }, { "nested": { "path": "experience", "query": { "bool": { "filter": [ { "term": { "experience.active_experience": 1 } } ], "must": [ { "bool": { "must": [ { "match": { "experience.company_categories_and_keywords": { "query": "fintech", "operator": "and" } } }, { "terms": { "experience.company_industry.exact": [ "Financial Services", "Banking", "Blockchain Services", "Software Development", "Technology, Information and Internet" ] } } ] } }, { "bool": { "should": [ { "match_phrase": { "experience.position_title": "Senior Product Manager" } }, { "match_phrase": { "experience.position_title": "Senior Product Manager" } }, { "match_phrase": { "experience.position_title": "Senior Product Manager" } }, { "match_phrase": { "experience.position_title": "Senior Productmanager" } }, { "match_phrase": { "experience.position_title": "Senior Product Manager / Product Manager" } } ], "minimum_should_match": 1 } } ] } } } } ] } }, "sort": [ "_score" ] }' ``` {% endcode %} Then **Collect** (one full record) or **Bulk Collect** (many records) to get full data. Use **Collect** to retrieve one full record by ID. Enter a valid `employee_id` value and your API Key. {% code title="cURL request" expandable="true" %} ```json curl -X 'GET' \ 'https://api.coresignal.com/cdapi/v2/employee_multi_source/collect/123456780' \ -H 'accept: application/json' \ -H 'apikey: {API Key}' ``` {% endcode %} Use [Bulk Collect](/api-introduction/requests/bulk-collect.md) to retrieve many full records at scale. {% hint style="info" %} Examples are prepared using Postman, however, you can use other tools such as a terminal or any API-compatible application. {% endhint %} {% endstep %} {% endstepper %} ### Case B: Starting from an API playground The API Playground provides a visual interface within the dashboard for interactively designing queries across Employee, Company, or Job datasets. With one request, the API Playground returns multiple matching IDs, letting you evaluate the prompt's accuracy and whether it needs refining. {% stepper %} {% step %} **Open API playground** Navigate to the Coresignal's dashboard and select an API that best fits your use case (e.g. Employee APIs), then select API playground. {% endstep %} {% step %} **Write a prompt** Start with a natural-language prompt in the API Playground. For example, type: {% prompt description="Find individuals in Spain with both UX and UI skills." %} ```markdown Find individuals in Spain with both UX and UI skills. ``` {% endprompt %} Right after submitting your prompt, you will receive: * The generated Elasticsearch DSL request structure (which you can copy directly into your API integration code) is readily available in the Search request field {% code title="Generated query sample" expandable="true" %} ```json { "query": { "bool": { "filter": [ { "term": { "is_deleted": 0 } }, { "term": { "is_parent": 1 } }, { "terms": { "location_country_iso2": [ "ES" ] } } ], "must": [ { "bool": { "must": [ { "bool": { "should": [ { "match": { "summary": { "query": "UX", "operator": "and" } } }, { "match": { "headline": { "query": "UX", "operator": "and" } } } ], "minimum_should_match": 1 } }, { "bool": { "should": [ { "match": { "summary": { "query": "UI", "operator": "and" } } }, { "match": { "headline": { "query": "UI", "operator": "and" } } } ], "minimum_should_match": 1 } } ] } } ] } }, "sort": [ "_score" ] } ``` {% endcode %} * All matching record IDs * One full sample record preview {% endstep %} {% step %} **Move to production** Copy the generated DSL request directly into your integration. The Playground provides pre-formatted snippets in cURL, Python, Node.js, Ruby, and PHP. To retrieve full profile data for matching records: * **Collect (for single record):** enter a valid `employee_id` value and your API Key into the request {% code title="Collect request example" expandable="true" %} ```json curl -X 'GET' \ 'https://api.coresignal.com/cdapi/v2/employee_multi_source/collect/{123456780}' \ -H 'accept: application/json' \ -H 'apikey: {API Key}' ``` {% endcode %} * **Bulk Collect:** supply the list of IDs directly to the Bulk Collect endpoint to fetch full profiles in a single request. {% endstep %} {% endstepper %} ### Choosing between Agentic Search and API Playground Depending on your use case, you might prefer using Agent Search or API Playground. Here is what each is best for: * Case A (Agentic Search API): suited for programmatic query generation within automated data pipelines and backend applications. * Case B (API Playground): suited for manual exploration, prototyping, and schema validation before writing integration code. ### Authentication: dashboard to terminal All requests described in this guide, across Search, Collect, Bulk Collect, and Agentic Search, require an API key passed via the [API Key](/self-service/account-management/authentication-and-api-keys.md) request header. You can get your API Key from Coresignal’s [self-service platform](https://dashboard.coresignal.com/home). {% code title="Authorization header" expandable="true" %} ```json -H “apikey: {API_Key}” ``` {% endcode %} ### Hardening for production To ensure automated integrations run reliably at scale, there are several steps you can incorporate to ensure smooth production. #### Two-step retrieval flow Implement two-step retrieval flow to efficiently fetch data at scale: 1. Run Search request using your validated Elasticsearch DSL to retrieve matching entity IDs 2. Pass those IDs into Collect (for individual records) or Bulk Collect (for batches) to pull complete entity objects #### Design around limits To avoid additional roadblocks keep in mind limits and restrictions:
* Bulk Collect endpoints accept up to 10,000 IDs per request. For result sets exceeding 10,000 IDs, split the array into multiple batch requests. * [Credits](/api-introduction/credits.md) are deducted per delivered record and per Agentic Search query. Monitor the `x-credits-remaining` response header across both manual testing and production scripts to avoid pipeline interruptions. #### Error handling When testing or running queries, you may encounter the following scenarios and errors: * No results (post response field displays `0`) – means the request succeeded but matched no records. To fix this issue, broaden search criteria, check for typos, and verify that the entity exists. * Failed requests – this error means the system cannot process your query. To fix this, remove requests for private data and ensure your prompt is clear and descriptive. You can also check our page for a list of common [response codes](/api-introduction/response-codes.md) to help identify the problem. ### Related reading | Resource | Text Description | | ---------------------------------------------------------------- | -------------------------------------------------------------------------- | | [Semantic Search](/api-introduction/requests/semantic-search.md) | Expand Elasticsearch DSL queries to include titles with equivalent meaning | | [Bulk Collect](/api-introduction/requests/bulk-collect.md) | A guide on retrieving large sets of data in a single request | | [Collect](/guides/collect-enrich-or-bulk-collect.md) | A detailed guide on Collect Endpoint and data collection | --- # 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/turning-a-natural-language-query-into-an-api-integration.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.