Passport
- Print
- PDF
Passport
- Print
- PDF
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 passports (Korean) 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
|
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
|
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
|
name | String | Required | Random image name
|
data | String | Required | Base64-encoded image data
|
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": "passport_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 'Content-Type: application/json' \
--header 'X-OCR-SECRET: {Secret key issued when registering the app}' \
--form 'message="{\"version\": \"V2\", \"requestId\": \"1234\", \"timestamp\": 0, \"images\": [{\"format\": \"png\", \"name\": \"passport_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
|
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 | - | Passport image UID
|
name | String | - | Passport image name
|
inferResult | String | - | Passport image recognition result
|
message | String | - | Result message |
validationResult | Object | - | Validity check result information |
validationResult.result | String | - | Validity check result code
|
validationResult.message | String | - | Validity check result details message
|
convertedImageInfo | Object | - | Converted image information
|
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
|
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
|
pp | Object | - | Passport information |
pp.type | Array | - | Passport type details |
pp.issueCountry | Array | - | Passport issuance country details |
pp.num | Array | - | Passport number details |
pp.surName | Array | - | Last name details |
pp.givenName | Array | - | Name details |
pp.nationality | Array | - | Nationality details |
pp.birthDate | Array | - | Date of birth details |
pp.sex | Array | - | Gender details |
pp.issueDate | Array | - | Issuance date details |
pp.expireDate | Array | - | Expiration date details |
pp.authority | Array | - | Issuing authority details |
pp.fullNameKor | Array | - | Full name details |
pp.mrz1 | Array | - | Machine readable zone 1 details |
pp.mrz2 | Array | - | Machine readable zone 2 details |
rois | Array | - | Object border position information |
idType | String | - | ID card type
|
type
The following describes pp.type.
| Field | Type | Required | Description |
|---|---|---|---|
text | String | - | Recognized type text |
formatted | Object | - | Recognized type text information |
formatted.value | String | - | Recognized type text value |
keyText | String | - | Key value of recognized type text |
confidenceScore | Float | - | Confidence of recognized type text
|
boundingPolys | Array | - | boundingPoly details |
maskingPolys | Array | - | maskingPoly details |
issueCountry
The following describes pp.issueCountry.
| Field | Type | Required | Description |
|---|---|---|---|
text | String | - | Recognized issuing country text |
keyText | String | - | Key value of recognized issuing country text |
confidenceScore | Float | - | Confidence of recognized issuing country text
|
boundingPolys | Array | - | boundingPoly 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
|
boundingPolys | Array | - | boundingPoly details |
maskingPolys | Array | - | maskingPoly details |
name
The following describes pp.surName and pp.GivenName.
| 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
|
boundingPolys | Array | - | boundingPoly details |
maskingPolys | Array | - | maskingPoly details |
nationality
The following describes pp.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
|
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
|
boundingPolys | Array | - | boundingPoly details |
maskingPolys | Array | - | maskingPoly details |
condition
The following describes pp.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
|
boundingPolys | Array | - | boundingPoly details |
maskingPolys | Array | - | maskingPoly details |
sex
The following describes pp.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
|
boundingPolys | Array | - | boundingPoly details |
maskingPolys | Array | - | maskingPoly details |
organDonation
The following describes pp.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
|
boundingPolys | Array | - | boundingPoly details |
maskingPolys | Array | - | maskingPoly details |
authority
The following describes pp.authority.
| Field | Type | Required | Description |
|---|---|---|---|
text | String | - | Recognized issuing authority text |
keyText | String | - | Key value of recognized issuing authority text |
confidenceScore | Float | - | Confidence of recognized issuing authority text
|
boundingPolys | Array | - | boundingPoly details |
fullNameKor
The following describes pp.fullNameKor.
| Field | Type | Required | Description |
|---|---|---|---|
text | String | - | Recognized full name text |
formatted | Object | - | Recognized full name text information |
formatted.value | String | - | Recognized full name text value |
keyText | String | - | Key value of recognized full name text |
confidenceScore | Float | - | Confidence of recognized full name text
|
boundingPolys | Array | - | boundingPoly details |
maskingPolys | Array | - | maskingPoly details |
mrz
The following describes mrz.
| Field | Type | Required | Description |
|---|---|---|---|
text | String | - | Recognized MRZ text |
formatted | Object | - | Recognized MRZ text information |
formatted.value | String | - | Recognized MRZ text value |
keyText | String | - | Key value of recognized MRZ text |
confidenceScore | Float | - | Confidence of recognized MRZ text
|
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": 1725412120101,
"images": [
{
"uid": "{uid}",
"name": "passport_test",
"inferResult": "SUCCESS",
"message": "SUCCESS",
"validationResult": {
"result": "NO_REQUESTED"
},
"idCard": {
"meta": {
"estimatedLanguage": "ko"
},
"result": {
"isConfident": true,
"pp": {
"type": [
{
"text": "PM",
"formatted": {
"value": "PM"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 187.23215,
"y": 428.7616
},
{
"x": 206.57947,
"y": 428.7616
},
{
"x": 206.57947,
"y": 439.99554
},
{
"x": 187.23215,
"y": 439.99554
}
]
}
],
"maskingPolys": []
}
],
"issueCountry": [
{
"text": "KOR",
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 234.04018,
"y": 428.7616
},
{
"x": 260.8768,
"y": 428.7616
},
{
"x": 260.8768,
"y": 439.99554
},
{
"x": 234.04018,
"y": 439.99554
}
]
}
]
}
],
"num": [
{
"text": "M123A****",
"formatted": {
"value": "M123A****"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 327.65625,
"y": 428.7616
},
{
"x": 395.68393,
"y": 428.7616
},
{
"x": 395.68393,
"y": 439.99554
},
{
"x": 327.65625,
"y": 439.99554
}
]
}
],
"maskingPolys": [
{
"vertices": [
{
"x": 326.53287,
"y": 427.6382
},
{
"x": 396.8073,
"y": 427.6382
},
{
"x": 396.8073,
"y": 441.11893
},
{
"x": 326.53287,
"y": 441.11893
}
]
}
]
}
],
"surName": [
{
"text": "HONG",
"formatted": {
"value": "HONG"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 187.23215,
"y": 454.97412
},
{
"x": 224.05446,
"y": 454.97412
},
{
"x": 224.05446,
"y": 466.83215
},
{
"x": 187.23215,
"y": 466.83215
}
]
}
],
"maskingPolys": []
}
],
"givenName": [
{
"text": "GIL****",
"formatted": {
"value": "GIL****"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 187.23215,
"y": 481.8107
},
{
"x": 241.52946,
"y": 481.8107
},
{
"x": 241.52946,
"y": 493.66876
},
{
"x": 187.23215,
"y": 493.66876
}
]
}
],
"maskingPolys": []
}
],
"nationality": [
{
"text": "REPUBLIC OF KOREA",
"formatted": {
"value": "REPUBLIC OF KOREA"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 187.74973,
"y": 569.2035
},
{
"x": 244.59932,
"y": 568.4555
},
{
"x": 244.73523,
"y": 578.78436
},
{
"x": 187.88564,
"y": 579.53235
}
]
}
],
"maskingPolys": []
}
],
"birthDate": [
{
"text": "February 1, 1987",
"formatted": {
"year": "1987",
"month": "02",
"day": "01"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 186.60803,
"y": 534.8598
},
{
"x": 204.70714,
"y": 534.8598
},
{
"x": 204.70714,
"y": 547.96606
},
{
"x": 186.60803,
"y": 547.96606
}
]
}
],
"maskingPolys": []
}
],
"sex": [
{
"text": "F んだ",
"formatted": {
"value": "F"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 187.23215,
"y": 558.57587
},
{
"x": 204.08304,
"y": 558.57587
},
{
"x": 204.08304,
"y": 565.4411
},
{
"x": 187.23215,
"y": 565.4411
}
]
}
],
"maskingPolys": []
}
],
"issueDate": [
{
"text": "August 15, 2020",
"formatted": {
"year": "2020",
"month": "08",
"day": "15"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 187.23215,
"y": 594.7741
},
{
"x": 202.83482,
"y": 594.7741
},
{
"x": 202.83482,
"y": 605.3839
},
{
"x": 187.23215,
"y": 605.3839
}
]
}
],
"maskingPolys": []
}
],
"expireDate": [
{
"text": "August 15, 2030",
"formatted": {
"year": "2030",
"month": "08",
"day": "15"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 328.28036,
"y": 594.15
},
{
"x": 343.25894,
"y": 594.15
},
{
"x": 343.25894,
"y": 605.3839
},
{
"x": 328.28036,
"y": 605.3839
}
]
}
],
"maskingPolys": []
}
],
"authority": [
{
"text": "MINISTRY OF FOREIGN AFFAIRS",
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 328.28036,
"y": 569.8098
},
{
"x": 373.84018,
"y": 569.8098
},
{
"x": 373.84018,
"y": 577.9232
},
{
"x": 328.28036,
"y": 577.9232
}
]
}
]
}
],
"fullNameKor": [
{
"text": "Hong**",
"formatted": {
"value": "Hong**"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 186.60803,
"y": 506.775
},
{
"x": 223.43036,
"y": 506.775
},
{
"x": 223.43036,
"y": 522.3777
},
{
"x": 186.60803,
"y": 522.3777
}
]
}
],
"maskingPolys": []
}
],
"mrz1": [
{
"text": "PMKORHONG<<GIL****<<<<<<<<<<<<<<<<<<<<<<<<<<<<",
"formatted": {
"value": "PMKORHONG<<GIL****<<<<<<<<<<<<<<<<<<<<<<<<<<"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 32.45357,
"y": 638.4616
},
{
"x": 484.93124,
"y": 638.4616
},
{
"x": 484.93124,
"y": 650.9437
},
{
"x": 32.45357,
"y": 650.9437
}
]
}
],
"maskingPolys": [
{
"vertices": [
{
"x": 31.20536,
"y": 637.2134
},
{
"x": 486.17944,
"y": 637.2134
},
{
"x": 486.17944,
"y": 652.19196
},
{
"x": 31.20536,
"y": 652.19196
}
]
}
]
}
],
"mrz2": [
{
"text": "M123A45670K0R*****0000000000000000",
"formatted": {
"value": "M123A45670K0R*****00000000000000"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 31.829464,
"y": 663.42584
},
{
"x": 486.17938,
"y": 663.42584
},
{
"x": 486.17938,
"y": 677.7803
},
{
"x": 31.829464,
"y": 677.7803
}
]
}
],
"maskingPolys": [
{
"vertices": [
{
"x": 30.39402,
"y": 661.9904
},
{
"x": 487.61484,
"y": 661.9904
},
{
"x": 487.61484,
"y": 679.2157
},
{
"x": 30.39402,
"y": 679.2157
}
]
}
]
}
]
},
"rois": [
{
"vertices": [
{
"x": 10.000834,
"y": 364.93756
},
{
"x": 500.2946,
"y": 364.6102
},
{
"x": 501.1391,
"y": 692.69543
},
{
"x": 6.990344,
"y": 694.3484
}
]
}
],
"idtype": "Passport"
}
}
}
]
}
Failure
The following is a sample response upon a failed call.
{
"version": "V2",
"requestId": "1234",
"timestamp": 1725235840459,
"images": [
{
"uid": "{uid}",
"name": "passport_test",
"inferResult": "ERROR",
"message": "Read page:0 error.",
"validationResult": {
"result": "NO_REQUESTED"
}
}
]
}
Was this article helpful?