Skip to main content

Concepts

A concept represents a single clinical idea or entity within a vocabulary. Each concept has a unique code within its vocabulary and includes human-readable descriptions, making it the fundamental building block of clinical terminologies.

What is a Concept?

Concepts are the individual units of meaning within terminology systems. They represent specific clinical ideas, such as diseases, procedures, medications, or observations, in a standardized and machine-readable format. Core characteristics:
  • Unique identification: Each concept has a unique code within its vocabulary
  • Human-readable: Includes display text and definitions for clinical users
  • Multilingual support: Can include translations and alternative names

Concept Structure

A concept in Clinia contains the following properties:
PropertyTypeDescription
vocabularyKeycodeIdentifier of the containing vocabulary (read-only, provided as a URL parameter)
codecodeUnique identifier within the vocabulary (read-only)
definitionsymbolDetailed explanation of the concept’s clinical meaning
designationobjectAlternative names and translations in different languages
Example concept:
{
  "code": "44054006",
  "definition": "A form of diabetes mellitus characterized by insulin resistance and relative insulin deficiency",
  "designation": {
    "en": "Type 2 diabetes mellitus",
    "fr": "Diabète de type 2",
    "es": "Diabetes mellitus tipo 2"
  }
}

Managing Concepts

Creating a Concept

Use the upsert concept endpoint to create or update concepts:
curl -X PUT "https://$CLINIA_WORKSPACE/terminology/v1/vocabularies/{vocabularyKey}/concepts/{conceptCode}" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": "A chronic metabolic disorder characterized by high blood glucose levels",
    "designation": {
      "en": "Diabetes mellitus",
      "fr": "Diabète sucré"
    }
  }'

Retrieving Concepts

Get specific concepts by their code:
curl -X GET "https://$CLINIA_WORKSPACE/terminology/v1/vocabularies/{vocabularyKey}/concepts/{conceptCode}" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"

Searching Concepts

Use the concept query endpoint to perform concept resolution, using Clinia’s operators and semantic search capabilities:
curl -X POST "https://$CLINIA_WORKSPACE/terminology/v1/vocabularies/*/concepts/query" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match": {
        "designation.en": {
          "value": "diabetes",
          "type": "word"
        }
      }
    }
  }'

Bulk Operations

Efficiently manage large sets of concepts using bulk operations:
curl -X POST "https://$CLINIA_WORKSPACE/terminology/v1/vocabularies/{vocabularyKey}/concepts/bulk" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "action": "UPSERT",
        "upsert": {
          "code": "123456789",
          "definition": "Example clinical concept",
          "designation": {
            "en": "Example Concept"
          }
        }
      }
    ]
  }'

Concept Validation

Concepts are central to field validation at Clinia. Learn how to do vocabulary-based validation here.
Ready to work with concepts? Start with the Concept API reference to manage your clinical concepts.
I