Search OMOP concepts

curl --request POST \
  --url https://api.v2.healthproximate.com/api/v1/search/ \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "<string>",
  "vocabularies": [
    "<string>"
  ],
  "domain_id": "<string>",
  "top_k": 10,
  "find_relationship": false,
  "relationship_filters": {},
  "search_type": "websearch",
  "language": "english",
  "use_search_rank": true,
  "rank_normalization": 0,
  "min_relevance": -2,
  "include_bridges": false,
  "filter_to_input_vocab": true
}
'

import requests

url = "https://api.v2.healthproximate.com/api/v1/search/"

payload = {
    "query": "<string>",
    "vocabularies": ["<string>"],
    "domain_id": "<string>",
    "top_k": 10,
    "find_relationship": False,
    "relationship_filters": {},
    "search_type": "websearch",
    "language": "english",
    "use_search_rank": True,
    "rank_normalization": 0,
    "min_relevance": -2,
    "include_bridges": False,
    "filter_to_input_vocab": True
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    query: '<string>',
    vocabularies: ['<string>'],
    domain_id: '<string>',
    top_k: 10,
    find_relationship: false,
    relationship_filters: {},
    search_type: 'websearch',
    language: 'english',
    use_search_rank: true,
    rank_normalization: 0,
    min_relevance: -2,
    include_bridges: false,
    filter_to_input_vocab: true
  })
};

fetch('https://api.v2.healthproximate.com/api/v1/search/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.v2.healthproximate.com/api/v1/search/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'query' => '<string>',
    'vocabularies' => [
        '<string>'
    ],
    'domain_id' => '<string>',
    'top_k' => 10,
    'find_relationship' => false,
    'relationship_filters' => [
        
    ],
    'search_type' => 'websearch',
    'language' => 'english',
    'use_search_rank' => true,
    'rank_normalization' => 0,
    'min_relevance' => -2,
    'include_bridges' => false,
    'filter_to_input_vocab' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.v2.healthproximate.com/api/v1/search/"

	payload := strings.NewReader("{\n  \"query\": \"<string>\",\n  \"vocabularies\": [\n    \"<string>\"\n  ],\n  \"domain_id\": \"<string>\",\n  \"top_k\": 10,\n  \"find_relationship\": false,\n  \"relationship_filters\": {},\n  \"search_type\": \"websearch\",\n  \"language\": \"english\",\n  \"use_search_rank\": true,\n  \"rank_normalization\": 0,\n  \"min_relevance\": -2,\n  \"include_bridges\": false,\n  \"filter_to_input_vocab\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.v2.healthproximate.com/api/v1/search/")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"<string>\",\n  \"vocabularies\": [\n    \"<string>\"\n  ],\n  \"domain_id\": \"<string>\",\n  \"top_k\": 10,\n  \"find_relationship\": false,\n  \"relationship_filters\": {},\n  \"search_type\": \"websearch\",\n  \"language\": \"english\",\n  \"use_search_rank\": true,\n  \"rank_normalization\": 0,\n  \"min_relevance\": -2,\n  \"include_bridges\": false,\n  \"filter_to_input_vocab\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.v2.healthproximate.com/api/v1/search/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"<string>\",\n  \"vocabularies\": [\n    \"<string>\"\n  ],\n  \"domain_id\": \"<string>\",\n  \"top_k\": 10,\n  \"find_relationship\": false,\n  \"relationship_filters\": {},\n  \"search_type\": \"websearch\",\n  \"language\": \"english\",\n  \"use_search_rank\": true,\n  \"rank_normalization\": 0,\n  \"min_relevance\": -2,\n  \"include_bridges\": false,\n  \"filter_to_input_vocab\": true\n}"

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "concept_id": 123,
      "concept_name": "<string>",
      "concept_code": "<string>",
      "vocabulary_id": "<string>",
      "concept_class_id": "<string>",
      "similarity": 123,
      "graph_score": 123,
      "combined_score": 123,
      "score": 123,
      "is_bridge": true,
      "parents": [
        {
          "parent_concept_id": 123,
          "parent_concept_code": "<string>",
          "parent_concept_name": "<string>"
        }
      ]
    }
  ],
  "metadata": {
    "query": "<string>",
    "vocabularies_searched": [
      "<string>"
    ],
    "domain_id": "<string>",
    "total_results": 123,
    "find_relationship": true,
    "search_mode": "hybrid",
    "requested_search_mode": "hybrid",
    "profile": "<string>",
    "include_bridges": true,
    "filter_to_input_vocab": true,
    "fts_options": {
      "search_type": "<string>",
      "language": "<string>",
      "use_search_rank": true,
      "rank_normalization": 123
    },
    "fallback_reason": "<string>"
  }
}

