Alien 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 alien 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": "alienRegistration_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\": 0, \"images\": [{\"format\": \"png\", \"name\": \"alienRegistration_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	-	Alien registration card image UID Use for API validity checks
`name`	String	-	Alien registration card image name Use to identify images and check response results
`inferResult`	String	-	Alien 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
`ac`	Object	-	Alien registration card information
`ac.alienRegNum`	Array	-	Alien registration number details
`ac.sex`	Array	-	Gender details
`ac.name`	Array	-	Name details
`ac.nationality`	Array	-	Nationality details
`ac.visaType`	Array	-	Visa type details
`ac.issueDate`	Array	-	Issuance date details
`ac.authority`	Array	-	Issuing authority details
`ac.authorityEng`	Array	-	Issuing authority English details
`ac.alienRegNumEtc`	Array	-	Details other than alien registration number
`rois`	Array	-	Object border position information
`idType`	String	-	ID card type `Alien Registration Card`

alienRegNum

The following describes ac.alienRegNum.

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

sex

The following describes ac.sex.

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

name

The following describes ac.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

nationality

The following describes ac.nationality.

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

visaType

The following describes ac.visaType.

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

num

The following describes pp.num.

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

Date object information

The following describes the date object.

Field	Type	Required	Description
`text`	String	-	Recognized date text
`formatted`	Object	-	Recognized date text information
`formatted.year`	String	-	Year (yyyy) of recognized date
`formatted.month`	String	-	Month (MM) of recognized date
`formatted.day`	String	-	Day (dd) of recognized date
`keyText`	String	-	Key value of recognized date text
`confidenceScore`	Float	-	Confidence of recognized 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 ac.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

authorityEng

The following describes ac.authorityEng.

Field	Type	Required	Description
`text`	String	-	Recognized issuing authority English 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

alienRegNumEtc

The following describes ac.alienRegNumEtc.

