/

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:

CPT
HCPCS
HPO
ICD-10
ICD-10-CM
ICD-10-PCS
LOINC
RXNORM
SNOMED_CT_US
SNOMED_CT_US_LITE

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

Specific code system version.

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:

CPT
HCPCS
HPO
ICD-10
ICD-10-CM
ICD-10-PCS
LOINC
RXNORM
SNOMED_CT_US
SNOMED_CT_US_LITE

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

Specific code system version.

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

# Get authentication token
PHENOML_TOKEN=$(curl -X POST "https://experiment.app.pheno.ml/v2/auth/token" \
  -u "$PHENOML_CLIENT_ID:$PHENOML_CLIENT_SECRET" \
  | jq -r '.access_token')

curl -X POST "https://experiment.app.pheno.ml/construe/feedback" \
  -H "Authorization: Bearer $PHENOML_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Patient has type 2 diabetes with hyperglycemia",
  "received_result": {
    "system": {
      "name": "ICD-10-CM",
      "version": "2025"
    },
    "codes": [
      {
        "code": "E11.9",
        "description": "Type 2 diabetes mellitus without complications",
        "valid": true
      }
    ]
  },
  "expected_result": {
    "system": {
      "name": "ICD-10-CM",
      "version": "2025"
    },
    "codes": [
      {
        "code": "E11.65",
        "description": "Type 2 diabetes mellitus with hyperglycemia",
        "valid": true
      }
    ]
  },
  "detail": "Expected code E11.65 because the text mentions hyperglycemia"
}'

201 CreatedExample Response

{
  "id": "abc123def456"
}