Clinical coding

Search OMOP concepts

Searches OMOP concepts across multiple medical vocabularies (ICD10, SNOMED, CPT4, etc.) with optional domain filtering. Returns matching concepts with metadata about the search.

Supports both JWT (Authorization: Bearer) and API key (X-API-Key) authentication.

Supported vocabularies: ICD10, ICD10CM, ICD10PCS, ICD9CM, ICD9Proc, SNOMED, CPT4, HCPCS, RxNorm, RxNorm Extension, OPCS4, DRG.

A search with no vocabularies filter scans ICD10, ICD10CM, ICD10PCS, ICD9CM, ICD9Proc, SNOMED, CPT4, HCPCS, RxNorm, RxNorm Extension. DRG, OPCS4 are supported but must be requested by name.

Supported domains: Condition, Procedure, Drug, Measurement, Observation, Device, Specimen.

POST

api

Search OMOP concepts

curl --request POST \
  --url https://api.v2.healthproximate.com/api/v1/search/ \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "<string>",
  "vocabularies": [
    "<string>"
  ],
  "domain_id": "<string>",
  "top_k": 10,
  "find_relationship": false,
  "relationship_filters": {},
  "search_type": "websearch",
  "language": "english",
  "use_search_rank": true,
  "rank_normalization": 0,
  "min_relevance": -2,
  "include_bridges": false,
  "filter_to_input_vocab": true
}
'

import requests

url = "https://api.v2.healthproximate.com/api/v1/search/"

payload = {
    "query": "<string>",
    "vocabularies": ["<string>"],
    "domain_id": "<string>",
    "top_k": 10,
    "find_relationship": False,
    "relationship_filters": {},
    "search_type": "websearch",
    "language": "english",
    "use_search_rank": True,
    "rank_normalization": 0,
    "min_relevance": -2,
    "include_bridges": False,
    "filter_to_input_vocab": True
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    query: '<string>',
    vocabularies: ['<string>'],
    domain_id: '<string>',
    top_k: 10,
    find_relationship: false,
    relationship_filters: {},
    search_type: 'websearch',
    language: 'english',
    use_search_rank: true,
    rank_normalization: 0,
    min_relevance: -2,
    include_bridges: false,
    filter_to_input_vocab: true
  })
};

fetch('https://api.v2.healthproximate.com/api/v1/search/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.v2.healthproximate.com/api/v1/search/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'query' => '<string>',
    'vocabularies' => [
        '<string>'
    ],
    'domain_id' => '<string>',
    'top_k' => 10,
    'find_relationship' => false,
    'relationship_filters' => [
        
    ],
    'search_type' => 'websearch',
    'language' => 'english',
    'use_search_rank' => true,
    'rank_normalization' => 0,
    'min_relevance' => -2,
    'include_bridges' => false,
    'filter_to_input_vocab' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.v2.healthproximate.com/api/v1/search/"

	payload := strings.NewReader("{\n  \"query\": \"<string>\",\n  \"vocabularies\": [\n    \"<string>\"\n  ],\n  \"domain_id\": \"<string>\",\n  \"top_k\": 10,\n  \"find_relationship\": false,\n  \"relationship_filters\": {},\n  \"search_type\": \"websearch\",\n  \"language\": \"english\",\n  \"use_search_rank\": true,\n  \"rank_normalization\": 0,\n  \"min_relevance\": -2,\n  \"include_bridges\": false,\n  \"filter_to_input_vocab\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.v2.healthproximate.com/api/v1/search/")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"<string>\",\n  \"vocabularies\": [\n    \"<string>\"\n  ],\n  \"domain_id\": \"<string>\",\n  \"top_k\": 10,\n  \"find_relationship\": false,\n  \"relationship_filters\": {},\n  \"search_type\": \"websearch\",\n  \"language\": \"english\",\n  \"use_search_rank\": true,\n  \"rank_normalization\": 0,\n  \"min_relevance\": -2,\n  \"include_bridges\": false,\n  \"filter_to_input_vocab\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.v2.healthproximate.com/api/v1/search/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"<string>\",\n  \"vocabularies\": [\n    \"<string>\"\n  ],\n  \"domain_id\": \"<string>\",\n  \"top_k\": 10,\n  \"find_relationship\": false,\n  \"relationship_filters\": {},\n  \"search_type\": \"websearch\",\n  \"language\": \"english\",\n  \"use_search_rank\": true,\n  \"rank_normalization\": 0,\n  \"min_relevance\": -2,\n  \"include_bridges\": false,\n  \"filter_to_input_vocab\": true\n}"

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "concept_id": 123,
      "concept_name": "<string>",
      "concept_code": "<string>",
      "vocabulary_id": "<string>",
      "concept_class_id": "<string>",
      "similarity": 123,
      "graph_score": 123,
      "combined_score": 123,
      "score": 123,
      "is_bridge": true,
      "parents": [
        {
          "parent_concept_id": 123,
          "parent_concept_code": "<string>",
          "parent_concept_name": "<string>"
        }
      ]
    }
  ],
  "metadata": {
    "query": "<string>",
    "vocabularies_searched": [
      "<string>"
    ],
    "domain_id": "<string>",
    "total_results": 123,
    "find_relationship": true,
    "search_mode": "hybrid",
    "requested_search_mode": "hybrid",
    "profile": "<string>",
    "include_bridges": true,
    "filter_to_input_vocab": true,
    "fts_options": {
      "search_type": "<string>",
      "language": "<string>",
      "use_search_rank": true,
      "rank_normalization": 123
    },
    "fallback_reason": "<string>"
  }
}

