Resident registration card

Article summary

Did you find this summary helpful?

Thank you for your feedback

Available in Classic and VPC

Recognize and extract key-value input information from resident registration cards using a specialized model engine.

Request

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

Method	URI
POST	/id-card

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:

If `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	-	Version information Only use `V2`
`requestId`	String	Required	Random API call UUID
`timestamp`	Integer	Required	Random API call time (timestamp)
`images`	Array	Required	images details

If `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
`message`	Object	Required	Request data information
`message.version`	String	Required	Version information Only use `V2`
`message.requestId`	String	Required	Random API call UUID
`message.timestamp`	Integer	Required	Random API call time (timestamp)
`message.images`	Array	Required	images details
`file`	File	Required	OCR recognition image file

`images`

The following describes images.

Field	Type	Required	Description
`format`	String	Required	Image format `jpg` \| `jpeg` \| `png` \| `pdf` \| `tif` \| `tiff` Image: `jpg`, `jpeg`, `png` Single page: `pdf`, `tif`, `tiff` Select and enter one of the image formats
`name`	String	Required	Random image name Use to identify images and check response results
`data`	String	Required	Base64-encoded image data Can be entered if `Content-Type: application/json`

Request example

The request example is as follows:

If `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://cbgrx5natw.apigw.ntruss.com/custom/v1/{DomainId}/{InvokeKey}/document/id-card' \
--header 'Content-Type: application/json' \
--header 'X-OCR-SECRET: {Secret key issued when registering the app}' \
--data '{
    "version": "V2",
    "requestId": "string",
    "timestamp": 0,
    "images": [
        { 
            "format": "png", 
            "name": "idcard_test", 
            "data":"{Base64-encoded image data}"
        }
    ]
 }'

If `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://cbgrx5natw.apigw.ntruss.com/custom/v1/{DomainId}/{InvokeKey}/document/id-card' \
--header 'X-OCR-SECRET: {Secret key issued when registering the app}' \
--header 'Content-Type: multipart/form-data' \
--form 'message="{\"version\": \"V2\", \"requestId\": \"1234\", \"timestamp\": 1724832750462, \"images\": [{\"format\": \"png\", \"name\": \"idcard_test\"}]}"' \
--form 'file=@"{file}"'

Response

This section describes the response format.

Response body

The response body includes the following data:

Field	Type	Required	Description
`version`	String	-	Version information Only use `V2`
`requestId`	String	-	Random API call UUID
`timestamp`	Integer	-	API call time (timestamp)
`images`	Array	-	images details

`images`

The following describes images.

