> 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/api-introduction/requests/semantic-search.md).

# Semantic Search

Semantic search expands [Elasticsearch DSL](/api-introduction/requests/elasticsearch-dsl.md) queries to include job titles with equivalent meaning, even when the wording differs. A search for "Software Engineer" can automatically surface results for "Software Developer" or "Senior Software Engineer" without modifying the query format.

It is activated via dedicated `/semantic_search/es_dsl` endpoints – drop-in replacements for the standard `/search/es_dsl` endpoints. The minimum confidence score for synonym inclusion is controlled by the `threshold` parameter.

{% hint style="info" %}
Semantic search endpoints have higher latency than their standard counterparts, as each request triggers an additional model call before query execution.
{% endhint %}

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Same request format</strong></td><td>No changes to Elasticsearch DSL query structure. Drop-in replacement for existing <code>/search/es_dsl</code> endpoints.</td></tr><tr><td><strong>Broader recall</strong></td><td>Semantically equivalent titles are matched automatically, reducing gaps caused by wording variations across profiles and postings.</td></tr><tr><td><strong>Full transparency</strong></td><td>Every injected synonym is listed in the response <code>metadata</code> with its confidence score and boost status.</td></tr></tbody></table>

## Endpoints

Each semantic search endpoint request matches standard multi-source `/search/es_dsl` endpoints, with synonym search performed before executing the query.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Multi-source Company API</td><td><a href="/pages/ClUpiETryZ8jSjWtLo8S">/pages/ClUpiETryZ8jSjWtLo8S</a></td></tr><tr><td>Multi-source Employee API</td><td><a href="/pages/96NHtqqAukl1f4WwmTZJ">/pages/96NHtqqAukl1f4WwmTZJ</a></td></tr><tr><td>Multi-source Jobs API</td><td><a href="/pages/RV8IUvrG1Ho0zZpzERN9">/pages/RV8IUvrG1Ho0zZpzERN9</a></td></tr></tbody></table>

| Semantic search endpoint                                | Regular search endpoint                        |
| ------------------------------------------------------- | ---------------------------------------------- |
| POST `/v2/company_multi_source/semantic_search/es_dsl`  | POST `/v2/company_multi_source/search/es_dsl`  |
| POST `/v2/employee_multi_source/semantic_search/es_dsl` | POST `/v2/employee_multi_source/search/es_dsl` |
| POST `/v2/job_multi_source/semantic_search/es_dsl`      | POST `/v2/job_multi_source/search/es_dsl`      |

## Supported fields for semantic search

Synonym injection is triggered when a `match_phrase` clause targets one of the data fields below. Other fields pass through unchanged.

| Endpoint                                                | Data field                                                                                                           |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| POST `/v2/company_multi_source/semantic_search/es_dsl`  | `active_job_postings[].job_posting_title`                                                                            |
| POST `/v2/employee_multi_source/semantic_search/es_dsl` | <p><code>active\_experience\_title</code><br><code>experience\[].position\_title</code><br><code>headline</code></p> |
| POST `/v2/job_multi_source/semantic_search/es_dsl`      | `title`                                                                                                              |

## Request parameters

Control semantic search with additional request parameters to get more relevant results.

| Parameter   | Type  | Default value | Description                                                       |
| ----------- | ----- | ------------- | ----------------------------------------------------------------- |
| `threshold` | Float | `0.9`         | Minimum confidence score required for a synonym to be injected    |
| `boost`     | Float | `0.1`         | Controls the weight of seniority signals in the relevance scoring |

## How it works

{% stepper %}
{% step %}

### Send request

Send an Elasticsearch DSL query with semantic search endpoint. Use an identical format to existing `/search/es_dsl` endpoints. No changes to request structure are required.
{% endstep %}

{% step %}

### Scanning data fields

The query is scanned for `match_phrase` clauses targeting supported data fields.
{% endstep %}

{% step %}

### Looking for a match

If a match is found, the semantic search model is called. Synonyms at or above the configured `threshold` are injected as an expanded `should` clause in the query.
{% endstep %}

{% step %}

### Executing the query

The enriched query is forwarded to Elasticsearch DSL and executed.
{% endstep %}

{% step %}

### Getting a response

The response includes a `metadata` block documenting what was injected and standard Elasticsearch DSL results (IDs) in `results` field. If no eligible `match_phrase` is detected, the query is forwarded as-is and `metadata[].synonyms_injected` is returned as an empty array.
{% endstep %}
{% endstepper %}

## Response

Response is similar to existing `/search/es_dsl` endpoints with an additional `metadata` block that includes information about applied semantic search and IDs presented in `results` field.

<table data-search="false"><thead><tr><th>Field</th><th>Description</th><th>Data type</th></tr></thead><tbody><tr><td><code>metadata</code></td><td>Information about applied semantic search </td><td>Array of struct</td></tr><tr><td><code>metadata[].threshold</code></td><td>Value set in the request</td><td>Float</td></tr><tr><td><code>metadata[].synonyms_injected</code></td><td>List of added synonyms to the query. If no synonyms were injected – returned as an empty array</td><td>Array of struct</td></tr><tr><td><code>metadata[].synonyms_injected[].field</code></td><td>Data field where original and synonym values were applied</td><td>String</td></tr><tr><td><code>metadata[].synonyms_injected[].original</code></td><td>Original field value</td><td>String</td></tr><tr><td><code>metadata[].synonyms_injected[].synonym</code></td><td>Added synonym value based on the <code>original</code> value and <code>threshold</code></td><td>String</td></tr><tr><td><code>metadata[].synonyms_injected[].score</code></td><td>Confidence score</td><td>Float</td></tr><tr><td><code>metadata[].synonyms_injected[].boosted</code></td><td>Identifies whether the <code>boost</code> was applied</td><td>Boolean</td></tr><tr><td><code>results</code></td><td>Returned matching IDs</td><td>Array of integers</td></tr></tbody></table>

{% code title="Response example" overflow="wrap" %}

```json
{
  "metadata": {
    "threshold": 0.9,
    "synonyms_injected": [
      {
        "field": "active_experience_title",
        "original": "Software Engineer",
        "synonym": "Senior Software Engineer",
        "score": 0.97,
        "boosted": true
      },
      {
        "field": "active_experience_title",
        "original": "Software Engineer",
        "synonym": "Software Developer",
        "score": 0.96,
        "boosted": false
      }
    ]
  },
  "results": [
    10000,
    10001,
    10002
  ]
}
```

{% endcode %}


---

# 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/api-introduction/requests/semantic-search.md?ask=<question>&goal=<endgoal>
```

`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.