Microsoft Azure Prebuilt API

openapi: 3.2.0
info:
  version: 2.1-preview.3
  title: Microsoft Azure Form Recognizer Client Prebuilt API
  description: Extracts information from forms and images into structured data.
security:
- apim_key: []
tags:
- name: Prebuilt
paths:
  /prebuilt/businessCard/analyze:
    post:
      summary: Microsoft Azure Analyze Business Card
      description: Extract field text and semantic values from a given business card document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'. Alternatively, use 'application/json' type to specify the location (Uri) of the document to be analyzed.
      operationId: microsoftAzureAnalyzebusinesscardasync
      parameters:
      - name: includeTextDetails
        in: query
        description: Include text lines and element references in the result.
        required: false
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/Locale'
      - $ref: '#/components/parameters/Pages'
      - $ref: '#/components/parameters/FileStream'
      responses:
        '202':
          description: Request is queued successfully.
          headers:
            Operation-Location:
              description: URL containing the resultId used to track the progress and obtain the result of the analyze operation.
              schema:
                type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Analyze Business Card:
          $ref: ./examples/BusinessCardBatch.json
      x-ms-long-running-operation: true
      tags:
      - Prebuilt
  /prebuilt/businessCard/analyzeResults/{resultId}:
    get:
      summary: Microsoft Azure Get Analyze Business Card Result
      description: Track the progress and obtain the result of the analyze business card operation.
      operationId: microsoftAzureGetanalyzebusinesscardresult
      parameters:
      - name: resultId
        in: path
        description: Analyze operation result identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeOperationResult'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Get analyze business card result:
          $ref: ./examples/BusinessCardBatchResult.json
      tags:
      - Prebuilt
  /prebuilt/invoice/analyze:
    post:
      summary: Microsoft Azure Analyze Invoice Document
      description: Extract field text and semantic values from a given invoice document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'. Alternatively, use 'application/json' type to specify the location (Uri) of the document to be analyzed.
      operationId: microsoftAzureAnalyzeinvoiceasync
      parameters:
      - name: includeTextDetails
        in: query
        description: Include text lines and element references in the result.
        required: false
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/Locale'
      - $ref: '#/components/parameters/Pages'
      - $ref: '#/components/parameters/FileStream'
      responses:
        '202':
          description: Request is queued successfully.
          headers:
            Operation-Location:
              description: URL containing the resultId used to track the progress and obtain the result of the analyze operation.
              schema:
                type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Analyze receipt:
          $ref: ./examples/InvoiceBatch.json
      x-ms-long-running-operation: true
      tags:
      - Prebuilt
  /prebuilt/invoice/analyzeResults/{resultId}:
    get:
      summary: Microsoft Azure Get Analyze Invoice Result
      description: Track the progress and obtain the result of the analyze invoice operation.
      operationId: microsoftAzureGetanalyzeinvoiceresult
      parameters:
      - name: resultId
        in: path
        description: Analyze operation result identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeOperationResult'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Get analyze receipt result:
          $ref: ./examples/InvoiceBatchResult.json
      tags:
      - Prebuilt
  /prebuilt/idDocument/analyze:
    post:
      summary: Microsoft Azure Analyze Id Document
      description: Extract field text and semantic values from a given ID document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'. Alternatively, use 'application/json' type to specify the location (Uri) of the document to be analyzed.
      operationId: microsoftAzureAnalyzeiddocumentasync
      parameters:
      - name: includeTextDetails
        in: query
        description: Include text lines and element references in the result.
        required: false
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/Pages'
      - $ref: '#/components/parameters/FileStream'
      responses:
        '202':
          description: Request is queued successfully.
          headers:
            Operation-Location:
              description: URL containing the resultId used to track the progress and obtain the result of the analyze operation.
              schema:
                type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Analyze ID:
          $ref: ./examples/IDDocumentBatch.json
      x-ms-long-running-operation: true
      tags:
      - Prebuilt
  /prebuilt/idDocument/analyzeResults/{resultId}:
    get:
      summary: Microsoft Azure Get Analyze Id Document Result
      description: Track the progress and obtain the result of the analyze ID operation.
      operationId: microsoftAzureGetanalyzeiddocumentresult
      parameters:
      - name: resultId
        in: path
        description: Analyze operation result identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeOperationResult'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Get analyze ID result:
          $ref: ./examples/IDDocumentBatchResult.json
      tags:
      - Prebuilt
  /prebuilt/receipt/analyze:
    post:
      summary: Microsoft Azure Analyze Receipt
      description: Extract field text and semantic values from a given receipt document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'. Alternatively, use 'application/json' type to specify the location (Uri) of the document to be analyzed.
      operationId: microsoftAzureAnalyzereceiptasync
      parameters:
      - name: includeTextDetails
        in: query
        description: Include text lines and element references in the result.
        required: false
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/Locale'
      - $ref: '#/components/parameters/Pages'
      - $ref: '#/components/parameters/FileStream'
      responses:
        '202':
          description: Request is queued successfully.
          headers:
            Operation-Location:
              description: URL containing the resultId used to track the progress and obtain the result of the analyze operation.
              schema:
                type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Analyze receipt:
          $ref: ./examples/ReceiptsBatch.json
      x-ms-long-running-operation: true
      tags:
      - Prebuilt
  /prebuilt/receipt/analyzeResults/{resultId}:
    get:
      summary: Microsoft Azure Get Analyze Receipt Result
      description: Track the progress and obtain the result of the analyze receipt operation.
      operationId: microsoftAzureGetanalyzereceiptresult
      parameters:
      - name: resultId
        in: path
        description: Analyze operation result identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeOperationResult'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Get analyze receipt result:
          $ref: ./examples/ReceiptsBatchResult.json
      tags:
      - Prebuilt
