Transform Text to JSON

Transforms unstructured text into structured JSON according to a provided schema. This utility endpoint extracts specific data patterns from free-form content.

POST /v1/utils/text-to-json

Transform unstructured text to structured JSON

cURL

curl --request POST \
  --url https://api.sully.ai/v1/utils/text-to-json \
  --header 'Content-Type: application/json' \
  --header 'X-ACCOUNT-ID: <api-key>' \
  --header 'X-API-KEY: <api-key>' \
  --data @- <<EOF
{
  "text": "Patient is a 45-year-old male presenting with chest pain...",
  "schema": {
    "type": "object",
    "description": "Structured clinical summary extracted from a patient encounter note",
    "properties": {
      "patientInfo": {
        "type": "object",
        "description": "Demographic details about the patient mentioned in the note",
        "properties": {
          "age": {
            "type": "number",
            "description": "Patient age in years as a number, e.g. 45"
          },
          "gender": {
            "type": "string",
            "description": "Patient gender as stated or implied in the note"
          },
          "allergies": {
            "type": [
              "array",
              "null"
            ],
            "description": "List of documented allergies; null if none mentioned",
            "items": {
              "type": "string",
              "description": "A single allergy (drug, food, or environmental)"
            }
          }
        },
        "required": [
          "age",
          "gender",
          "allergies"
        ]
      },
      "symptoms": {
        "type": "array",
        "description": "Active symptoms the patient is currently experiencing or reporting",
        "items": {
          "type": "string",
          "description": "A single symptom in plain language, e.g. 'chest pain'"
        }
      },
      "diagnosis": {
        "type": "array",
        "description": "Only confirmed diagnoses — do not include suspected or rule-out conditions",
        "items": {
          "type": "string",
          "description": "A single confirmed diagnosis"
        }
      },
      "severityLevel": {
        "type": "string",
        "description": "Overall clinical severity based on the presenting condition and vitals",
        "enum": [
          "mild",
          "moderate",
          "severe",
          "critical"
        ]
      },
      "notes": {
        "type": [
          "string",
          "null"
        ],
        "description": "Additional clinical notes, provider observations, or contextual information not captured elsewhere"
      }
    },
    "required": [
      "patientInfo",
      "symptoms",
      "diagnosis",
      "severityLevel",
      "notes"
    ]
  }
}
EOF

200

{
  "data": {
    "patientInfo": {
      "age": 45,
      "gender": "male",
      "allergies": null
    },
    "symptoms": [
      "chest pain"
    ],
    "diagnosis": [],
    "severityLevel": "moderate",
    "notes": null
  }
}

Authorizations

X-API-KEY · string · header · required

X-ACCOUNT-ID · string · header · required

Body

application/json

Text and schema for transformation

Request payload for transforming unstructured text into structured JSON

text · string · required

Unstructured text to transform

Example:

"Patient is a 45-year-old male presenting with chest pain..."

schema · object · required

JSON Schema defining the structure to extract from the text. Use description fields on properties to guide the model — they act as extraction instructions (e.g. "only include confirmed diagnoses, not suspected ones").

Example:

{
  "type": "object",
  "description": "Structured clinical summary extracted from a patient encounter note",
  "properties": {
    "patientInfo": {
      "type": "object",
      "description": "Demographic details about the patient mentioned in the note",
      "properties": {
        "age": {
          "type": "number",
          "description": "Patient age in years as a number, e.g. 45"
        },
        "gender": {
          "type": "string",
          "description": "Patient gender as stated or implied in the note"
        },
        "allergies": {
          "type": ["array", "null"],
          "description": "List of documented allergies; null if none mentioned",
          "items": {
            "type": "string",
            "description": "A single allergy (drug, food, or environmental)"
          }
        }
      },
      "required": ["age", "gender", "allergies"]
    },
    "symptoms": {
      "type": "array",
      "description": "Active symptoms the patient is currently experiencing or reporting",
      "items": {
        "type": "string",
        "description": "A single symptom in plain language, e.g. 'chest pain'"
      }
    },
    "diagnosis": {
      "type": "array",
      "description": "Only confirmed diagnoses — do not include suspected or rule-out conditions",
      "items": {
        "type": "string",
        "description": "A single confirmed diagnosis"
      }
    },
    "severityLevel": {
      "type": "string",
      "description": "Overall clinical severity based on the presenting condition and vitals",
      "enum": ["mild", "moderate", "severe", "critical"]
    },
    "notes": {
      "type": ["string", "null"],
      "description": "Additional clinical notes, provider observations, or contextual information not captured elsewhere"
    }
  },
  "required": [
    "patientInfo",
    "symptoms",
    "diagnosis",
    "severityLevel",
    "notes"
  ]
}

Response

200

application/json

JSON data extracted from text

Response containing the structured JSON data extracted from text

data · object

Extracted structured data that conforms to the provided schema

Example:

{
  "patientInfo": {
    "age": 45,
    "gender": "male",
    "allergies": null
  },
  "symptoms": ["chest pain"],
  "diagnosis": [],
  "severityLevel": "moderate",
  "notes": null
}