MENU
      Template OCR

        Template OCR


        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 | ja | zh-TW
          • ko: Korean
          • 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

        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 | ja | zh-TW
          • ko: Korean
          • 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
        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]
            }
        }'
        Shell

        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\"}]}"'
        Shell

        Response

        This section describes the response format.

        Note
        • When requesting with the V1 version, the coordinate information is displayed in bounding of the response result value.
        • When requesting with the V1 version, the convertedImageInfo, valueType, type, and subFields information is not 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
        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

        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

        vertices

        The following describes boundingPoly.vertices.

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

        bounding

        The following describes bounding.

        FieldTypeRequiredDescription
        topFloat-Bounding Y-axis coordinate value
        leftFloat-Bounding X-axis coordinate value
        widthFloat-Bounding poly width
        heightFloat-Bounding poly height

        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
                            }
                        ]
                    }
                },
            ]
        }
        JSON

        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"
                    }
                }
            ]
        }
        JSON

        Was this article helpful?

        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.