components:
  parameters:
    Locale:
      name: locale
      in: query
      description: 'Locale of the input document. Supported locales include: en-AU, en-CA, en-GB, en-IN, en-US(default).'
      required: false
      x-ms-parameter-location: method
      x-ms-enum:
        name: Locale
        modelAsString: true
      schema:
        type: string
        enum:
        - en-AU
        - en-CA
        - en-GB
        - en-IN
        - en-US
    Pages:
      name: pages
      in: query
      description: Custom page numbers for multi-page documents(PDF/TIFF), input the number of the pages you want to get OCR result. For a range of pages, use a hyphen. Separate each page or range with a comma.
      required: false
      x-ms-parameter-location: method
      schema:
        type: array
        items:
          type: string
          pattern: (^[0-9]+-[0-9]+$)|(^[0-9]+$)
    FileStream:
      name: fileStream
      description: .json, .pdf, .jpg, .png, .tiff or .bmp type file stream.
      x-ms-parameter-location: method
      in: body
      schema:
        $ref: '#/components/schemas/SourcePath'
  schemas:
    ErrorInformation:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
        message:
          type: string
    BoundingBox:
      description: Quadrangle bounding box, with coordinates specified relative to the top-left of the original image. The eight numbers represent the four points, clockwise from the top-left corner relative to the text orientation. For image, the (x, y) coordinates are measured in pixels. For PDF, the (x, y) coordinates are measured in inches.
      type: array
      minItems: 8
      maxItems: 8
      items:
        type: number
    FieldValue:
      description: Recognized field value.
      type: object
      required:
      - type
      properties:
        type:
          description: Type of field value.
          $ref: '#/components/schemas/FieldValueType'
        valueString:
          description: String value.
          type: string
        valueDate:
          description: Date value.
          format: date
          type: string
        valueTime:
          description: Time value.
          format: time
          type: string
        valuePhoneNumber:
          description: Phone number value.
          type: string
        valueNumber:
          description: Floating point value.
          type: number
        valueInteger:
          description: Integer value.
          type: integer
        valueArray:
          description: Array of field values.
          type: array
          items:
            $ref: '#/components/schemas/FieldValue'
        valueObject:
          description: Dictionary of named field values.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FieldValue'
        valueSelectionMark:
          description: Selection mark value.
          type: string
          enum:
          - selected
          - unselected
        valueGender:
          description: 'Gender value: M, F, or X.'
          type: string
          enum:
          - M
          - F
          - X
        valueCountry:
          description: 3-letter country code (ISO 3166-1 alpha-3).
          type: string
        text:
          description: Text content of the extracted field.
          type: string
        boundingBox:
          description: Bounding box of the field value, if appropriate.
          $ref: '#/components/schemas/BoundingBox'
        confidence:
          description: Confidence score.
          $ref: '#/components/schemas/Confidence'
        elements:
          description: When includeTextDetails is set to true, a list of references to the text elements constituting this field.
          type: array
          items:
            $ref: '#/components/schemas/ElementReference'
        page:
          description: The 1-based page number in the input document.
          type: integer
          minimum: 1
    Style:
      description: An object representing the style of the text line.
      type: object
      required:
      - name
      - confidence
      properties:
        name:
          description: The text line style name, including handwriting and other.
          type: string
          x-ms-enum:
            name: TextStyle
            modelAsString: true
          enum:
          - other
          - handwriting
        confidence:
          description: The confidence of text line style.
          type: number
          format: float
    SourcePath:
      description: Uri or local path to source data.
      type: object
      properties:
        source:
          description: File source path.
          maxLength: 2048
          minLength: 0
          type: string
    ReadResult:
      description: Text extracted from a page in the input document.
      type: object
      required:
      - page
      - angle
      - width
      - height
      - unit
      properties:
        page:
          description: The 1-based page number in the input document.
          type: integer
          minimum: 1
        angle:
          description: The general orientation of the text in clockwise direction, measured in degrees between (-180, 180].
          type: number
          maximum: 180
          exclusiveMinimum: -180
        width:
          description: The width of the image/PDF in pixels/inches, respectively.
          type: number
          minimum: 0
        height:
          description: The height of the image/PDF in pixels/inches, respectively.
          type: number
          minimum: 0
        unit:
          description: The unit used by the width, height and boundingBox properties. For images, the unit is "pixel". For PDF, the unit is "inch".
          type: string
          enum:
          - pixel
          - inch
          x-ms-enum:
            name: LengthUnit
            modelAsString: false
        lines:
          description: When includeTextDetails is set to true, a list of recognized text lines. The maximum number of lines returned is 300 per page. The lines are sorted top to bottom, left to right, although in certain cases proximity is treated with higher priority. As the sorting order depends on the detected text, it may change across images and OCR version updates. Thus, business logic should be built upon the actual line location instead of order.
          type: array
          items:
            $ref: '#/components/schemas/TextLine'
        selectionMarks:
          description: List of selection marks extracted from the page.
          type: array
          items:
            $ref: '#/components/schemas/SelectionMark'
    FieldValueType:
      type: string
      description: Semantic data type of the field value.
      enum:
      - string
      - date
      - time
      - phoneNumber
      - number
      - integer
      - array
      - object
      - selectionMark
      - gender
      - country
      x-ms-enum:
        name: FieldValueType
        modelAsString: false
    AnalyzeOperationResult:
      description: Status and result of the queued analyze operation.
      type: object
      required:
      - status
      - createdDateTime
      - lastUpdatedDateTime
      properties:
        status:
          description: Operation status.
          $ref: '#/components/schemas/OperationStatus'
        createdDateTime:
          format: date-time
          description: Date and time (UTC) when the analyze operation was submitted.
          type: string
        lastUpdatedDateTime:
          format: date-time
          description: Date and time (UTC) when the status was last updated.
          type: string
        analyzeResult:
          description: Results of the analyze operation.
          $ref: '#/components/schemas/AnalyzeResult'
    AnalyzeResult:
      description: Analyze operation result.
      type: object
      required:
      - version
      - readResults
      properties:
        version:
          description: Version of schema used for this result.
          type: string
        readResults:
          description: Text extracted from the input.
          type: array
          items:
            $ref: '#/components/schemas/ReadResult'
        pageResults:
          description: Page-level information extracted from the input.
          type: array
          items:
            $ref: '#/components/schemas/PageResult'
        documentResults:
          description: Document-level information extracted from the input.
          type: array
          items:
            $ref: '#/components/schemas/DocumentResult'
        errors:
          description: List of errors reported during the analyze operation.
          type: array
          items:
            $ref: '#/components/schemas/ErrorInformation'
    DataTable:
      description: Information about the extracted table contained in a page.
      type: object
      required:
      - rows
      - columns
      - cells
      - boundingBox
      properties:
        rows:
          description: Number of rows.
          type: integer
          minimum: 1
        columns:
          description: Number of columns.
          type: integer
          minimum: 1
        cells:
          description: List of cells contained in the table.
          type: array
          items:
            $ref: '#/components/schemas/DataTableCell'
        boundingBox:
          description: Bounding box of the table.
          $ref: '#/components/schemas/BoundingBox'
    KeyValuePair:
      description: Information about the extracted key-value pair.
      type: object
      required:
      - key
      - value
      - confidence
      properties:
        label:
          description: A user defined label for the key/value pair entry.
          type: string
        key:
          description: Information about the extracted key in a key-value pair.
          $ref: '#/components/schemas/KeyValueElement'
        value:
          description: Information about the extracted value in a key-value pair.
          $ref: '#/components/schemas/KeyValueElement'
        confidence:
          description: Confidence value.
          $ref: '#/components/schemas/Confidence'
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorInformation'
    OperationStatus:
      type: string
      description: Status of the queued operation.
      enum:
      - notStarted
      - running
      - succeeded
      - failed
      x-ms-enum:
        name: OperationStatus
        modelAsString: false
    DataTableCell:
      description: Information about the extracted cell in a table.
      type: object
      required:
      - rowIndex
      - columnIndex
      - text
      - boundingBox
      - confidence
      properties:
        rowIndex:
          description: Row index of the cell.
          type: integer
          minimum: 0
        columnIndex:
          description: Column index of the cell.
          type: integer
          minimum: 0
        rowSpan:
          description: Number of rows spanned by this cell.
          type: integer
          minimum: 1
          default: 1
        columnSpan:
          description: Number of columns spanned by this cell.
          type: integer
          minimum: 1
          default: 1
        text:
          description: Text content of the cell.
          type: string
        boundingBox:
          description: Bounding box of the cell.
          $ref: '#/components/schemas/BoundingBox'
        confidence:
          description: Confidence value.
          $ref: '#/components/schemas/Confidence'
        elements:
          description: When includeTextDetails is set to true, a list of references to the text elements constituting this table cell.
          type: array
          items:
            $ref: '#/components/schemas/ElementReference'
        isHeader:
          description: Is the current cell a header cell?
          type: boolean
          default: false
        isFooter:
          description: Is the current cell a footer cell?
          type: boolean
          default: false
    DocumentResult:
      description: A set of extracted fields corresponding to the input document.
      type: object
      required:
      - docType
      - pageRange
      - fields
      properties:
        docType:
          description: Document type.
          type: string
        modelId:
          description: Model identifier.
          type: string
          format: uuid
        pageRange:
          description: First and last page number where the document is found.
          type: array
          minItems: 2
          maxItems: 2
          items:
            type: integer
            minimum: 1
        docTypeConfidence:
          description: Predicted document type confidence.
          $ref: '#/components/schemas/Confidence'
        fields:
          description: Dictionary of named field values.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FieldValue'
    Appearance:
      description: An object representing the appearance of the text line.
      type: object
      required:
      - style
      properties:
        style:
          description: An object representing the style of the text line.
          type: object
          $ref: '#/components/schemas/Style'
    PageResult:
      description: Extracted information from a single page.
      type: object
      required:
      - page
      properties:
        page:
          description: Page number.
          type: integer
          format: int32
          minimum: 1
        clusterId:
          description: Cluster identifier.
          type: integer
          format: int32
          minimum: 0
        keyValuePairs:
          description: List of key-value pairs extracted from the page.
          type: array
          items:
            $ref: '#/components/schemas/KeyValuePair'
        tables:
          description: List of data tables extracted from the page.
          type: array
          items:
            $ref: '#/components/schemas/DataTable'
    KeyValueElement:
      description: Information about the extracted key or value in a key-value pair.
      type: object
      required:
      - text
      properties:
        type:
          $ref: '#/components/schemas/KeyValueType'
        text:
          description: The text content of the key or value.
          type: string
        boundingBox:
          description: Bounding box of the key or value.
          $ref: '#/components/schemas/BoundingBox'
        elements:
          description: When includeTextDetails is set to true, a list of references to the text elements constituting this key or value.
          type: array
          items:
            $ref: '#/components/schemas/ElementReference'
    TextLine:
      description: An object representing an extracted text line.
      type: object
      required:
      - text
      - boundingBox
      - words
      properties:
        text:
          description: The text content of the line.
          type: string
        boundingBox:
          description: Bounding box of an extracted line.
          $ref: '#/components/schemas/BoundingBox'
        words:
          description: List of words in the text line.
          type: array
          items:
            $ref: '#/components/schemas/TextWord'
        appearance:
          description: Text appearance properties.
          $ref: '#/components/schemas/Appearance'
    Confidence:
      description: Confidence value.
      type: number
      minimum: 0
      maximum: 1
    ElementReference:
      description: Reference to a line, word or selection mark.
      type: string
    KeyValueType:
      type: string
      description: Semantic data type of the key value element.
      enum:
      - string
      - selectionMark
      x-ms-enum:
        name: KeyValueType
        modelAsString: true
    TextWord:
      description: An object representing a word.
      type: object
      required:
      - boundingBox
      - text
      properties:
        text:
          description: The text content of the word.
          type: string
        boundingBox:
          description: Bounding box of an extracted word.
          $ref: '#/components/schemas/BoundingBox'
        confidence:
          description: Confidence value.
          $ref: '#/components/schemas/Confidence'
    SelectionMark:
      description: Information about the extracted selection mark.
      type: object
      required:
      - boundingBox
      - confidence
      - state
      properties:
        boundingBox:
          description: Bounding box of the selection mark.
          $ref: '#/components/schemas/BoundingBox'
        confidence:
          description: Confidence value.
          $ref: '#/components/schemas/Confidence'
        state:
          description: State of the selection mark.
          type: string
          enum:
          - selected
          - unselected
  securitySchemes:
    apim_key:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
x-ms-parameterized-host:
  hostTemplate: '{endpoint}/formrecognizer/v2.1-preview.3'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'
x-ms-paths:
  /custom/models?op=full:
    get:
      summary: List Custom Models
      description: Get information about all custom models
      operationId: ListCustomModels
      consumes: []
      produces:
      - application/json
      parameters:
      - name: op
        in: query
        description: Specify whether to return summary or full list of models.
        required: true
        type: string
        enum:
        - full
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/components/schemas/Models'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      x-ms-pageable:
        nextLinkName: nextLink
        itemName: modelList
      x-ms-examples:
        List custom models:
          $ref: ./examples/GetModels.json
  /custom/models?op=summary:
    get:
      summary: Get Custom Models
      description: Get information about all custom models
      operationId: GetCustomModels
      consumes: []
      produces:
      - application/json
      parameters:
      - name: op
        in: query
        description: Specify whether to return summary or full list of models.
        required: true
        type: string
        enum:
        - summary
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/components/schemas/Models'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Get models summary:
          $ref: ./examples/GetModelsSummary.json