Authorizations

X-API-Key

string

header

required

API key for organization authentication. Obtain from the organization settings or API key management endpoint.

Query Parameters

profile

enum<string>

Profile preset that bundles sensible defaults for a use case. mapping — find equivalent codes in the requested vocabularies (2-hop graph traversal, vocab-filtered, no bridges). explore — show the full graph neighborhood (3-hop, includes SNOMED bridge concepts, no vocab filter, no quality gate). hybrid — plain text search, no graph. Individual params in the request body override profile defaults.

Available options:

explore,

hybrid,

mapping

string

Search query string (e.g. 'diabetes', 'appendectomy'). Can also be supplied in the request body as query (one of q or query is required).

response_format

enum<string>

default:json

Response format. 'json' (default) returns structured JSON. 'llm' returns compact markdown tables (text/markdown) optimized for LLM consumption. When 'llm', the response body is markdown text rather than the JSON schema shown below.

Available options:

json,

llm

search_mode

enum<string>

default:hybrid

Search strategy. hybrid uses RRF+reranking (dense + sparse fusion); graph uses OMOP graph traversal for cross-vocabulary and hierarchical expansion. Overridden by the profile preset when both are set.

Available options:

graph,

hybrid

Body

query

string

required

Search query (e.g., 'diabetes', 'appendectomy')

Minimum string length: 1

vocabularies

string[]

List of vocabularies to search (e.g., ['ICD10', 'SNOMED']). If not provided, searches all.

Minimum string length: 1

domain_id

string

Filter by domain (e.g., 'Condition', 'Procedure')

Minimum string length: 1

top_k

integer

default:10

Number of results to return (1-100)

Required range: 1 <= x <= 100

find_relationship

boolean

default:false

If true, fetch 'Is a' relationships (parent concepts) for each result

relationship_filters

object

Additional filters for ConceptRelationship query. Allowed keys: concept_id_2__concept_class_id, concept_id_2__concept_class_id__in, concept_id_2__vocabulary_id, concept_id_2__vocabulary_id__in, concept_id_2__domain_id, concept_id_2__domain_id__in

Show child attributes

search_type

enum<string>

default:websearch

FTS search type: plain (simple word match), phrase (exact phrase), raw (tsquery syntax), websearch (web-style with +/-)

plain - plain
phrase - phrase
raw - raw
websearch - websearch

Available options:

plain,

phrase,

raw,

websearch

language

string

default:english

PostgreSQL text search configuration (e.g., 'english', 'simple', 'french')

Minimum string length: 1

use_search_rank

boolean

default:true

Use SearchRank for ordering FTS results by relevance

rank_normalization

integer

default:0

SearchRank normalization flags (0-31). See PostgreSQL docs for details.

min_relevance

number<double> | null

default:-2

Cross-encoder logit threshold. Results scoring below this are dropped before being returned. ms-marco-MiniLM-L-6-v2 produces logits roughly in [-15, +15]; ~0 is the irrelevant/relevant boundary. Default -2.0 is permissive but blocks the 'no good match anywhere' case. Pass null to disable filtering and always return up to top_k results regardless of quality.

include_bridges

boolean

default:false

Graph mode only. When True, surface the SNOMED-style standard 'bridge' concepts used for 2-hop Maps-to traversal (each marked is_bridge: true in the response). Useful for showing the user why a non-standard code was suggested. Default False.

filter_to_input_vocab

boolean

default:true

Graph mode only. When True (default), restrict results to the vocabularies in the vocabularies filter. Set False to allow cross-vocab graph neighbors (e.g. for an LLM-agent profile).

Response

Search results with metadata

results

object[]

required

Show child attributes

metadata

object

required

Show child attributes

Get started

Gateway

Clinical coding

DRG

Search OMOP concepts

Authorizations

Query Parameters

Body

Response