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.

Vocabularies

Learn about the containers that organize concepts into terminology systems

Clinical Terminology Standards

Understand the major terminology standards and their concept structures

Coding Data Type

See how concepts are represented in FHIR data structures

Field Validation

Explore how concepts enable clinical data validation
Ready to work with concepts? Start with the Concept API reference to manage your clinical concepts.