Template OCR
    • PDF

    Template OCR

    • PDF

    Article summary

    Available in Classic and VPC

    Recognize and extract text based on a template that specifies the reading area of an image directly from the NAVER Cloud Platform console.

    Request

    This section describes the request format. The method and URI are as follows:

    MethodURI
    POST/infer

    Request headers

    For information about the headers common to all CLOVA OCR APIs, see CLOVA OCR request headers.

    Request body

    You can include the following data in the body of your request:

    For Content-Type: application/json

    You can include the following data in the body of your request if the request header's Content-Type is application/json:

    FieldTypeRequiredDescription
    versionStringRequiredVersion information
    • V1 | V2 (recommended)
      • V1: Call V1 engine
      • V2: Call V2 engine
    requestIdStringRequiredRandom API call UUID
    timestampIntegerRequiredRandom API call time (timestamp)
    langStringOptionalOCR recognition request language information
    • ko | en | ja | zh-TW
      • ko: Korean
      • en: English
      • ja: Japanese
      • zh-TW: Chinese (Traditional)
    • Automatically set to domain's language setting if not entered
    • Comma (,) to call multiple languages simultaneously
      • <e.g.> "ko, ja, zh-TW"
    imagesArrayRequiredimages details
    • Write as JSON array
    • Able to create 1 image array per call
    • Image size: up to 50 MB
    enableTableDetectionBooleanOptionalWhether to recognize table areas within document images and provide a structured form
    • true | false (default)
      • true: table recognition and form provided
      • false: table recognition and form not provided
    • Must enable (ON) the toggle button for "Table extraction status" in the domain created in NAVER Cloud Platform to use it

    For Content-Type: multipart/form-data

    You can include the following data in the body of your request if the request header's Content-Type is multipart/form-data.

    FieldTypeRequiredDescription
    messageObjectRequiredRequest data information
    message.versionStringRequiredVersion information
    • V1 | V2 (recommended value)
      • V1: Call V1 engine
      • V2: Call V2 engine
    message.requestIdStringRequiredRandom API call UUID
    message.timestampIntegerRequiredRandom API call time (timestamp)
    message.langStringOptionalOCR recognition request language information
    • ko | en | ja | zh-TW
      • ko: Korean
      • en: English
      • ja: Japanese
      • zh-TW: Chinese (Traditional)
    • Automatically set to domain's language setting if not entered
    • Comma (,) to call multiple languages simultaneously
      • <e.g.> "ko, ja, zh-TW"
    message.imagesArrayRequiredimages details
    • Write as JSON array
    • Able to create 1 image array per call
    • Image size: up to 50 MB
    message.enableTableDetectionBooleanOptionalWhether to recognize table areas within document images and provide a structured form
    • true | false (default)
      • true: table recognition and form provided
      • false: table recognition and form not provided
    • Must enable (ON) the toggle button for "Table extraction status" in the domain created in NAVER Cloud Platform to use it
    fileFileRequiredOCR recognition image file

    images

    The following describes images.

    FieldTypeRequiredDescription
    formatStringRequiredImage format
    • jpg | jpeg | png | pdf | tif | tiff
      • pdf: up to 10 pages can be recognized
    nameStringRequiredImage name
    • Use to identify images and check response results
    urlStringConditionalImage URL address
    • Public URL where images can be fetched
    • Can be entered if Content-Type: application/json
    • images.url or images.data must be entered
      • images.data is prioritized when both are entered
    dataStringConditionalBase64-encoded image data
    • Can be entered if Content-Type: application/json
    • images.url or images.data must be entered
      • images.data is prioritized when both are entered
    templateIdsIntegerOptionalTemplate ID
    • Automatically categorized into all deployed service templates when not entered

    Request example

    The request example is as follows:

    For Content-Type: application/json

    The request example if the request header's Content-Type is application/json is as follows:

    curl --location --request POST 'https://*****.apigw.ntruss.com/custom/v1/33661/f5d739754b0ed5bdaa51365b7d**********a5bbdd069e0db430d5f5adb490b/infer' \
    --header 'Content-Type: application/json' \
    --header 'X-OCR-SECRET: {Secret key issued when registering the app}' \
    --data '{
      "version": "V2",
      "requestId": "string",
      "timestamp": 0,
      "lang":"ko",
      "images": [
        {
          "format": "pdf",
          "name": "test 1",
          "url": "{url}",
          "templateIds":[31677]
        }
      ],
      "enableTableDetection": true
    }'
    

    For Content-Type: multipart/form-data

    The request example if the request header's Content-Type is multipart/form-data is as follows:

    curl --location --request POST 'https://*****.apigw.ntruss.com/custom/v1/33661/f5d739754b0ed5bdaa51365b7d**********bbdd069e0db430d5f5adb490b/infer' \
    --header 'Content-Type: multipart/form-data' \
    --header 'X-OCR-SECRET: {Secret key issued when registering the app}' \
    --form '{file}.jpg"' \
    --form 'message="{\"version\": \"V1\", \"requestId\": \"1234\", \"timestamp\": 1724832750462, \"images\": [{\"format\": \"jpg\", \"name\": \"hello\"}]}"'
    

    Response

    This section describes the response format.

    Note

    When requesting with the V2 version, the bounding and boundingPoly information is displayed in the response result value.

    Response body

    The response body includes the following data:

    FieldTypeRequiredDescription
    versionString-Version information
    • V1 | V2
      • V1: Call V1 engine
      • V2: Call V2 engine
    requestIdString-API call UUID
    timestampInteger-API call time (timestamp)
    imagesArray-images details

    images

    The following describes images.

    FieldTypeRequiredDescription
    uidString-Image UID
    • Use for API validity checks and request tracing
    nameString-Image name
    • Use to identify images and check response results
    inferResultString-Image inference result
    • SUCCESS | FAILURE | ERROR
      • SUCCESS: recognition successful
      • FAILURE: recognition failure
      • ERROR: recognition processing exception
    messageString-Result message
    matchedTemplateObject-Template information
    • If recognition fails or no matching template is found, the field is not displayed
    matchedTemplate.idInteger-Template ID
    matchedTemplate.nameString-Template name
    validationResultObject-Validity check result information
    validationResult.resultString-Validity check result code
    • NO_REQUESTED | UNCHECKED | ERROR | VALID | INVALID
      • NO_REQUESTED: no validation action requested (validity check failed)
      • UNCHECKED: unable to verify validation
      • ERROR: error on validation (validity check failed)
      • VALID: validation result valid (validity check succeeded)
      • INVALID: failed to pass validation
    validationResult.messageString-Validity check result details message
    • This value is not always returned
    convertedImageInfoObject-Converted image information
    • If format is pdf or tiff
    • Coordinate values are set relative to the called image file
    convertedImageInfo.widthInteger-Converted image width
    convertedImageInfo.heightInteger-Converted image height
    convertedImageInfo.pageIndexInteger-Converted image page index
    convertedImageInfo.longImageBoolean-Whether the converted image length is long
    • true | false
      • true: long image
      • false: not a long image
    combineResultObject-Image recognition result combination information
    combineResult.nameString-Image combination field name
    combineResult.textString-Output value and fixed text for each image field
    tablesArray-Tables details
    fieldsArray-Fields details
    titleObject-Image title details
    title.nameString-Template representative sample field names
    • Use to identify images and check response results
    title.boundingPolyObject-Bounding poly information
    • Provided only if version is V2
    title.boundingPoly.verticesArray-Bounding poly vertices details
    title.inferTextString-Recognized text
    • If type is CHECKBOX, replace with response value specified in settings
    title.inferConfidenceFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    title.subFieldsArray-subFields details

    tables

    The following describes images.tables.

    FieldTypeRequiredDescription
    cellsArray-Cells details
    inferTextString-Recognized text
    inferConfidenceFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    boundingPolyObject-Bounding poly information
    • Provided only if version is V2
    boundingPoly.verticesArray-Bounding poly vertices details

    fields

    The following describes fields.

    FieldTypeRequiredDescription
    nameString-Template field name
    • Operate only on API calls
    • Use to identify images and check response results
    valueTypeString-Input value type
    • ALL | NUMERIC
      • ALL: text and numbers
      • NUMERIC: numbers
    boundingPolyObject-Bounding poly information
    • Provided only if version is V2
    boundingPoly.verticesArray-Bounding poly vertices details
    inferTextString-Recognized text
    • If type is CHECKBOX, replace with response value specified in settings
    inferConfidenceFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    typeString-Recognized image type
    • NORMAL | MULTI_BOX | CHECKBOX
      • NORMAL: general
      • MULTI_BOX: multi-box
      • CHECKBOX: checkbox
    subFieldsArray-subFields details
    checkedBoolean-Checkbox selection
    • true | false
      • true: selected
      • false: not selected

    subFields

    The following describes fields.subFields.

    FieldTypeRequiredDescription
    boundingPolyObject-Bounding poly information
    • Provided only if version is V2
    boundingPoly.verticesArray-Bounding poly vertices details
    inferTextString-Recognized text
    • If type is CHECKBOX, replace with response value specified in settings
    inferConfidenceFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    lineBreakBoolean-Indicate whether the recognized text is the last line
    • true | false
      • true: last text
      • false: not last text

    cells

    The following describes tables.cells.

    FieldTypeRequiredDescription
    boundingPolyObject-Bounding poly information
    • Provided only if version is V2
    boundingPoly.verticesArray-Bounding poly vertices details
    cellTextLinesArray-cellTextLines details
    inferConfidenceFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    rowSpanInteger-Number of horizontal columns occupied by cells in the table (span)
    rowIndexInteger-Position value of the corresponding horizontal column in the table
    columnSpanInteger-Number of vertical rows occupied by cells in the table (span)
    columnIndexInteger-Position value of the corresponding vertical row in the table

    cellTextLines

    The following describes cellTextLines.

    FieldTypeRequiredDescription
    boundingPolyObject-Bounding poly information
    • Provided only if version is V2
    boundingPoly.verticesArray-Bounding poly vertices details
    inferConfidenceFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    cellWordsArray-Cell's text details

    cellWords

    The following describes cellWords.

    FieldTypeRequiredDescription
    boundingPolyObject-Bounding poly information
    • Provided only if version is V2
    boundingPoly.verticesArray-Bounding poly vertices details
    inferConfidenceFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    inferTextString-Recognized text

    vertices

    The following describes boundingPoly.vertices.

    FieldTypeRequiredDescription
    xFloat-Bounding poly X-axis coordinate value
    yFloat-Bounding poly Y-axis coordinate value

    Response status codes

    For information about the HTTP status codes common to all CLOVA OCR APIs, see Common CLOVA OCR response status codes.

    Response example

    The response example is as follows:

    Succeeded

    The following is a sample response upon a successful call.

    {
        "version": "V2",
        "requestId": "string",
        "timestamp": 1724831491715,
        "images": [
            {
                "uid": "{uid}",
                "name": "test 1",
                "inferResult": "SUCCESS",
                "message": "SUCCESS",
                "matchedTemplate": {
                    "id": 31677,
                    "name": "Business registration certificate"
                },
                "validationResult": {
                    "result": "NO_REQUESTED"
                },
                "convertedImageInfo": {
                    "width": 1190,
                    "height": 1682,
                    "pageIndex": 0,
                    "longImage": false
                },
                "fields": [
                    {
                        "name": "Registration number",
                        "valueType": "ALL",
                        "boundingPoly": {
                            "vertices": [
                                {
                                    "x": 551.0,
                                    "y": 310.0
                                },
                                {
                                    "x": 775.0,
                                    "y": 310.0
                                },
                                {
                                    "x": 775.0,
                                    "y": 350.0
                                },
                                {
                                    "x": 551.0,
                                    "y": 350.0
                                }
                            ]
                        },
                        "inferText": "***-**-*****",
                        "inferConfidence": 1.0,
                        "type": "NORMAL",
                        "subFields": [
                            {
                                "boundingPoly": {
                                    "vertices": [
                                        {
                                            "x": 551.0,
                                            "y": 310.0
                                        },
                                        {
                                            "x": 775.0,
                                            "y": 310.0
                                        },
                                        {
                                            "x": 775.0,
                                            "y": 350.0
                                        },
                                        {
                                            "x": 551.0,
                                            "y": 350.0
                                        }
                                    ]
                                },
                                "inferText": "***-**-*****",
                                "inferConfidence": 1.0,
                                "lineBreak": true
                            }
                        ]
                    },
                    {
                        "name": "Corporate name_organization name",
                        "valueType": "ALL",
                        "boundingPoly": {
                            "vertices": [
                                {
                                    "x": 317.0,
                                    "y": 369.0
                                },
                                {
                                    "x": 511.0,
                                    "y": 369.0
                                },
                                {
                                    "x": 511.0,
                                    "y": 402.0
                                },
                                {
                                    "x": 317.0,
                                    "y": 402.0
                                }
                            ]
                        },
                        "inferText": "***** Inc.",
                        "inferConfidence": 0.9999,
                        "type": "NORMAL",
                        "subFields": [
                            {
                                "boundingPoly": {
                                    "vertices": [
                                        {
                                            "x": 317.0,
                                            "y": 369.0
                                        },
                                        {
                                            "x": 451.0,
                                            "y": 369.0
                                        },
                                        {
                                            "x": 451.0,
                                            "y": 402.0
                                        },
                                        {
                                            "x": 317.0,
                                            "y": 402.0
                                        }
                                    ]
                                },
                                "inferText": "*****",
                                "inferConfidence": 0.9998,
                                "lineBreak": false
                            },
                            {
                                "boundingPoly": {
                                    "vertices": [
                                        {
                                            "x": 459.0,
                                            "y": 371.0
                                        },
                                        {
                                            "x": 511.0,
                                            "y": 371.0
                                        },
                                        {
                                            "x": 511.0,
                                            "y": 399.0
                                        },
                                        {
                                            "x": 459.0,
                                            "y": 399.0
                                        }
                                    ]
                                },
                                "inferText": "Inc.",
                                "inferConfidence": 1.0,
                                "lineBreak": true
                            }
                        ]
                    },
                    {
                        "name": "Business start date",
                        "valueType": "ALL",
                        "boundingPoly": {
                            "vertices": [
                                {
                                    "x": 316.0,
                                    "y": 493.0
                                },
                                {
                                    "x": 564.0,
                                    "y": 495.0
                                },
                                {
                                    "x": 564.0,
                                    "y": 526.0
                                },
                                {
                                    "x": 314.0,
                                    "y": 526.0
                                }
                            ]
                        },
                        "inferText": "June 01, 1975",
                        "inferConfidence": 0.99796,
                        "type": "NORMAL",
                        "subFields": [
                            {
                                "boundingPoly": {
                                    "vertices": [
                                        {
                                            "x": 316.0,
                                            "y": 493.0
                                        },
                                        {
                                            "x": 374.0,
                                            "y": 496.0
                                        },
                                        {
                                            "x": 373.0,
                                            "y": 525.0
                                        },
                                        {
                                            "x": 314.0,
                                            "y": 522.0
                                        }
                                    ]
                                },
                                "inferText": "1975",
                                "inferConfidence": 1.0,
                                "lineBreak": false
                            },
                            {
                                "boundingPoly": {
                                    "vertices": [
                                        {
                                            "x": 380.0,
                                            "y": 495.0
                                        },
                                        {
                                            "x": 410.0,
                                            "y": 495.0
                                        },
                                        {
                                            "x": 410.0,
                                            "y": 526.0
                                        },
                                        {
                                            "x": 380.0,
                                            "y": 526.0
                                        }
                                    ]
                                },
                                "inferText": "Year",
                                "inferConfidence": 0.9999,
                                "lineBreak": false
                            },
                            {
                                "boundingPoly": {
                                    "vertices": [
                                        {
                                            "x": 417.0,
                                            "y": 495.0
                                        },
                                        {
                                            "x": 451.0,
                                            "y": 495.0
                                        },
                                        {
                                            "x": 451.0,
                                            "y": 523.0
                                        },
                                        {
                                            "x": 417.0,
                                            "y": 523.0
                                        }
                                    ]
                                },
                                "inferText": "06",
                                "inferConfidence": 1.0,
                                "lineBreak": false
                            },
                            {
                                "boundingPoly": {
                                    "vertices": [
                                        {
                                            "x": 457.0,
                                            "y": 495.0
                                        },
                                        {
                                            "x": 490.0,
                                            "y": 495.0
                                        },
                                        {
                                            "x": 490.0,
                                            "y": 524.0
                                        },
                                        {
                                            "x": 457.0,
                                            "y": 524.0
                                        }
                                    ]
                                },
                                "inferText": "Month",
                                "inferConfidence": 0.9997,
                                "lineBreak": false
                            },
                            {
                                "boundingPoly": {
                                    "vertices": [
                                        {
                                            "x": 494.0,
                                            "y": 495.0
                                        },
                                        {
                                            "x": 564.0,
                                            "y": 495.0
                                        },
                                        {
                                            "x": 564.0,
                                            "y": 523.0
                                        },
                                        {
                                            "x": 494.0,
                                            "y": 523.0
                                        }
                                    ]
                                },
                                "inferText": "1st",
                                "inferConfidence": 0.9902,
                                "lineBreak": false
                            }
                        ]
                    },
                    {
                        "name": "Business place location",
                        "valueType": "ALL",
                        "boundingPoly": {
                            "vertices": [
                                {
                                    "x": 315.0,
                                    "y": 534.0
                                },
                                {
                                    "x": 852.0,
                                    "y": 534.0
                                },
                                {
                                    "x": 852.0,
                                    "y": 568.0
                                },
                                {
                                    "x": 315.0,
                                    "y": 568.0
                                }
                            ]
                        },
                        "inferText": "Gyeonggi-do ******",
                        "inferConfidence": 0.99223995,
                        "type": "NORMAL",
                        "subFields": [
                            {
                                "boundingPoly": {
                                    "vertices": [
                                        {
                                            "x": 315.0,
                                            "y": 535.0
                                        },
                                        {
                                            "x": 397.0,
                                            "y": 535.0
                                        },
                                        {
                                            "x": 397.0,
                                            "y": 568.0
                                        },
                                        {
                                            "x": 315.0,
                                            "y": 568.0
                                        }
                                    ]
                                },
                                "inferText": "Gyeonggi-do",
                                "inferConfidence": 1.0,
                                "lineBreak": false
                            }
                        ]
                    },
                    {
                        "name": "CEO",
                        "valueType": "ALL",
                        "boundingPoly": {
                            "vertices": [
                                {
                                    "x": 300.66458,
                                    "y": 404.66934
                                },
                                {
                                    "x": 910.0876,
                                    "y": 400.79553
                                },
                                {
                                    "x": 909.6188,
                                    "y": 478.17303
                                },
                                {
                                    "x": 300.49875,
                                    "y": 481.97482
                                }
                            ]
                        },
                        "inferText": "",
                        "inferConfidence": 0.0,
                        "type": "NORMAL"
                    }
                ],
                "title": {
                    "name": "Business registration certificate",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 330.0,
                                "y": 188.0
                            },
                            {
                                "x": 795.0,
                                "y": 186.0
                            },
                            {
                                "x": 795.0,
                                "y": 252.0
                            },
                            {
                                "x": 330.0,
                                "y": 253.0
                            }
                        ]
                    },
                    "inferText": "Business registration certificate",
                    "inferConfidence": 0.9998,
                    "subFields": [
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 330.0,
                                        "y": 188.0
                                    },
                                    {
                                        "x": 795.0,
                                        "y": 186.0
                                    },
                                    {
                                        "x": 795.0,
                                        "y": 252.0
                                    },
                                    {
                                        "x": 330.0,
                                        "y": 253.0
                                    }
                                ]
                            },
                            "inferText": "Business registration certificate",
                            "inferConfidence": 0.9998,
                            "lineBreak": true
                        }
                    ]
                }
            },
        ]
    }
    

    Failure

    The following is a sample response upon a failed call.

    {
        "version": "V1",
        "requestId": "1234",
        "timestamp": 1724833931723,
        "images": [
            {
                "uid": "{uid}",
                "name": "hello",
                "inferResult": "FAILURE",
                "message": "NOT_FOUND: not found matched template",
                "validationResult": {
                    "result": "NO_REQUESTED"
                }
            }
        ]
    }
    

    Was this article helpful?

    What's Next
    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.