Process audio

Important

This feature is in preview. Some functionality might not be supported or might have constrained capabilities.

PUT /audio/batch/startProcessing?api-version=2&customerId={customerId}

Tells Dragon Copilot to generate the AI artifacts and other results from an uploaded audio file.

Parameters

Type Name Required Description Schema
Query api-version Yes The supported API version. Must be set to 1. Integer (int32)
Query customerId Yes The Microsoft-defined identifier of the customer for whom the request is being made. String (uuid)

HTTP headers

Name Value
Content-Type application/json
Authorization Bearer <access token issued by your identity solution>
Accept application/json

Request body

Name Required Description Schema
inputs Yes Information on the audio files to process. List (input object)
languages No The languages of the audio files. A session can contain multiple languages. List (string)
client Yes Information about the client application that generated the audio. Client object
correlationId Yes The partner-defined identifier used to return results. Allowed characters: letters, numbers, underscore (_), hyphen (-) and pipe (|). The maximum allowed length is 128 characters. String
Patient Yes The patient details. Patient object
Practitioner Yes The practitioner details. Practitioner object
Visit Yes The visit details. Visit object
Location No The location details. Location object
AccompaniedBy No The person accompanying the patient. AccompaniedBy object
processing Yes Processing details. Processing object
workflow No Workflow details. Workflow object
output Yes Ouput details. Output object

Input

Name Required Description Schema
type No File type. Must be "audio". String
id Yes The ID returned by the storeAudio API. String (uuid)
audioMetadata No Metadata about the audio to process. AudioMetadata object

AudioMetadata

Name Required Description Schema
contentType No File type. Must be "audio". String
startTime No The audio start time. String
languages No The languages of the audio file. A session can contain multiple languages. List (string)

Client

Name Required Description Schema
id Yes A stable, human-readable identifier of the client application that generated the audio. String
sdkVersion Yes The version of the SDK used by the client application. String

Patient

Name Required Description Schema
fhirIdentifier No The FHIR identifier of the patient. String
medicalRecordNumber Yes The medical record number of the patient. This is typically a longitudinal unique identifier for the patient within an organization, EHR instance or health system. String
externalPatientId Yes The external identifier of the patient. This is typically a longitudinal unique identifier that might exist to represent the patient across multiple EHR instances or health systems. String
patientId No The internal identifier of the patient. This should be used to internally represent the patient across multiple data persistence layers. String
personId No The internal person_id of the patient. This should be used to internally represent the patient as a person entity. For example, this would be used to represent the person within an EMPI system. String
name Yes The patient's name as a Name object. Name object
gender Yes The patient's gender. This can be one of:
unspecified
male
female
other
unknown		 String
gender_identity No The patient’s preferred gender identity. This can be one of:
LA4489-6 - Unknown
LA22878-5 - Identifies as male
LA22879-3 - Identifies as female
LA22880-1 - Female-to-male transsexual
LA22881-9 - Male-to-female transsexual
LA22882-7 - Identifies as non-conforming
LA46-8 - Other
LA20384-6 - Asked but unknown		 String
pronounPreference Yes The patient's preferred pronoun. This can be one of:
LA4489-7 - Unknown
LA29518-0 - he/him/his/his/himself
LA29519-8 - she/her/her/hers/herself
LA29520-6 - they/them/their/theirs/themselves
LA29523-0 - ze/zir/zir/zirs/zirself
LA29521-4 - xie/hir ('here')/hir/hirs/hirself
LA29515-6 - co/co/cos/cos/coself
LA29516-4 - en/en/ens/ens/enself
LA29517-2 - ey/em/eir/eirs/emself
LA29522-2 - yo/yo/yos/yos/yoself
LA29524-8 - ve/ver/vis/ver/verself
LA46-8 - Other
LA20384-6 - Asked but unknown		 String
birthdate Yes The patient's date of birth. String
age Yes The patient's age Age object

Practitioner

Name Required Description Schema
id Yes The identifier of the practitioner. String
fhirIdentifier No The FHIR identifier of the practitioner. String
fullName Yes The practitioner's full name as a string. Use this if individual name properties not provided. String
nameDetails No The practitioner's name as a Name object. Name object
npi Yes The practitioner's NPI (10 digits). int
qualifications Yes The practitioner's qualifications as a list of HL7 codes. See: https://terminology.hl7.org/5.3.0/ValueSet-v2-0360.html List (string)
specialties No The practitioner's specialties as a list of NUCC codes. See: https://www.nucc.org/images/stories/CSV/nucc_taxonomy_231.csv List (string)
roles Yes The practitioner's roles as a list of HL7 codes. See: http://hl7.org/fhir/ValueSet/practitioner-role List (string)

Location

