Turning a Natural Language Query Into an API Integration

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 and Agentic Search 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.

1

Choose an endpoint

Choose an endpoint to turn your prompt into an Elasticsearch DSL query. /fast is the default endpoint for Agentic Search, but if you need more accurate results, try /reasoning.

2

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:

Find Senior Product Managers at fintech prompt

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.

Example request

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"
}'

At this point you need an API key and credits are deducted based on the endpoint you choose.

3

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.

Example response

"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
        }
      ]
    },
    ....

Sample profiles contain fictionalized values for demonstration.

4

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.

Search request example

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"
  ]
}'

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.

cURL request

curl -X 'GET' \
'https://api.coresignal.com/cdapi/v2/employee_multi_source/collect/123456780' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}'

Use Bulk Collect to retrieve many full records at scale.

Examples are prepared using Postman, however, you can use other tools such as a terminal or any API-compatible application.

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.

1

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.

2

Write a prompt

Start with a natural-language prompt in the API Playground. For example, type:

Find individuals in Spain with both UX and UI skills.

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

Generated query sample

{
  "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"
  ]
}

• All matching record IDs

• One full sample record preview

3

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

Collect request example

curl -X 'GET' \
'https://api.coresignal.com/cdapi/v2/employee_multi_source/collect/{123456780}' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}'

• Bulk Collect: supply the list of IDs directly to the Bulk Collect endpoint to fetch full profiles in a single request.

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 request header. You can get your API Key from Coresignal’s self-service platform.

Authorization header

-H “apikey: {API_Key}”

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 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 to help identify the problem.

Related reading

Resource	Text Description
Semantic Search	Expand Elasticsearch DSL queries to include titles with equivalent meaning
Bulk Collect	A guide on retrieving large sets of data in a single request
Collect	A detailed guide on Collect Endpoint and data collection