Field	Type	Required	Description
`uid`	String	-	Resident registration card image UID Use for API validity checks
`name`	String	-	Resident registration card image name Use to identify images and check response results
`inferResult`	String	-	Resident registration card image recognition result `SUCCESS` \| `FAILURE` \| `ERROR` `SUCCESS`: recognition successful `FAILURE`: recognition failure `ERROR`: recognition processing exception
`message`	String	-	Result message
`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
`idCard`	Object	-	ID card details
`idCard.meta`	Object	-	Meta information
`idCard.meta.estimatedLanguage`	String	-	OCR estimated language `ko` \| `en` \| `ja` `ko`:Korean `en`: English `ja`: Japanese
`idCard.result`	Object	-	ID card OCR recognition result

`result`

The following describes result.

Field	Type	Required	Description
`isConfident`	Boolean	-	Whether it has details for each type `true` \| `false` `true`: has `false`: doesn't have
`ic`	Object	-	Resident registration card information
`ic.name`	Array	-	Name details
`ic.personalNum`	Array	-	Resident registration number details
`ic.address`	Array	-	Address details
`ic.issueDate`	Array	-	Issuance date details
`ic.authority`	Array	-	Issuing authority details
`rois`	Array	-	Object border position information
`idType`	String	-	ID card type `ID Card`

name

The following describes ic.name.

Field	Type	Required	Description
`text`	String	-	Recognized name text
`formatted`	Object	-	Recognized name text information
`formatted.value`	String	-	Recognized name text value
`keyText`	String	-	Key value of recognized name text
`confidenceScore`	Float	-	Confidence of recognized name text 0 - 1 The higher the confidence value, the more accurate the text is
`boundingPolys`	Array	-	boundingPoly details
`maskingPolys`	Array	-	maskingPoly details

personalNum

The following describes ic.personalNum.

Field	Type	Required	Description
`text`	String	-	Recognized resident registration number text
`formatted`	Object	-	Recognized resident registration number text information
`formatted.value`	String	-	Recognized resident registration number text value
`keyText`	String	-	Key value of recognized resident registration number text
`confidenceScore`	Float	-	Confidence of recognized resident registration number text 0 - 1 The higher the confidence value, the more accurate the text is
`boundingPolys`	Array	-	boundingPoly details
`maskingPolys`	Array	-	maskingPoly details

address

The following describes ic.address.

Field	Type	Required	Description
`text`	String	-	Recognized address text
`formatted`	Object	-	Recognized address text information
`formatted.value`	String	-	Recognized address text value
`keyText`	String	-	Key value of recognized address text
`confidenceScore`	Float	-	Confidence of recognized address text 0 - 1 The higher the confidence value, the more accurate the text is
`boundingPolys`	Array	-	boundingPoly details
`maskingPolys`	Array	-	maskingPoly details

issueDate

The following describes ic.issueDate.

Field	Type	Required	Description
`text`	String	-	Recognized issuance date text
`formatted`	Object	-	Recognized issuance date text information
`formatted.year`	String	-	Year (yyyy) of recognized issuance date
`formatted.month`	String	-	Month (MM) of recognized issuance date
`formatted.day`	String	-	Day (dd) of recognized issuance date
`keyText`	String	-	Key value of recognized issuance date text
`confidenceScore`	Float	-	Confidence of recognized issuance date text 0 - 1 The higher the confidence value, the more accurate the text is
`boundingPolys`	Array	-	boundingPoly details
`maskingPolys`	Array	-	maskingPoly details

authority

The following describes ic.authority.

Field	Type	Required	Description
`text`	String	-	Recognized issuing authority text
`formatted`	Object	-	Recognized issuing authority text information
`formatted.value`	String	-	Recognized issuing authority text value
`keyText`	String	-	Key value of recognized issuing authority text
`confidenceScore`	Float	-	Confidence of recognized issuing authority text 0 - 1 The higher the confidence value, the more accurate the text is
`boundingPolys`	Array	-	boundingPoly details
`maskingPolys`	Array	-	maskingPoly details

rois

The following describes rois.

Field	Type	Required	Description
Field	Type	Required	Description
---	---	---	---
`x`	Float	-	Object border position X-axis coordinate value
`y`	Float	-	Object border position Y-axis coordinate value

`boundingPolys`

The following describes boundingPolys.

Field	Type	Required	Description
`vertices`	Array	-	vertices details

`maskingPolys`

The following describes maskingPolys.

Field	Type	Required	Description
`vertices`	Array	-	vertices details

`boundingPolyVertices`

The following describes boundingPolyVertices.

Field	Type	Required	Description
`x`	Float	-	X-axis coordinate value
`y`	Float	-	Y-axis coordinate value

Response status codes

For response status codes common to all CLOVA OCR APIs, see Common CLOVA OCR response status codes.

Response example

The response example is as follows:

Success

The following is a sample response upon a successful call.

{
    "version": "V2",
    "requestId": "1234",
    "timestamp": 1725406864631,
    "images": [
        {
            "uid": "{uid}",
            "name": "idcard_test",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "validationResult": {
                "result": "NO_REQUESTED"
            },
            "idCard": {
                "meta": {
                    "estimatedLanguage": "ko"
                },
                "result": {
                    "isConfident": true,
                    "ic": {
                        "name": [
                            {
                                "text": "Hong**",
                                "formatted": {
                                    "value": "Hong**"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 72.2125,
                                                "y": 116.6
                                            },
                                            {
                                                "x": 367.6875,
                                                "y": 116.6
                                            },
                                            {
                                                "x": 367.6875,
                                                "y": 165.625
                                            },
                                            {
                                                "x": 72.2125,
                                                "y": 165.625
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ],
                        "personalNum": [
                            {
                                "text": "800***-234****",
                                "formatted": {
                                    "value": "800***-234****"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 65.5875,
                                                "y": 181.52498
                                            },
                                            {
                                                "x": 363.71246,
                                                "y": 181.52498
                                            },
                                            {
                                                "x": 363.71246,
                                                "y": 216.63748
                                            },
                                            {
                                                "x": 65.5875,
                                                "y": 216.63748
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 211.13873,
                                                "y": 178.01373
                                            },
                                            {
                                                "x": 367.22372,
                                                "y": 178.01373
                                            },
                                            {
                                                "x": 367.22372,
                                                "y": 220.14873
                                            },
                                            {
                                                "x": 211.13873,
                                                "y": 220.14873
                                            }
                                        ]
                                    }
                                ]
                            }
                        ],
                        "address": [
                            {
                                "text": "Seoul***",
                                "formatted": {
                                    "value": "Seoul***"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 51.675,
                                                "y": 235.1875
                                            },
                                            {
                                                "x": 192.7875,
                                                "y": 235.1875
                                            },
                                            {
                                                "x": 192.7875,
                                                "y": 272.2875
                                            },
                                            {
                                                "x": 51.675,
                                                "y": 272.2875
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ],
                        "issueDate": [
                            {
                                "text": "2020.08.16",
                                "formatted": {
                                    "year": "2020",
                                    "month": "08",
                                    "day": "16"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 242.475,
                                                "y": 351.7875
                                            },
                                            {
                                                "x": 374.3125,
                                                "y": 351.7875
                                            },
                                            {
                                                "x": 374.3125,
                                                "y": 381.6
                                            },
                                            {
                                                "x": 242.475,
                                                "y": 381.6
                                            }
                                        ]
                                    },
                                ],
                                "maskingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 239.52966,
                                                "y": 349.0218
                                            },
                                            {
                                                "x": 424.9578,
                                                "y": 349.0217
                                            },
                                            {
                                                "x": 424.9578,
                                                "y": 384.3657
                                            },
                                            {
                                                "x": 239.52968,
                                                "y": 384.36578
                                            }
                                        ]
                                    }
                                ]
                            }
                        ],
                        "authority": [
                            {
                                "text": "Head of ** gu, Seoul**",
                                "formatted": {
                                    "value": "Head of ** gu, Seoul"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 146.53316,
                                                "y": 381.33884
                                            },
                                            {
                                                "x": 326.93195,
                                                "y": 383.12497
                                            },
                                            {
                                                "x": 326.47778,
                                                "y": 428.99695
                                            },
                                            {
                                                "x": 146.07898,
                                                "y": 427.21082
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ]
                    },
                    "rois": [
                        {
                            "vertices": [
                                {
                                    "x": 3.1388545,
                                    "y": 3.9956706
                                },
                                {
                                    "x": 754.52325,
                                    "y": -5.092327
                                },
                                {
                                    "x": 747.84045,
                                    "y": 473.14856
                                },
                                {
                                    "x": 2.264223,
                                    "y": 474.4076
                                }
                            ]
                        }
                    ],
                    "idtype": "ID Card"
                }
            }
        }
    ]
}

Failure

The following is a sample response upon a failed call.

{
    "version": "V2",
    "requestId": "1234",
    "timestamp": 1725235840459,
    "images": [
        {
            "uid": "{uid}",
            "name": "idcard_sample",
            "inferResult": "ERROR",
            "message": "Read page:0 error.",
            "validationResult": {
                "result": "NO_REQUESTED"
            }
        }
    ]
}

Was this article helpful?

What's Next

CLOVA OCR Validation

Table of contents

Request
Response

Resident registration card

Request

Request headers

Request body

If Content-Type: application/json

If Content-Type: multipart/form-data

images

Request example

If Content-Type: application/json

If Content-Type: multipart/form-data

Response

Response body

images

result

name

personalNum

address

issueDate

authority

rois

boundingPolys

maskingPolys

boundingPolyVertices

Response status codes

Response example

Success

Failure

What's Next

If `Content-Type: application/json`

If `Content-Type: multipart/form-data`

`images`

If `Content-Type: application/json`

If `Content-Type: multipart/form-data`

`images`

`result`

`boundingPolys`

`maskingPolys`

`boundingPolyVertices`