Get an asynchronous E/M code generation
GET/generate-em-codes-async/:id
Poll the status — and results if successful — of an asynchronous E/M code generation.
warning
This feature is a U.S. product release only; this should not be used outside of U.S. markets.
Request
Responses
- 200
The asynchronous E/M code generation details.
Operation spec
{
"method": "get",
"path": "/generate-em-codes-async/{id}",
"operationId": "get-generate-em-codes-async",
"parameters": [
{
"name": "id",
"description": "The id of the asynchronous request.",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"description": "A unique identifier.",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"example": "23A9981B-9E46-4ADB-BB0B-8E406C624540"
}
],
"responses": {
"200": {
"description": "The asynchronous E/M code generation details.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "ONGOING",
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
}
},
"required": [
"id",
"status"
]
},
{
"title": "FAILED",
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
},
"payload": {
"type": "object",
"properties": {
"error_code": {
"type": "integer",
"example": 422
},
"error_message": {
"type": "string",
"example": "We can't generate the note when the transcript is too short."
}
},
"required": [
"error_code"
],
"title": "async_request_failed_payload"
}
},
"required": [
"id",
"status",
"payload"
]
},
{
"title": "SUCCEEDED",
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
},
"payload": {
"type": "object",
"description": "The result of a successful E/M code generation.",
"properties": {
"visit_type": {
"description": "The visit type used for coding. Either the value provided in the request, or the LLM-inferred value when not provided.",
"type": "string",
"enum": [
"SICK_VISIT",
"PREVENTIVE",
"SPLIT_VISIT"
],
"example": "SICK_VISIT",
"title": "em_visit_type"
},
"em_codes": {
"type": "array",
"description": "The suggested E/M CPT codes. May contain multiple entries for different coding bases (MDM-based, time-based, categorical preventive codes).",
"items": {
"type": "object",
"description": "A suggested E/M CPT code with its coding basis.",
"properties": {
"code": {
"type": "string",
"description": "The CPT code, e.g. `\"99214\"`.",
"example": "99214"
},
"modifiers": {
"type": "array",
"description": "List of CPT modifiers to append to the code, e.g. `[\"25\"]`.",
"items": {
"type": "string"
},
"example": [
"25"
]
},
"coding_basis": {
"type": "string",
"description": "The basis used to determine this E/M code. - `MDM`: code is based on Medical Decision Making complexity. - `TIME`: code is based on total encounter time. - `CATEGORICAL`: code is a categorical (e.g. preventive) code not derived from MDM or time.",
"enum": [
"MDM",
"TIME",
"CATEGORICAL"
],
"example": "MDM",
"title": "em_coding_basis"
},
"description": {
"type": "string",
"description": "Human-readable rationale for why this code was suggested.",
"example": "MDM=moderate, established patient, office modality"
}
},
"required": [
"code",
"modifiers",
"coding_basis",
"description"
],
"title": "em_code"
}
},
"mdm_level": {
"description": "The LLM-inferred MDM level. Always null when `visit_type` is `PREVENTIVE`.",
"nullable": true,
"type": "object",
"properties": {
"value": {
"description": "The determined MDM level of service.",
"type": "string",
"enum": [
"STRAIGHTFORWARD",
"LOW",
"MODERATE",
"HIGH"
],
"example": "MODERATE",
"title": "em_mdm_level"
},
"confidence": {
"type": "string",
"description": "Confidence in the MDM level determination. - `HIGH`: high confidence in the determined level. - `MEDIUM`: there is one plausible alternative overall MDM level; see `alternative_value`. - `LOW`: the determination is uncertain.",
"enum": [
"HIGH",
"MEDIUM",
"LOW"
],
"example": "HIGH"
},
"alternative_value": {
"description": "The alternative overall MDM level when confidence is `medium`. Null otherwise.",
"nullable": true,
"type": "string",
"enum": [
"STRAIGHTFORWARD",
"LOW",
"MODERATE",
"HIGH"
],
"example": "MODERATE",
"title": "em_mdm_level"
}
},
"required": [
"value",
"confidence"
],
"title": "em_mdm_level_output"
},
"mdm_breakdown": {
"description": "The breakdown of the MDM level across the three dimensions. Always null when `visit_type` is `PREVENTIVE`.",
"nullable": true,
"type": "object",
"properties": {
"problem_addressed": {
"type": "object",
"description": "The MDM assessment for one of the three MDM dimensions.",
"properties": {
"level": {
"type": "string",
"description": "The MDM (Medical Decision Making) level of service.",
"enum": [
"STRAIGHTFORWARD",
"LOW",
"MODERATE",
"HIGH"
],
"example": "MODERATE",
"title": "em_mdm_level"
},
"justification": {
"type": "string",
"description": "A brief explanation of why this MDM level was determined for this dimension.",
"example": "Chronic illness with exacerbation requiring prescription management"
}
},
"required": [
"level",
"justification"
],
"title": "em_mdm_breakdown_element"
},
"data_reviewed": {
"type": "object",
"description": "The MDM assessment for one of the three MDM dimensions.",
"properties": {
"level": {
"type": "string",
"description": "The MDM (Medical Decision Making) level of service.",
"enum": [
"STRAIGHTFORWARD",
"LOW",
"MODERATE",
"HIGH"
],
"example": "MODERATE",
"title": "em_mdm_level"
},
"justification": {
"type": "string",
"description": "A brief explanation of why this MDM level was determined for this dimension.",
"example": "Chronic illness with exacerbation requiring prescription management"
}
},
"required": [
"level",
"justification"
],
"title": "em_mdm_breakdown_element"
},
"risk": {
"type": "object",
"description": "The MDM assessment for one of the three MDM dimensions.",
"properties": {
"level": {
"type": "string",
"description": "The MDM (Medical Decision Making) level of service.",
"enum": [
"STRAIGHTFORWARD",
"LOW",
"MODERATE",
"HIGH"
],
"example": "MODERATE",
"title": "em_mdm_level"
},
"justification": {
"type": "string",
"description": "A brief explanation of why this MDM level was determined for this dimension.",
"example": "Chronic illness with exacerbation requiring prescription management"
}
},
"required": [
"level",
"justification"
],
"title": "em_mdm_breakdown_element"
}
},
"required": [
"problem_addressed",
"data_reviewed",
"risk"
],
"title": "em_mdm_breakdown"
}
},
"required": [
"visit_type",
"em_codes"
],
"title": "generate_em_codes_async_succeeded_payload"
}
},
"required": [
"id",
"status"
]
}
],
"discriminator": {
"propertyName": "status",
"mapping": {
"ONGOING": {
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
}
},
"required": [
"id",
"status"
],
"title": "async_request_ongoing"
},
"FAILED": {
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
},
"payload": {
"type": "object",
"properties": {
"error_code": {
"type": "integer",
"example": 422
},
"error_message": {
"type": "string",
"example": "We can't generate the note when the transcript is too short."
}
},
"required": [
"error_code"
],
"title": "async_request_failed_payload"
}
},
"required": [
"id",
"status",
"payload"
],
"title": "async_request_failed"
},
"SUCCEEDED": {
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
},
"payload": {
"type": "object",
"description": "The result of a successful E/M code generation.",
"properties": {
"visit_type": {
"description": "The visit type used for coding. Either the value provided in the request, or the LLM-inferred value when not provided.",
"type": "string",
"enum": [
"SICK_VISIT",
"PREVENTIVE",
"SPLIT_VISIT"
],
"example": "SICK_VISIT",
"title": "em_visit_type"
},
"em_codes": {
"type": "array",
"description": "The suggested E/M CPT codes. May contain multiple entries for different coding bases (MDM-based, time-based, categorical preventive codes).",
"items": {
"type": "object",
"description": "A suggested E/M CPT code with its coding basis.",
"properties": {
"code": {
"type": "string",
"description": "The CPT code, e.g. `\"99214\"`.",
"example": "99214"
},
"modifiers": {
"type": "array",
"description": "List of CPT modifiers to append to the code, e.g. `[\"25\"]`.",
"items": {
"type": "string"
},
"example": [
"25"
]
},
"coding_basis": {
"type": "string",
"description": "The basis used to determine this E/M code. - `MDM`: code is based on Medical Decision Making complexity. - `TIME`: code is based on total encounter time. - `CATEGORICAL`: code is a categorical (e.g. preventive) code not derived from MDM or time.",
"enum": [
"MDM",
"TIME",
"CATEGORICAL"
],
"example": "MDM",
"title": "em_coding_basis"
},
"description": {
"type": "string",
"description": "Human-readable rationale for why this code was suggested.",
"example": "MDM=moderate, established patient, office modality"
}
},
"required": [
"code",
"modifiers",
"coding_basis",
"description"
],
"title": "em_code"
}
},
"mdm_level": {
"description": "The LLM-inferred MDM level. Always null when `visit_type` is `PREVENTIVE`.",
"nullable": true,
"type": "object",
"properties": {
"value": {
"description": "The determined MDM level of service.",
"type": "string",
"enum": [
"STRAIGHTFORWARD",
"LOW",
"MODERATE",
"HIGH"
],
"example": "MODERATE",
"title": "em_mdm_level"
},
"confidence": {
"type": "string",
"description": "Confidence in the MDM level determination. - `HIGH`: high confidence in the determined level. - `MEDIUM`: there is one plausible alternative overall MDM level; see `alternative_value`. - `LOW`: the determination is uncertain.",
"enum": [
"HIGH",
"MEDIUM",
"LOW"
],
"example": "HIGH"
},
"alternative_value": {
"description": "The alternative overall MDM level when confidence is `medium`. Null otherwise.",
"nullable": true,
"type": "string",
"enum": [
"STRAIGHTFORWARD",
"LOW",
"MODERATE",
"HIGH"
],
"example": "MODERATE",
"title": "em_mdm_level"
}
},
"required": [
"value",
"confidence"
],
"title": "em_mdm_level_output"
},
"mdm_breakdown": {
"description": "The breakdown of the MDM level across the three dimensions. Always null when `visit_type` is `PREVENTIVE`.",
"nullable": true,
"type": "object",
"properties": {
"problem_addressed": {
"type": "object",
"description": "The MDM assessment for one of the three MDM dimensions.",
"properties": {
"level": {
"type": "string",
"description": "The MDM (Medical Decision Making) level of service.",
"enum": [
"STRAIGHTFORWARD",
"LOW",
"MODERATE",
"HIGH"
],
"example": "MODERATE",
"title": "em_mdm_level"
},
"justification": {
"type": "string",
"description": "A brief explanation of why this MDM level was determined for this dimension.",
"example": "Chronic illness with exacerbation requiring prescription management"
}
},
"required": [
"level",
"justification"
],
"title": "em_mdm_breakdown_element"
},
"data_reviewed": {
"type": "object",
"description": "The MDM assessment for one of the three MDM dimensions.",
"properties": {
"level": {
"type": "string",
"description": "The MDM (Medical Decision Making) level of service.",
"enum": [
"STRAIGHTFORWARD",
"LOW",
"MODERATE",
"HIGH"
],
"example": "MODERATE",
"title": "em_mdm_level"
},
"justification": {
"type": "string",
"description": "A brief explanation of why this MDM level was determined for this dimension.",
"example": "Chronic illness with exacerbation requiring prescription management"
}
},
"required": [
"level",
"justification"
],
"title": "em_mdm_breakdown_element"
},
"risk": {
"type": "object",
"description": "The MDM assessment for one of the three MDM dimensions.",
"properties": {
"level": {
"type": "string",
"description": "The MDM (Medical Decision Making) level of service.",
"enum": [
"STRAIGHTFORWARD",
"LOW",
"MODERATE",
"HIGH"
],
"example": "MODERATE",
"title": "em_mdm_level"
},
"justification": {
"type": "string",
"description": "A brief explanation of why this MDM level was determined for this dimension.",
"example": "Chronic illness with exacerbation requiring prescription management"
}
},
"required": [
"level",
"justification"
],
"title": "em_mdm_breakdown_element"
}
},
"required": [
"problem_addressed",
"data_reviewed",
"risk"
],
"title": "em_mdm_breakdown"
}
},
"required": [
"visit_type",
"em_codes"
],
"title": "generate_em_codes_async_succeeded_payload"
}
},
"required": [
"id",
"status"
],
"title": "generate_em_codes_async_succeeded"
}
}
},
"title": "async_em_codes_generation"
}
}
}
}
}
}