--- title: "Template OCR" slug: "clova-template-ocr-api" updated: 2026-09-17T09:35:51Z published: 2026-09-17T09:35:51Z canonical: "api.ncloud-docs.com/clova-template-ocr-api" --- > ## Documentation Index > Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # Template OCR 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: | Method | URI | | --- | --- | | POST | /infer | ### Request headers For information about the headers common to all CLOVA OCR APIs, see [CLOVA OCR request headers](/docs/en/ai-application-service-ocr#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94). ### 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`: | Field | Type | Required | Description | | --- | --- | --- | --- | | `version` | String | Required | Version information - `V1` \| `V2` (recommended) - `V1`: Call V1 engine. - `V2`: Call V2 engine. | | `requestId` | String | Required | Random API call UUID | | `timestamp` | Integer | Required | Random API call time (millisecond) - Unix timestamp format | | `lang` | String | Optional | OCR 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 - Example: `"ko, ja, zh-TW"` | | `images` | Array | Required | images details: [images](/docs/en/clova-template-ocr-api#images1) - 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`: | Field | Type | Required | Description | | --- | --- | --- | --- | | `file` | File | Required | OCR recognition image file | | `message` | Object | Required | Request data information | | `message.version` | String | Required | Version information - `V1` \| `V2` (recommended value) - `V1`: Call V1 engine - `V2`: Call V2 engine | | `message.requestId` | String | Required | Random API call UUID | | `message.timestamp` | Integer | Required | Random API call time (millisecond) - Unix timestamp format | | `message.lang` | String | Optional | OCR 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 - Example: `"ko, ja, zh-TW"` | | `message.images` | Array | Required | images details: [images](/docs/en/clova-template-ocr-api#images1) - Write as JSON array. - Able to create 1 image array per call - Image size: up to 50 MB | #### `images` The following describes `images`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `format` | String | Required | Image format - `jpg` \| `jpeg` \| `png` \| `pdf` \| `tif` \| `tiff` - `pdf`: up to 5 pages can be recognized. | | `name` | String | Required | Image name - Use to identify images and check response results. | | `url` | String | Conditional | Image 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. | | `data` | String | Conditional | Base64-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. | | `templateIds` | Integer | Optional | Template 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] } }' ``` #### 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 `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: | Field | Type | Required | Description | | --- | --- | --- | --- | | `version` | String | - | Version information - `V1` \| `V2` - `V1`: Call V1 engine. - `V2`: Call V2 engine. | | `requestId` | String | - | API call UUID | | `timestamp` | Integer | - | API call time (millisecond) - Unix timestamp format | | `images` | Array | - | images details: [images](/docs/en/clova-template-ocr-api#images2) | #### `images` The following describes `images`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `uid` | String | - | Image UID - Use for API validity checks and request tracing. | | `name` | String | - | Image name - Use to identify images and check response results. | | `inferResult` | String | - | Image inference result - `SUCCESS` \| `FAILURE` \| `ERROR` - `SUCCESS`: recognition successful - `FAILURE`: recognition failure - `ERROR`: recognition processing exception | | `message` | String | - | Result message | | `matchedTemplate` | Object | - | Template information - If recognition fails or no matching template is found, the field is not displayed. | | `matchedTemplate.id` | Integer | - | Template ID | | `matchedTemplate.name` | String | - | Template name | | `validationResult` | Object | - | Validity check result information | | `validationResult.result` | String | - | 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.message` | String | - | Validity check result details message - This value is not always returned. | | `convertedImageInfo` | Object | - | Converted image information - If `format` is `pdf` or `tiff` - Coordinate values are set relative to the called image file. | | `convertedImageInfo.width` | Integer | - | Converted image width | | `convertedImageInfo.height` | Integer | - | Converted image height | | `convertedImageInfo.pageIndex` | Integer | - | Converted image page index | | `convertedImageInfo.longImage` | Boolean | - | Whether the converted image length is long - `true` \| `false` - `true`: long image - `false`: not a long image | | `combineResult` | Object | - | Image recognition result combination information | | `combineResult.name` | String | - | Image combination field name | | `combineResult.text` | String | - | Output value and fixed text for each image field | | `fields` | Array | - | Fields details: [fields](/docs/en/clova-template-ocr-api#fields) | | `title` | Object | - | Image title details | | `title.name` | String | - | Template representative sample field names - Use to identify images and check response results. | | `title.boundingPoly` | Object | - | Bounding poly information - Provided only if `version` is `V2` | | `title.boundingPoly.vertices` | Array | - | Bounding poly vertices details: [vertices](/docs/en/clova-template-ocr-api#boundingpolyvertices) | | `title.inferText` | String | - | Recognized text - If `type` is `CHECKBOX`, replace with response value specified in settings. | | `title.inferConfidence` | Float | - | Confidence of recognized text - 0-1 - The higher the confidence value, the more accurate the text is. | | `title.subFields` | Array | - | subFields details: [subFields](/docs/en/clova-template-ocr-api#subFields) | #### `fields` The following describes `fields`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | String | - | Template field name - Operate only on API calls. - Use to identify images and check response results. | | `valueType` | String | - | Input value type - `ALL` \| `NUMERIC` - `ALL`: text and numbers - `NUMERIC`: numbers | | `boundingPoly` | Object | - | Bounding poly information - Provided only if `version` is `V2` | | `boundingPoly.vertices` | Array | - | Bounding poly vertices details: [vertices](/docs/en/clova-template-ocr-api#boundingpolyvertices) | | `inferText` | String | - | Recognized text - If `type` is `CHECKBOX`, replace with response value specified in settings. | | `inferConfidence` | Float | - | Confidence of recognized text - 0-1 - The higher the confidence value, the more accurate the text is. | | `type` | String | - | Recognized image type - `NORMAL` \| `MULTI_BOX` \| `CHECKBOX` - `NORMAL`: general - `MULTI_BOX`: multi-box - `CHECKBOX`: checkbox | | `subFields` | Array | - | subFields details: [subFields](/docs/en/clova-template-ocr-api#subFields) | | `checked` | Boolean | - | Checkbox selection - `true` \| `false` - `true`: selected - `false`: not selected | #### `subFields` The following describes `subFields`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `boundingPoly` | Object | - | Bounding poly information - Provided only if `version` is `V2` | | `boundingPoly.vertices` | Array | - | Bounding poly vertices details: [vertices](/docs/en/clova-template-ocr-api#boundingpolyvertices) | | `inferText` | String | - | Recognized text - If `type` is `CHECKBOX`, replace with response value specified in settings. | | `inferConfidence` | Float | - | Confidence of recognized text - 0-1 - The higher the confidence value, the more accurate the text is. | | `lineBreak` | Boolean | - | Indicate whether the recognized text is the last line - `true` \| `false` - `true`: last text - `false`: not last text | #### `vertices` The following describes `vertices`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `x` | Float | - | Bounding poly X-axis coordinate value | | `y` | Float | - | Bounding poly Y-axis coordinate value | #### `bounding` The following describes `bounding`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `top` | Float | - | Bounding Y-axis coordinate value | | `left` | Float | - | Bounding X-axis coordinate value | | `width` | Float | - | Bounding poly width | | `height` | Float | - | 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](/docs/en/ai-application-service-ocr#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C). ### 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" } } ] } ```