Business card

Prev Next

Available in Classic and VPC

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

Request

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

Method URI
POST /name-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/name-card' \
--header 'Content-Type: application/json' \
--header 'X-OCR-SECRET: {Secret key issued when registering the app}' \
--data '{
    "version": "V2",
    "requestId": "1234",
    "timestamp": 0,
    "images": [
        { 
            "format": "jpg", 
            "name": "namecard_test2",
            "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/name-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\": \"jpg\", \"name\": \"namecard_test\"}]}"' \
--form 'file={file}.jpg"'

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 - Business card image UID
  • Use for API validity checks
name String - Business card image name
  • Use to identify images and check response results
inferResult String - Business 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
nameCard Object - Business card details
nameCard.meta Object - Meta information
nameCard.meta.estimatedLanguage String - OCR estimated language
  • ko | en | ja
    • ko:Korean
    • en: English
    • ja: Japanese
nameCard.result Object - Business card OCR recognition result

result

The following describes result.

Field Type Required Description
name Array - Name information
nameFurigana Array - Furigana name information
company Array - Company information
address Array - Address information
position Array - Job title information
department Array - Department information
mobile Array - Mobile phone information
tel Array - Phone information
fax Array - Fax information
email Array - Email information
homepage Array - Website information

Common object information

The following describes the common objects.

Field Type Required Description
text String - Recognized text
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
boundingPoly Object - Bounding Poly information
boundingPolys Array - boundingPoly details
maskingPolys Array - maskingPoly details

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

vertices

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": 1725235494383,
    "images": [
        {
            "uid": "{uid}",
            "name": "namecard_test",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "validationResult": {
                "result": "NO_REQUESTED"
            },
            "nameCard": {
                "meta": {
                    "estimatedLanguage": "ko"
                },
                "result": {
                    "name": [
                        {
                            "text": "Kim**",
                            "keyText": "",
                            "confidenceScore": 0.0,
                            "boundingPolys": [
                                {
                                    "vertices": [
                                        {
                                            "x": 92.0,
                                            "y": 103.0
                                        },
                                        {
                                            "x": 218.0,
                                            "y": 103.0
                                        },
                                        {
                                            "x": 218.0,
                                            "y": 141.0
                                        },
                                        {
                                            "x": 92.0,
                                            "y": 141.0
                                        }
                                    ]
                                }
                            ],
                            "maskingPolys": []
                        }
                    ],
                    "company": [
                        {
                            "text": "** **Distributor",
                            "keyText": "",
                            "confidenceScore": 0.0,
                            "boundingPolys": [
                                {
                                    "vertices": [
                                        {
                                            "x": 90.0,
                                            "y": 255.0
                                        },
                                        {
                                            "x": 237.0,
                                            "y": 255.0
                                        },
                                        {
                                            "x": 237.0,
                                            "y": 284.0
                                        },
                                        {
                                            "x": 90.0,
                                            "y": 284.0
                                        }
                                    ]
                                }
                            ],
                            "maskingPolys": []
                        }
                    ],
                    "address": [
                        {
                            "text": "Seoul***",
                            "keyText": "",
                            "confidenceScore": 0.0,
                            "boundingPolys": [
                                {
                                    "vertices": [
                                        {
                                            "x": 91.0,
                                            "y": 287.0
                                        },
                                        {
                                            "x": 376.0,
                                            "y": 287.0
                                        },
                                        {
                                            "x": 376.0,
                                            "y": 312.0
                                        },
                                        {
                                            "x": 91.0,
                                            "y": 312.0
                                        }
                                    ]
                                }
                            ],
                            "maskingPolys": []
                        }
                    ],
                    "position": [
                        {
                            "text": "****",
                            "keyText": "",
                            "confidenceScore": 0.0,
                            "boundingPolys": [
                                {
                                    "vertices": [
                                        {
                                            "x": 226.0,
                                            "y": 114.0
                                        },
                                        {
                                            "x": 300.0,
                                            "y": 114.0
                                        },
                                        {
                                            "x": 300.0,
                                            "y": 138.0
                                        },
                                        {
                                            "x": 226.0,
                                            "y": 138.0
                                        }
                                    ]
                                }
                            ],
                            "maskingPolys": []
                        }
                    ],
                    "mobile": [
                        {
                            "text": "010********",
                            "keyText": "",
                            "confidenceScore": 0.0,
                            "boundingPolys": [
                                {
                                    "vertices": [
                                        {
                                            "x": 88.0,
                                            "y": 145.0
                                        },
                                        {
                                            "x": 300.0,
                                            "y": 145.0
                                        },
                                        {
                                            "x": 300.0,
                                            "y": 175.0
                                        },
                                        {
                                            "x": 88.0,
                                            "y": 175.0
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "tel": [
                        {
                            "text": "02-****-****",
                            "keyText": "",
                            "confidenceScore": 0.0,
                            "boundingPolys": [
                                {
                                    "vertices": [
                                        {
                                            "x": 89.0,
                                            "y": 311.0
                                        },
                                        {
                                            "x": 264.0,
                                            "y": 311.0
                                        },
                                        {
                                            "x": 264.0,
                                            "y": 333.0
                                        },
                                        {
                                            "x": 89.0,
                                            "y": 333.0
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "fax": [
                        {
                            "text": "02-****-****",
                            "keyText": "",
                            "confidenceScore": 0.0,
                            "boundingPolys": [
                                {
                                    "vertices": [
                                        {
                                            "x": 89.0,
                                            "y": 334.0
                                        },
                                        {
                                            "x": 264.0,
                                            "y": 334.0
                                        },
                                        {
                                            "x": 264.0,
                                            "y": 358.0
                                        },
                                        {
                                            "x": 89.0,
                                            "y": 358.0
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "email": [
                        {
                            "text": "****@****.net",
                            "keyText": "",
                            "confidenceScore": 0.0,
                            "boundingPolys": [
                                {
                                    "vertices": [
                                        {
                                            "x": 137.0,
                                            "y": 359.0
                                        },
                                        {
                                            "x": 312.0,
                                            "y": 359.0
                                        },
                                        {
                                            "x": 312.0,
                                            "y": 382.0
                                        },
                                        {
                                            "x": 137.0,
                                            "y": 382.0
                                        }
                                    ]
                                }
                            ],
                            "maskingPolys": []
                        }
                    ]
                }
            }
        }
    ]
}

Failure

The following is a sample response upon a failed call.

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