Microsoft Azure Health Data Services Deid API

openapi: 3.2.0
info:
  title: Azure Health Data Services de-identification service Collection Deid API
  version: '2024-11-15'
  x-typespec-generated:
  - emitter: '@azure-tools/typespec-autorest'
security:
- AadToken:
  - https://deid.azure.com/.default
tags:
- name: Deid
paths:
  /deid:
    post:
      operationId: DeidentifyText
      summary: De-identify text.
      description: A remote procedure call (RPC) operation.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      responses:
        '200':
          description: The request has succeeded.
          headers:
            x-ms-client-request-id:
              description: An opaque, globally-unique, client-generated string identifier for the request.
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeidentificationResult'
        default:
          description: An unexpected error response.
          headers:
            x-ms-error-code:
              description: String error code indicating what went wrong.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Azure.Core.Foundations.ErrorResponse'
      x-ms-examples:
        De-identify text.:
          $ref: ./examples/DeidentifyText.json
      tags:
      - Deid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeidentificationContent'
        description: Request body for de-identification operation.
        required: true
components:
  schemas:
    Azure.Core.Foundations.InnerError:
      type: object
      description: An object containing more specific information about the error. As per Azure REST API guidelines - https://aka.ms/AzureRestApiGuidelines#handling-errors.
      properties:
        code:
          type: string
          description: One of a server-defined set of error codes.
        innererror:
          $ref: '#/components/schemas/Azure.Core.Foundations.InnerError'
          description: Inner error.
    PhiTaggerResult:
      type: object
      description: Result of the "Tag" operation.
      properties:
        entities:
          type: array
          description: List of entities detected in the input.
          items:
            $ref: '#/components/schemas/PhiEntity'
      required:
      - entities
    PhiCategory:
      type: string
      description: List of PHI Entities.
      enum:
      - Unknown
      - Account
      - Age
      - BioID
      - City
      - CountryOrRegion
      - Date
      - Device
      - Doctor
      - Email
      - Fax
      - HealthPlan
      - Hospital
      - IDNum
      - IPAddress
      - License
      - LocationOther
      - MedicalRecord
      - Organization
      - Patient
      - Phone
      - Profession
      - SocialSecurity
      - State
      - Street
      - Url
      - Username
      - Vehicle
      - Zip
      x-ms-enum:
        name: PhiCategory
        modelAsString: true
        values:
        - name: Unknown
          value: Unknown
          description: Unknown PHI Type.
        - name: Account
          value: Account
          description: Account Number.
        - name: Age
          value: Age
          description: Age.
        - name: BioID
          value: BioID
          description: Biological Identifier, such as a fingerprint or retinal scan.
        - name: City
          value: City
          description: City.
        - name: CountryOrRegion
          value: CountryOrRegion
          description: Country or Region.
        - name: Date
          value: Date
          description: Date.
        - name: Device
          value: Device
          description: Device ID or serial numbers.
        - name: Doctor
          value: Doctor
          description: Doctor's Name.
        - name: Email
          value: Email
          description: Email Addresses.
        - name: Fax
          value: Fax
          description: Fax Number.
        - name: HealthPlan
          value: HealthPlan
          description: Health Plan ID Numbers.
        - name: Hospital
          value: Hospital
          description: Hospital Name.
        - name: IDNum
          value: IDNum
          description: Id Number, eg. passport number.
        - name: IPAddress
          value: IPAddress
          description: IP Address.
        - name: License
          value: License
          description: License, eg. Driver's license or medical license.
        - name: LocationOther
          value: LocationOther
          description: Location Other, eg. Golden Gate Park.
        - name: MedicalRecord
          value: MedicalRecord
          description: Medical Record Number.
        - name: Organization
          value: Organization
          description: Organization, eg. Microsoft.
        - name: Patient
          value: Patient
          description: Patient Name.
        - name: Phone
          value: Phone
          description: Phone Number.
        - name: Profession
          value: Profession
          description: Profession.
        - name: SocialSecurity
          value: SocialSecurity
          description: Social Security Number.
        - name: State
          value: State
          description: State.
        - name: Street
          value: Street
          description: Street.
        - name: Url
          value: Url
          description: Web URL.
        - name: Username
          value: Username
          description: Usernames, eg. a social media handle.
        - name: Vehicle
          value: Vehicle
          description: Vehicle IDs, eg. license plate or VIN number.
        - name: Zip
          value: Zip
          description: Zip Code.
    DeidentificationResult:
      type: object
      description: Response body for de-identification operation.
      properties:
        outputText:
          type: string
          description: Output text after de-identification. Not available for "Tag" operation.
        taggerResult:
          $ref: '#/components/schemas/PhiTaggerResult'
          description: Result of the "Tag" operation. Only available for "Tag" Operation.
    DeidentificationCustomizationOptions:
      type: object
      description: Customizations options to override default service behaviors for synchronous usage.
      properties:
        redactionFormat:
          type: string
          description: "Format of the redacted output. Only valid when Operation is Redact. \nPlease refer to https://learn.microsoft.com/azure/healthcare-apis/deidentification/redaction-format for more details."
          minLength: 1
          maxLength: 16
        surrogateLocale:
          type: string
          description: Locale in which the output surrogates are written.
          default: en-US
    PhiEntity:
      type: object
      description: PHI Entity tag in the input.
      properties:
        category:
          $ref: '#/components/schemas/PhiCategory'
          description: PHI Category of the entity.
        offset:
          $ref: '#/components/schemas/StringIndex'
          description: Starting index of the location from within the input text.
        length:
          $ref: '#/components/schemas/StringIndex'
          description: Length of the input text.
        text:
          type: string
          description: Text of the entity.
        confidenceScore:
          type: number
          format: double
          description: Confidence score of the category match.
      required:
      - category
      - offset
      - length
    Azure.Core.Foundations.ErrorResponse:
      type: object
      description: A response containing error details.
      properties:
        error:
          $ref: '#/components/schemas/Azure.Core.Foundations.Error'
          description: The error object.
      required:
      - error
    StringIndex:
      type: object
      description: String index encoding model.
      properties:
        utf8:
          type: integer
          format: int32
          description: The offset or length of the substring in UTF-8 encoding
        utf16:
          type: integer
          format: int32
          description: 'The offset or length of the substring in UTF-16 encoding.


            Primary encoding used by .NET, Java, and JavaScript.'
        codePoint:
          type: integer
          format: int32
          description: 'The offset or length of the substring in CodePoint encoding.


            Primary encoding used by Python.'
      required:
      - utf8
      - utf16
      - codePoint
    DeidentificationContent:
      type: object
      description: Request body for de-identification operation.
      properties:
        inputText:
          type: string
          description: Input text to de-identify.
          maxLength: 48000
        operation:
          type: string
          description: Operation to perform on the input documents.
          default: Surrogate
          enum:
          - Redact
          - Surrogate
          - Tag
          x-ms-enum:
            name: DeidentificationOperationType
            modelAsString: true
            values:
            - name: Redact
              value: Redact
              description: Redact Operation will remove all entities of PHI and replace them with a placeholder value.
            - name: Surrogate
              value: Surrogate
              description: Surrogation Operation will replace all entities of PHI with a surrogate value.
            - name: Tag
              value: Tag
              description: Tag Operation will detect all entities of PHI, their type, and return their locations in the document.
        customizations:
          $ref: '#/components/schemas/DeidentificationCustomizationOptions'
          description: Customization parameters to override default service behaviors.
      required:
      - inputText
    Azure.Core.Foundations.Error:
      type: object
      description: The error object.
      properties:
        code:
          type: string
          description: One of a server-defined set of error codes.
        message:
          type: string
          description: A human-readable representation of the error.
        target:
          type: string
          description: The target of the error.
        details:
          type: array
          description: An array of details about specific errors that led to this reported error.
          items:
            $ref: '#/components/schemas/Azure.Core.Foundations.Error'
        innererror:
          $ref: '#/components/schemas/Azure.Core.Foundations.InnerError'
          description: An object containing more specific information than the current object about the error.
      required:
      - code
      - message
  parameters:
    Azure.Core.ClientRequestIdHeader:
      name: x-ms-client-request-id
      in: header
      description: An opaque, globally-unique, client-generated string identifier for the request.
      required: false
      x-ms-parameter-location: method
      x-ms-client-name: clientRequestId
      schema:
        type: string
        format: uuid
    Azure.Core.Foundations.ApiVersionParameter:
      name: api-version
      in: query
      description: The API version to use for this operation.
      required: true
      x-ms-parameter-location: method
      x-ms-client-name: apiVersion
      schema:
        type: string
        minLength: 1
  securitySchemes:
    AadToken:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            https://deid.azure.com/.default: ''
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/token
      description: The Azure Active Directory OAuth2 Flow
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - name: endpoint
    in: path
    description: Url of your De-identification Service.
    required: true
    type: string
    format: uri
    x-ms-skip-url-encoding: true