Field	Type	Required	Description
`text`	String	-	Recognized text
`formatted`	Object	-	Recognized text information
`formatted.value`	String	-	Recognized text value
`keyText`	String	-	Key value of recognized text
`confidenceScore`	Float	-	Confidence of recognized 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": 1725415136556,
    "images": [
        {
            "uid": "{uid}",
            "name": "alienRegistration_test",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "validationResult": {
                "result": "NO_REQUESTED"
            },
            "idCard": {
                "meta": {
                    "estimatedLanguage": "ko"
                },
                "result": {
                    "isConfident": true,
                    "ac": {
                        "alienRegNum": [
                            {
                                "text": "123***-123****",
                                "formatted": {
                                    "value": "123***-123****"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 250.44644,
                                                "y": 86.428566
                                            },
                                            {
                                                "x": 399.24106,
                                                "y": 86.428566
                                            },
                                            {
                                                "x": 399.24106,
                                                "y": 104.10713
                                            },
                                            {
                                                "x": 250.44644,
                                                "y": 104.10713
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 323.0759,
                                                "y": 84.660706
                                            },
                                            {
                                                "x": 401.0089,
                                                "y": 84.660706
                                            },
                                            {
                                                "x": 401.0089,
                                                "y": 105.874985
                                            },
                                            {
                                                "x": 323.0759,
                                                "y": 105.874985
                                            }
                                        ]
                                    }
                                ]
                            }
                        ],
                        "sex": [
                            {
                                "text": "F",
                                "formatted": {
                                    "value": "F"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 457.27267,
                                                "y": 86.69321
                                            },
                                            {
                                                "x": 491.81177,
                                                "y": 87.496445
                                            },
                                            {
                                                "x": 491.4664,
                                                "y": 102.34618
                                            },
                                            {
                                                "x": 456.92734,
                                                "y": 101.542946
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ],
                        "name": [
                            {
                                "text": "HONG S*******",
                                "formatted": {
                                    "value": "HONG S*******"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 250.30173,
                                                "y": 137.56241
                                            },
                                            {
                                                "x": 307.85138,
                                                "y": 136.8519
                                            },
                                            {
                                                "x": 308.07855,
                                                "y": 155.25519
                                            },
                                            {
                                                "x": 250.52892,
                                                "y": 155.96568
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ],
                        "nationality": [
                            {
                                "text": "REPUBLIC OF UTOPIA",
                                "formatted": {
                                    "value": "REPUBLIC OF UTOPIA"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 251.42857,
                                                "y": 180.71428
                                            },
                                            {
                                                "x": 344.24106,
                                                "y": 180.71428
                                            },
                                            {
                                                "x": 344.24106,
                                                "y": 198.88393
                                            },
                                            {
                                                "x": 251.42857,
                                                "y": 198.88393
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ],
                        "visaType": [
                            {
                                "text": "Corporate investor (D-8)",
                                "formatted": {
                                    "value": "Corporate investor (D-8)"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 250.44643,
                                                "y": 225.40178
                                            },
                                            {
                                                "x": 312.8125,
                                                "y": 225.40178
                                            },
                                            {
                                                "x": 312.8125,
                                                "y": 245.04465
                                            },
                                            {
                                                "x": 250.44643,
                                                "y": 245.04465
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ],
                        "issueDate": [
                            {
                                "text": "2011.1.1 1234.",
                                "formatted": {
                                    "year": "2011",
                                    "month": "01",
                                    "day": "01"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 71.69643,
                                                "y": 292.67856
                                            },
                                            {
                                                "x": 102.63393,
                                                "y": 292.67856
                                            },
                                            {
                                                "x": 102.63393,
                                                "y": 302.00894
                                            },
                                            {
                                                "x": 71.69643,
                                                "y": 302.00894
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 69.91906,
                                                "y": 290.60785
                                            },
                                            {
                                                "x": 485.82584,
                                                "y": 262.38263
                                            },
                                            {
                                                "x": 486.8961,
                                                "y": 278.1529
                                            },
                                            {
                                                "x": 70.989296,
                                                "y": 306.3781
                                            }
                                        ]
                                    }
                                ]
                            }
                        ],
                        "authority": [
                            {
                                "text": "Director of Seoul Immigration Office",
                                "formatted": {
                                    "value": "Director of Seoul Immigration Office"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 300.07544,
                                                "y": 285.12625
                                            },
                                            {
                                                "x": 492.13126,
                                                "y": 285.91016
                                            },
                                            {
                                                "x": 492.02887,
                                                "y": 310.99646
                                            },
                                            {
                                                "x": 299.97308,
                                                "y": 310.21255
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ],
                        "authorityEng": [
                            {
                                "text": "CHIEF, SEOUL IMMIGRATION OFFICE",
                                "formatted": {
                                    "value": "CHIEF, SEOUL IMMIGRATION OFFICE"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 302.00894,
                                                "y": 308.88394
                                            },
                                            {
                                                "x": 338.3482,
                                                "y": 308.88394
                                            },
                                            {
                                                "x": 338.3482,
                                                "y": 321.1607
                                            },
                                            {
                                                "x": 302.00894,
                                                "y": 321.1607
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ],
                        "alienRegNumEtc": [
                            {
                                "text": "B4***",
                                "formatted": {
                                    "value": "B4***"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 128.6607,
                                                "y": 292.67853
                                            },
                                            {
                                                "x": 160.58034,
                                                "y": 292.67853
                                            },
                                            {
                                                "x": 160.58034,
                                                "y": 301.51782
                                            },
                                            {
                                                "x": 128.6607,
                                                "y": 301.51782
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 127.77678,
                                                "y": 291.7946
                                            },
                                            {
                                                "x": 161.46426,
                                                "y": 291.7946
                                            },
                                            {
                                                "x": 161.46426,
                                                "y": 302.40176
                                            },
                                            {
                                                "x": 127.77678,
                                                "y": 302.40176
                                            }
                                        ]
                                    }
                                ]
                            }
                        ]
                    },
                    "rois": [
                        {
                            "vertices": [
                                {
                                    "x": 11.189065,
                                    "y": 9.545465
                                },
                                {
                                    "x": 537.28156,
                                    "y": 9.624473
                                },
                                {
                                    "x": 538.10034,
                                    "y": 341.7781
                                },
                                {
                                    "x": 11.295485,
                                    "y": 342.03995
                                }
                            ]
                        }
                    ],
                    "idtype": "Alien Registration Card"
                }
            }
        }
    ]
}

Failure

The following is a sample response upon a failed call.

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

Was this article helpful?

What's Next

Driver's license

Table of contents

Request
Response

Alien 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

alienRegNum

sex

name

nationality

visaType

num

Date object information

authority

authorityEng

alienRegNumEtc

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`