Microsoft Azure Layout API

openapi: 3.2.0
info:
  version: 2.1-preview.3
  title: Microsoft Azure Form Recognizer Client Layout API
  description: Extracts information from forms and images into structured data.
security:
- apim_key: []
tags:
- name: Layout
paths:
  /layout/analyze:
    post:
      summary: Microsoft Azure Analyze Layout
      description: Extract text and layout information from a given 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 or local path) of the document to be analyzed.
      operationId: microsoftAzureAnalyzelayoutasync
      parameters:
      - $ref: '#/components/parameters/FileStream'
      - $ref: '#/components/parameters/Pages'
      - $ref: '#/components/parameters/Language'
      - $ref: '#/components/parameters/ReadingOrder'
      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 layout:
          $ref: ./examples/LayoutBatch.json
      x-ms-long-running-operation: true
      tags:
      - Layout
  /layout/analyzeResults/{resultId}:
    get:
      summary: Microsoft Azure Get Analyze Layout Result
      description: Track the progress and obtain the result of the analyze layout operation
      operationId: microsoftAzureGetanalyzelayoutresult
      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 layout result:
          $ref: ./examples/LayoutBatchResult.json
      tags:
      - Layout
components:
  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
  parameters:
    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]+$)
    ReadingOrder:
      name: readingOrder
      in: query
      description: 'Reading order algorithm to sort the text lines returned. Supported reading orders include: basic(default), natural.'
      required: false
      x-ms-parameter-location: method
      x-ms-enum:
        name: ReadingOrder
        modelAsString: false
      schema:
        type: string
        enum:
        - basic
        - natural
        default: basic
    Language:
      name: language
      in: query
      description: Currently, only Afrikaans (‘af’), Albanian (‘sq’), Asturian (‘ast’), Basque (‘eu’), Bislama (‘bi’), Breton (‘br’), Catalan (‘ca’), Cebuano (‘ceb’), Chamorro (‘ch’), Cornish (‘kw’), Corsican (‘co’), Crimean Tatar - Latin script(‘crh’), Czech (‘cs’), Danish (‘da’), Dutch (‘nl’), English ('en'), Estonian (‘et’), Fijian (‘fj’), Filipino (‘fil’), Finnish (‘fi’), French (‘fr’), Friulian (‘fur’), Galician (‘gl’), German (‘de’), Gilbertese (‘gil’), Greenlandic (‘kl’), Haitian Creole (‘ht’), Hani (‘hni’), Hmong Daw (‘mww’), Hungarian (‘hu’), Indonesian (‘id’), Interlingua (‘ia’), Inuktitut (‘iu’), Irish (‘ga’), Italian (‘it’), Japanese (‘ja’), Javanese (‘jv’), Kabuverdianu (‘kea’), Kachin (‘kac’), Kara-Kalpak (‘kaa’), Kashubian (‘csb’), Khasi (‘kha’), Korean (‘ko’), Kurdish - Latin script (‘ku’), K’iche’ (‘quc’), Luxembourgish (‘lb’), Malay (‘ms’), Manx (‘gv’), Neapolitan (‘nap’), Norwegian (‘no’), Occitan (‘oc’), Polish (‘pl’), Portuguese (‘pt’), Romansh (‘rm’), Scots (‘sco’), Scottish Gaelic (‘gd’), simplified Chinese (‘zh-Hans’), Slovenian (‘sl’), Spanish (‘es’), Swahili (‘sw’), Swedish (‘sv’), Tatar - Latin script (‘tt’), Tetum (‘tet’), traditional Chinese (‘zh-Hant’), Turkish (‘tr’), Upper Sorbian (‘hsb’), Uzbek (‘uz’), Volapük (‘vo’), Walser (‘wae’), Western Frisian (‘fy’), Yucatec Maya (‘yua’), Zhuang (‘za’) and Zulu (‘zu’) are supported (print – seventy-three languages and handwritten – English only). Layout supports auto language identification and multi language documents, so only provide a language code if you would like to force the documented to be processed as that specific language.
      required: false
      x-ms-parameter-location: method
      x-ms-enum:
        name: Language
        modelAsString: true
      schema:
        type: string
        enum:
        - af
        - ast
        - bi
        - br
        - ca
        - ceb
        - ch
        - co
        - crh
        - cs
        - csb
        - da
        - de
        - en
        - es
        - et
        - eu
        - fi
        - fil
        - fj
        - fr
        - fur
        - fy
        - ga
        - gd
        - gil
        - gl
        - gv
        - hni
        - hsb
        - ht
        - hu
        - ia
        - id
        - it
        - iu
        - ja
        - jv
        - kaa
        - kac
        - kea
        - kha
        - kl
        - ko
        - ku
        - kw
        - lb
        - ms
        - mww
        - nap
        - nl
        - 'no'
        - oc
        - pl
        - pt
        - quc
        - rm
        - sco
        - sl
        - sq
        - sv
        - sw
        - tet
        - tr
        - tt
        - uz
        - vo
        - wae
        - yua
        - za
        - zh-Hans
        - zh-Hant
        - zu
    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'
  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