Driver's license

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 driver's licenses 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": "driverlicense_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\": \"driverlicense_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	-	Driver's license image UID Use for API validity checks
`name`	String	-	Driver's license image name Use to identify images and check response results
`inferResult`	String	-	Driver's license 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
`dl`	Object	-	Driver's license information
`dl.type`	Array	-	Driver's license type details
`dl.num`	Array	-	Driver's license number details
`dl.name`	Array	-	Name details
`dl.personalNum`	Array	-	Resident registration number details
`dl.address`	Array	-	Address details
`dl.renewStartDate`	Array	-	Renewal period start date details
`dl.renewEndDate`	Array	-	Renewal period end date details
`dl.condition`	Array	-	Driver's license condition details
`dl.code`	Array	-	Driver's license code details
`dl.organDonation`	Array	-	Organ and tissue donation registration details
`dl.issueDate`	Array	-	Issuance date details
`dl.authority`	Array	-	Issuing authority details
`rois`	Array	-	Object border position information
`idType`	String	-	ID card type `Driver's License`

type

The following describes dl.type.

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

num

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

name

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

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

condition

The following describes dl.condition.

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

code

The following describes dl.code.

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

organDonation

The following describes dl.organDonation.

Field	Type	Required	Description
`text`	String	-	Recognized organ and tissue donation text
`keyText`	String	-	Key value of recognized organ and tissue donation text
`confidenceScore`	Float	-	Confidence of recognized organ and tissue donation 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 dl.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": 1725409664957,
    "images": [
        {
            "uid": "{uid}",
            "name": "driverlicense_test",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "validationResult": {
                "result": "NO_REQUESTED"
            },
            "idCard": {
                "meta": {
                    "estimatedLanguage": "ko"
                },
                "result": {
                    "isConfident": true,
                    "dl": {
                        "type": [
                            {
                                "text": "Class 1 Large Class 1 Ordinary Class 1 Small Special (Large tow, Small tow, Rescue) Class 2 Ordinary Class 2 Small Motorcycle",
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 6.875,
                                                "y": 20.625
                                            },
                                            {
                                                "x": 77.5,
                                                "y": 20.625
                                            },
                                            {
                                                "x": 77.5,
                                                "y": 42.5
                                            },
                                            {
                                                "x": 6.875,
                                                "y": 42.5
                                            }
                                        ]
                                    }
                                ]
                            }
                        ],
                        "num": [
                            {
                                "text": "**-**-******-**",
                                "formatted": {
                                    "value": "**-**-******-**"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 270.66333,
                                                "y": 81.96319
                                            },
                                            {
                                                "x": 615.7258,
                                                "y": 83.148964
                                            },
                                            {
                                                "x": 615.59015,
                                                "y": 122.63947
                                            },
                                            {
                                                "x": 270.52765,
                                                "y": 121.4537
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 404.75287,
                                                "y": 78.474884
                                            },
                                            {
                                                "x": 619.68854,
                                                "y": 79.213486
                                            },
                                            {
                                                "x": 619.5257,
                                                "y": 126.60209
                                            },
                                            {
                                                "x": 404.59003,
                                                "y": 125.86349
                                            }
                                        ]
                                    }
                                ]
                            }
                        ],
                        "name": [
                            {
                                "text": "Hong**",
                                "formatted": {
                                    "value": "Hong**"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 268.125,
                                                "y": 130.0
                                            },
                                            {
                                                "x": 358.75,
                                                "y": 130.0
                                            },
                                            {
                                                "x": 358.75,
                                                "y": 164.375
                                            },
                                            {
                                                "x": 268.125,
                                                "y": 164.375
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ],
                        "personalNum": [
                            {
                                "text": "******-*******",
                                "formatted": {
                                    "value": "******-*******"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 264.71436,
                                                "y": 161.93407
                                            },
                                            {
                                                "x": 496.74896,
                                                "y": 159.34149
                                            },
                                            {
                                                "x": 497.16132,
                                                "y": 196.25029
                                            },
                                            {
                                                "x": 265.1267,
                                                "y": 198.84286
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 376.99954,
                                                "y": 156.98816
                                            },
                                            {
                                                "x": 500.39862,
                                                "y": 155.60939
                                            },
                                            {
                                                "x": 500.89346,
                                                "y": 199.89995
                                            },
                                            {
                                                "x": 377.49442,
                                                "y": 201.27872
                                            }
                                        ]
                                    }
                                ]
                            }
                        ],
                        "address": [
                            {
                                "text": "Seoul***",
                                "formatted": {
                                    "value": "Seoul***"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 263.125,
                                                "y": 232.5
                                            },
                                            {
                                                "x": 301.25,
                                                "y": 232.5
                                            },
                                            {
                                                "x": 301.25,
                                                "y": 258.75
                                            },
                                            {
                                                "x": 263.125,
                                                "y": 258.75
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ],
                        "renewStartDate": [
                            {
                                "text": "2029.01.01",
                                "formatted": {
                                    "year": "2029",
                                    "month": "01",
                                    "day": "01"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 402.39316,
                                                "y": 300.80316
                                            },
                                            {
                                                "x": 531.2038,
                                                "y": 300.008
                                            },
                                            {
                                                "x": 531.3579,
                                                "y": 324.9801
                                            },
                                            {
                                                "x": 402.54727,
                                                "y": 325.7752
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ],
                        "renewEndDate": [
                            {
                                "text": "2029 12.31",
                                "formatted": {
                                    "year": "2029",
                                    "month": "12",
                                    "day": "31"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 425.987,
                                                "y": 332.6018
                                            },
                                            {
                                                "x": 481.51587,
                                                "y": 329.9576
                                            },
                                            {
                                                "x": 482.8507,
                                                "y": 357.98932
                                            },
                                            {
                                                "x": 427.32184,
                                                "y": 360.6335
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ],
                        "condition": [
                            {
                                "text": "Geon 8",
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 341.875,
                                                "y": 361.25
                                            },
                                            {
                                                "x": 367.5,
                                                "y": 361.25
                                            },
                                            {
                                                "x": 367.5,
                                                "y": 388.75
                                            },
                                            {
                                                "x": 341.875,
                                                "y": 388.75
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ],
                        "code": [
                            {
                                "text": "H1***",
                                "formatted": {
                                    "value": "H1***"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 582.5,
                                                "y": 351.87497
                                            },
                                            {
                                                "x": 690.625,
                                                "y": 351.87497
                                            },
                                            {
                                                "x": 690.625,
                                                "y": 379.99997
                                            },
                                            {
                                                "x": 582.5,
                                                "y": 379.99997
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ],
                        "organDonation": [
                            {
                                "text": "Organ and tissue donation",
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 59.375,
                                                "y": 454.375
                                            },
                                            {
                                                "x": 105.625,
                                                "y": 454.375
                                            },
                                            {
                                                "x": 105.625,
                                                "y": 479.375
                                            },
                                            {
                                                "x": 59.375,
                                                "y": 479.375
                                            }
                                        ]
                                    }
                                ]
                            }
                        ],
                        "issueDate": [
                            {
                                "text": "2019.09.10",
                                "formatted": {
                                    "year": "2019",
                                    "month": "09",
                                    "day": "10"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 249.375,
                                                "y": 443.75
                                            },
                                            {
                                                "x": 368.125,
                                                "y": 443.75
                                            },
                                            {
                                                "x": 368.125,
                                                "y": 475.0
                                            },
                                            {
                                                "x": 249.375,
                                                "y": 475.0
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 246.28294,
                                                "y": 440.82266
                                            },
                                            {
                                                "x": 411.842,
                                                "y": 440.82266
                                            },
                                            {
                                                "x": 411.842,
                                                "y": 477.9273
                                            },
                                            {
                                                "x": 246.28294,
                                                "y": 477.9273
                                            }
                                        ]
                                    }
                                ]
                            }
                        ],
                        "authority": [
                            {
                                "text": "Seoul Metropolitan Police Agency",
                                "formatted": {
                                    "value": "Seoul Metropolitan Police Commissioner"
                                },
                                "keyText": "",
                                "confidenceScore": 0.0,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 402.79678,
                                                "y": 436.09882
                                            },
                                            {
                                                "x": 651.7483,
                                                "y": 433.49652
                                            },
                                            {
                                                "x": 652.1772,
                                                "y": 474.53296
                                            },
                                            {
                                                "x": 403.2257,
                                                "y": 477.13528
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ]
                    },
                    "rois": [
                        {
                            "vertices": [
                                {
                                    "x": -4.7505364,
                                    "y": -5.066147
                                },
                                {
                                    "x": 712.13684,
                                    "y": -2.8448386
                                },
                                {
                                    "x": 714.93665,
                                    "y": 480.58566
                                },
                                {
                                    "x": -2.094209,
                                    "y": 492.42014
                                }
                            ]
                        }
                    ],
                    "idtype": "Driver's License"
                }
            }
        }
    ]
}

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

Resident registration card

Table of contents

Request
Response

Driver's license

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

type

num

name

personalNum

address

Date object information

condition

code

organDonation

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`