/

phenoml.comGet API keys

Submit feedback on extraction results

POST/construe/feedback

Submits user feedback on results from the Construe extraction endpoint. Feedback includes the full extraction result received and the result the user expected.

RequiresBearerauthentication

Body parameters

textstringrequired

The natural language text that was used for code extraction

received_resultobjectrequired

systemobjectrequired

namestringoptional

Code system name. Can be a built-in system or a custom system name.

Built-in systems:

SNOMED_CT_US_LITE - version 20240901
RXNORM - version 11042024
ICD-10-CM - version 2025
ICD-10-PCS - version 2025
LOINC - version 2.78
HPO - version 2025
CPT - version 2025

Custom systems:

Any valid system name uploaded via /construe/upload. Requires a paid plan.

Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.

versionstringoptional

Code system version. Must match the version available in your environment.

codesobject[]required

codestringrequired

The extracted code

descriptionstringrequired

Short description of the code

validbooleanrequired

Whether the code passed validation. Always true unless include_invalid is set to true, in which case invalid codes will have this set to false.

reasonstringoptional

Explanation for why this code was extracted (if include_rationale is true)

is_ancestorbooleanoptional

Whether this code is an ancestor (parent) of an extracted code rather than directly extracted. Only present when include_ancestors is true.

citationsobject[]optional

Source text references showing where this code was found in the input. Only present when include_citations is true and chunking method supports it. Ancestor codes do not receive citations.

categoriesobject[]optional

Higher-level groupings the extracted code belongs to (e.g. HPO category terms). Only populated by full-extraction chunking methods such as "fasthpocr".

expected_resultobjectrequired

systemobjectrequired

namestringoptional

Code system name. Can be a built-in system or a custom system name.

Built-in systems:

SNOMED_CT_US_LITE - version 20240901
RXNORM - version 11042024
ICD-10-CM - version 2025
ICD-10-PCS - version 2025
LOINC - version 2.78
HPO - version 2025
CPT - version 2025

Custom systems:

Any valid system name uploaded via /construe/upload. Requires a paid plan.

Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.

versionstringoptional

Code system version. Must match the version available in your environment.

codesobject[]required

codestringrequired

The extracted code

descriptionstringrequired

Short description of the code

validbooleanrequired

Whether the code passed validation. Always true unless include_invalid is set to true, in which case invalid codes will have this set to false.

reasonstringoptional

Explanation for why this code was extracted (if include_rationale is true)

is_ancestorbooleanoptional

Whether this code is an ancestor (parent) of an extracted code rather than directly extracted. Only present when include_ancestors is true.

citationsobject[]optional

Source text references showing where this code was found in the input. Only present when include_citations is true and chunking method supports it. Ancestor codes do not receive citations.

categoriesobject[]optional

Higher-level groupings the extracted code belongs to (e.g. HPO category terms). Only populated by full-extraction chunking methods such as "fasthpocr".

detailstringoptional

Optional details explaining the feedback

Returns

Feedback saved successfully

Response fields

idstringrequired

The ID of the saved feedback

POSTRequest

curl -X POST 'https://experiment.app.pheno.ml/construe/feedback' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "Patient has type 2 diabetes with hyperglycemia",
  "received_result": {
    "system": {
      "name": "SNOMED_CT_US_LITE",
      "version": "20240901"
    },
    "codes": [
      {
        "code": "195967001",
        "description": "Asthma",
        "valid": true,
        "reason": "example",
        "is_ancestor": true,
        "citations": [
          {
            "text": "Patient has type 2 diabetes",
            "begin_offset": 0,
            "end_offset": 27
          }
        ],
        "categories": [
          {
            "uri": "HP:0025142",
            "label": "Constitutional symptom"
          }
        ]
      }
    ]
  },
  "expected_result": {},
  "detail": "Expected code X instead because ..."
}'

201 CreatedResponse

{
  "id": "abc123def456"
}