Name Required Description Schema
fhirIdentifier No The location's FHIR identifier. String
name No The name of the clinic or place where the encounter took place. String
npi No The site's NPI. Int
unit No The specific unit or ward within the site where the patient is located. String

Visit

Name Required Description Schema
fhirIdentifier Yes The visit's FHIR identifier. String
externalVisitId Yes The visit ID. String
accountNumber No The account number of the encounter. String
admissionDate No Inpatient: The date and time in UTC when the patient was admitted for an inpatient visit. Outpatient: For an outpatient visit, this can be just the date of the encounter or it can be a specific time at which the patient was checked in. Date time value
dischargeDate No Inpatient: The date and time in UTC when the patient was discharged from an inpatient visit. Outpatient: For an outpatient visit, this can be just the date of the encounter or it can be a specific time at which the patient was checked out. Date time value
reasonForVisit Yes A text representation of the reason for the visit. String
ReasonForAdmission No A text representation of the reason for admission as an inpatient, which can be different than the reason for visit. String
type No The visit type. Possible values:inpatient outpatient emergency urgent elective home field other String

Name

Name Required Description Schema
givenName Yes The person's first name. String
familyName Yes The person's last name. String
suffix Yes Any suffixes (II, III, Senior) or qualifications (MD, DO, DMD). String

Age

Name Required Description Schema
value Yes Number Int
unit Yes One of:years months weeks days hours minutes * seconds String

AccompaniedBy

Name Required Description Schema
name No The name of the person accompanying the patient. String
relationship No The relationship of the person accompanying the patient String

Processing

Name Required Description Schema
templateReferences No Template references List (string)
outputLanguage Yes The output language String

Workflow

Name Required Description Schema
formIds No FormIds List (string)

Ouput

Name Required Description Schema
deliveryMethod Yes The delivery method. For example, "dde" String

Sample request

PUT /audio/batch/startProcessing?api-version=1&customerId=00000000-1111-2222-3333-444444444444
{
    "inputs": [
        {
            "type": "audio",
            "id": "00000000-0000-0000-0000-000000001234",
            "audioMetadata": {
                "contentType": "audio/wav",
                "startTime": "2021-01-01T12:00:00Z",
                "languages": [
                    "en-US",
                    "es-US"
                ]
            }
        }
    ],
    "languages": [
        "en-US",
        "de-DE"
    ],
    "client": {
        "id": "my-app/1.0",
        "sdkVersion": "1.0.0"
    },
    "correlationId": "a80617c4-232c-45f7-ab07-456bfc3b5a10",
    "patient": {
        "medicalRecordNumber": "",
        "externalPatientId": "",
        "name": {
            "givenName": "Jane",
            "familyName": "Hastings",
            "suffix": ""
        },
        "gender": "EHR_ADMINISTRATIVE_GENDER_FEMALE",
        "gender_identity": "LA22879-3",
        "pronounPreference": "LA29519-8",
        "birthdate": "2004-08-09",
        "age": {
            "value": 20,
            "unit": "years"
        }
    },
    "practitioner": {
        "id": "John Doe",
        "fullName": "string",
        "nameDetails": {
            "givenName": "string",
            "familyName": "string",
            "suffix": "string"
        },
        "npi": 1234567890,
        "qualifications": [
            "string"
        ],
        "specialties": [
            "string"
        ],
        "roles": [
            "string"
        ]
    },
    "visit": {
        "fhirIdentifier": "string value",
        "externalVisitId": "string value",
        "accountNumber": "string value",
        "admissionDate": "Date time value",
        "dischargeDate": "Date time value",
        "reasonForVisit": "string value",
        "reasonForAdmission": "string value",
        "type": "inpatient"
    },
    "location": {
        "fhirIdentifier": "string value",
        "name": "string value",
        "npi": 100,
        "unit": "string value"
    },
    "accompaniedBy": {
        "name": "string value",
        "relationship": "string value"
    },
    "processing": {
        "templateReferences": [
            "summary",
            "orders"
        ],
        "outputLanguage": "en-US"
    },
    "workflow": {
        "formIds": [
            "formId1",
            "formId2"
        ]
    },
    "output": {
        "deliveryMethod": "dde"
    }
}

Response codes

Code Description Links
200 Success. The audio was successfully processed. No links
400 Invalid request/bad request. The audio file ID isn't known or the audio file isn't complete. The response will specify which inputs aren't valid. No links
401 Not authorized. The access token is missing or invalid. No links
403 Forbidden. The caller isn't authorized to call the API. No links
500 Internal server error. Any other exceptional scenario where the application isn't able to complete the request. No links

Response body

{
    "message": "Start processing the audio files successfully."
}

Response body properties

Name Description Schema
message Success/error message. String
  • Last updated on