Business 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 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 See Common object information
`nameFurigana`	Array	-	Furigana name information See Common object information Respond only if Furigana name information (`nameCard.meta.estimatedLanguage`) is Japanese (`ja`)
`company`	Array	-	Company information See Common object information
`address`	Array	-	Address information See Common object information
`position`	Array	-	Job title information See Common object information
`department`	Array	-	Department information See Common object information
`mobile`	Array	-	Mobile phone information See Common object information
`tel`	Array	-	Phone information See Common object information
`fax`	Array	-	Fax information See Common object information
`email`	Array	-	Email information See Common object information
`homepage`	Array	-	Website information See Common object 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"
            }
        }
    ]
}

Was this article helpful?

What's Next

Business registration certificate

Table of contents

Request
Response

Business 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

Common object information

boundingPolys

maskingPolys

vertices

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`

`vertices`