Receipt
    • PDF

    Receipt

    • PDF

    Article summary

    Available in Classic and VPC

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

    Request

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

    MethodURI
    POST/receipt

    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:

    FieldTypeRequiredDescription
    versionString-Version information
    • Only use V2
    requestIdStringRequiredRandom API call UUID
    timestampIntegerRequiredRandom API call time (timestamp)
    imagesArrayRequiredimages 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:

    FieldTypeRequiredDescription
    messageObjectRequiredRequest data information
    message.versionStringRequiredVersion information
    • Only use V2
    message.requestIdStringRequiredRandom API call UUID
    message.timestampIntegerRequiredRandom API call time (timestamp)
    message.imagesArrayRequiredimages details
    fileFileRequiredOCR recognition image file

    images

    The following describes images.

    FieldTypeRequiredDescription
    formatStringRequiredImage format
    • jpg | jpeg | png | pdf | tif | tiff
      • Image: jpg, jpeg, png
      • Single page: pdf, tif, tiff
    • Select and enter one of the image formats
    nameStringRequiredRandom image name
    • Use to identify images and check response results
    dataStringRequiredBase64-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/receipt' \
    --header 'Content-Type: application/json' \
    --header 'X-OCR-SECRET: {Secret key issued when registering the app}' \
    --data '{
        "version": "V2",
        "requestId": "4567",
        "timestamp": "0",
        "images": [
            {
                "format": "png",
                "data": "{Base64-encoded image data}",
                "name": "receipt_test2"
        }]
    }'
    

    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/receipt' \
    --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\": \"receipt_test\"}]}"' \
    --form 'file={file}"'
    

    Response

    This section describes the response format.

    Response body

    The response body includes the following data:

    FieldTypeRequiredDescription
    versionString-Version information
    • Only use V2
    requestIdString-Random API call UUID
    timestampInteger-API call time (timestamp)
    imagesArray-images details

    images

    The following describes images.

    FieldTypeRequiredDescription
    uidString-Receipt image UID
    • Use for API validity checks
    nameString-Receipt image name
    • Use to identify images and check response results
    inferResultString-Receipt image recognition result
    • SUCCESS | FAILURE | ERROR
      • SUCCESS: recognition successful
      • FAILURE: recognition failure
      • ERROR: recognition processing exception
    messageString-Result message
    validationResultObject-Validity check result information
    validationResult.resultString-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.messageString-Validity check result details message
    • This value is not always returned
    convertedImageInfoObject-Converted image information
    • If format is pdf or tiff
    • Coordinate values are set relative to the called image file
    convertedImageInfo.widthInteger-Converted image width
    convertedImageInfo.heightInteger-Converted image height
    convertedImageInfo.pageIndexInteger-Converted image page index
    receiptObject-Receipt details
    receipt.metaObject-Meta information
    receipt.meta.estimatedLanguageString-OCR estimated language
    • ko | en | ja
      • ko:Korean
      • en: English
      • ja: Japanese
    receipt.resultObject-Receipt OCR recognition result

    result

    The following describes receipt.result.

    FieldTypeRequiredDescription
    storeInfoObject-Store information
    storeInfo.nameObject-Store name details
    storeInfo.subNameObject-Branch name details
    storeInfo.bizNumObject-Store business registration number details
    storeInfo.movieNameObject-Movie ticket details
    storeInfo.addressesArray-Store address details
    storeInfo.telArray-Store phone number details
    paymentInfoObject-Payment information
    paymentInfo.dateObject-Payment date details
    paymentInfo.timeObject-Payment time details
    paymentInfo.cardInfoObject-Payment card information
    paymentInfo.cardInfo.companyObject-Credit card company details
    paymentInfo.cardInfo.numberObject-Card number details
    paymentInfo.confirmNumObject-Authorization number details
    subResultsArray-Product group information
    totalPriceObject-Total amount information
    totalPrice.priceObject-Total amount details
    subTotalArray-Grand total details

    addresses

    The following describes receipt.result.storeInfo.addresses.

    FieldTypeRequiredDescription
    textString-Recognized text
    formattedObject-Recognized text information
    formatted.valueString-Recognized text value
    keyTextString-Key value of recognized text
    confidenceScoreFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    boundingPolysArray-boundingPoly details
    maskingPolysArray-maskingPoly details

    tel

    The following describes receipt.result.storeInfo.tel.

    FieldTypeRequiredDescription
    textString-Recognized text
    formattedObject-Recognized text information
    formatted.valueString-Recognized text value
    keyTextString-Key value of recognized text
    confidenceScoreFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    boundingPolysArray-boundingPoly details
    maskingPolysArray-maskingPoly details

    subResults

    The following describes receipt.result.subResults.

    FieldTypeRequiredDescription
    itemsArray-Recognized product details

    items

    The following describes receipt.result.subResults.items.

    FieldTypeRequiredDescription
    nameObject-Item name details
    codeObject-Item code details
    countObject-Item quantity details
    priceObject-Item price information
    price.priceObject-Item price details
    price.unitPriceObject-Item unit price details

    subTotal

    The following describes receipt.result.subTotal.

    FieldTypeRequiredDescription
    taxPriceArray-VAT details
    discountPriceArray-Discount amount details

    taxPrice

    The following describes receipt.result.subTotal.taxPrice.

    FieldTypeRequiredDescription
    textString-Recognized text
    formattedObject-Recognized text information
    formatted.valueString-Recognized text value
    keyTextString-Key value of recognized text
    confidenceScoreFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    boundingPolysArray-boundingPoly details
    maskingPolysArray-maskingPoly details

    discountPrice

    The following describes receipt.result.subTotal.discountPrice.

    FieldTypeRequiredDescription
    textString-Recognized text
    formattedObject-Recognized text information
    formatted.valueString-Recognized text value
    keyTextString-Key value of recognized text
    confidenceScoreFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    boundingPolysArray-boundingPoly details
    maskingPolysArray-maskingPoly details

    Common object information

    The following describes the common objects.

    FieldTypeRequiredDescription
    textString-Recognized text
    formattedObject-Recognized text information
    formatted.valueString-Recognized text value
    keyTextString-Key value of recognized text
    confidenceScoreFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    boundingPolysArray-boundingPoly details
    maskingPolysArray-maskingPoly details

    Base object information

    The following describes the base object information.

    FieldTypeRequiredDescription
    textString-Recognized text
    keyTextString-Key value of recognized text
    confidenceScoreFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    boundingPolysArray-boundingPoly details
    maskingPolysArray-maskingPoly details

    Date object information

    The following describes the date object.

    FieldTypeRequiredDescription
    textString-Recognized text
    formattedObject-Recognized text information
    formatted.yearString-Year (yyyy) of recognized date
    formatted.monthString-Month (MM) of recognized date
    formatted.dayString-Day (dd) of recognized date
    keyTextString-Key value of recognized text
    confidenceScoreFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    boundingPolysArray-boundingPoly details
    maskingPolysArray-maskingPoly details

    Time object information

    The following describes the time object.

    FieldTypeRequiredDescription
    textString-Recognized text
    formattedObject-Recognized text information
    formatted.hourString-Hour (HH) of recognized time
    formatted.minuteString-Minute (MM) of recognized time
    formatted.secondString-Second (ss) of recognized time
    keyTextString-Key value of recognized text
    confidenceScoreFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    boundingPolysArray-boundingPoly details
    maskingPolysArray-maskingPoly details

    Unit price object information

    The following describes the unit price object.

    FieldTypeRequiredDescription
    textString-Recognized text
    formattedObject-Recognized text information
    formatted.valueString-Recognized text value
    keyTextString-Key value of recognized text
    confidenceScoreFloat-Confidence of recognized text
    • 0 - 1
    • The higher the confidence value, the more accurate the text is
    boundingPolysArray-boundingPoly details

    boundingPolys

    The following describes boundingPolys.

    FieldTypeRequiredDescription
    verticesArray-vertices details

    maskingPolys

    The following describes maskingPolys.

    FieldTypeRequiredDescription
    verticesArray-vertices details

    boundingPolyVertices

    The following describes boundingPolyVertices.

    FieldTypeRequiredDescription
    xFloat-X-axis coordinate value
    yFloat-Y-axis coordinate value

    Response status codes

    For information about the HTTP 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": 1724976333747,
        "images": [
            {
                "uid": "{uid}",
                "name": "receipt_test",
                "inferResult": "SUCCESS",
                "message": "SUCCESS",
                "validationResult": {
                    "result": "NO_REQUESTED"
                },
                "receipt": {
                    "meta": {
                        "estimatedLanguage": "ko"
                    },
                    "result": {
                        "storeInfo": {
                            "name": {
                                "text": "**Mart",
                                "formatted": {
                                    "value": "**Mart"
                                },
                                "keyText": "",
                                "confidenceScore": 0.95703,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 32.0,
                                                "y": 196.0
                                            },
                                            {
                                                "x": 164.0,
                                                "y": 196.0
                                            },
                                            {
                                                "x": 164.0,
                                                "y": 232.0
                                            },
                                            {
                                                "x": 32.0,
                                                "y": 232.0
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            },
                            "subName": {
                                "text": "**points",
                                "keyText": "",
                                "confidenceScore": 0.85623,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 164.0,
                                                "y": 196.0
                                            },
                                            {
                                                "x": 263.0,
                                                "y": 196.0
                                            },
                                            {
                                                "x": 263.0,
                                                "y": 232.0
                                            },
                                            {
                                                "x": 164.0,
                                                "y": 232.0
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            },
                            "bizNum": {
                                "text": "***-**-*****",
                                "formatted": {
                                    "value": "***-**-*****"
                                },
                                "keyText": "",
                                "confidenceScore": 0.93726,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 30.0,
                                                "y": 237.0
                                            },
                                            {
                                                "x": 233.0,
                                                "y": 237.0
                                            },
                                            {
                                                "x": 233.0,
                                                "y": 270.0
                                            },
                                            {
                                                "x": 30.0,
                                                "y": 270.0
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            },
                            "addresses": [
                                {
                                    "text": "Seoul***",
                                    "formatted": {
                                        "value": "Gyeongsangbuk-do***"
                                    },
                                    "keyText": "",
                                    "confidenceScore": 0.94554,
                                    "boundingPolys": [
                                        {
                                            "vertices": [
                                                {
                                                    "x": 33.0,
                                                    "y": 272.0
                                                },
                                                {
                                                    "x": 168.0,
                                                    "y": 274.0
                                                },
                                                {
                                                    "x": 167.0,
                                                    "y": 311.0
                                                },
                                                {
                                                    "x": 33.0,
                                                    "y": 309.0
                                                }
                                            ]
                                        },
    
                                    ],
                                    "maskingPolys": []
                                }
                            ],
                            "tel": [
                                {
                                    "text": "***)***-****",
                                    "formatted": {
                                        "value": "**********"
                                    },
                                    "keyText": "TEL:",
                                    "confidenceScore": 0.90208,
                                    "boundingPolys": [
                                        {
                                            "vertices": [
                                                {
                                                    "x": 320.0,
                                                    "y": 238.0
                                                },
                                                {
                                                    "x": 525.0,
                                                    "y": 238.0
                                                },
                                                {
                                                    "x": 525.0,
                                                    "y": 271.0
                                                },
                                                {
                                                    "x": 320.0,
                                                    "y": 271.0
                                                }
                                            ]
                                        }
                                    ]
                                }
                            ]
                        },
                        "paymentInfo": {
                            "date": {
                                "text": "2014-01-21 (Tue)",
                                "formatted": {
                                    "year": "2014",
                                    "month": "01",
                                    "day": "21"
                                },
                                "keyText": "",
                                "confidenceScore": 0.46487,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 30.0,
                                                "y": 394.0
                                            },
                                            {
                                                "x": 200.0,
                                                "y": 394.0
                                            },
                                            {
                                                "x": 200.0,
                                                "y": 428.0
                                            },
                                            {
                                                "x": 30.0,
                                                "y": 428.0
                                            }
                                        ]
                                    },
                                    {
                                        "vertices": [
                                            {
                                                "x": 304.0,
                                                "y": 394.0
                                            },
                                            {
                                                "x": 360.0,
                                                "y": 394.0
                                            },
                                            {
                                                "x": 360.0,
                                                "y": 429.0
                                            },
                                            {
                                                "x": 304.0,
                                                "y": 429.0
                                            }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            },
                            "time": {
                                "text": "16:53",
                                "formatted": {
                                    "hour": "16",
                                    "minute": "53",
                                    "second": "00"
                                },
                                "keyText": "",
                                "confidenceScore": 0.92913,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 210.0,
                                                "y": 394.0
                                            },
                                            {
                                                "x": 304.0,
                                                "y": 394.0
                                            },
                                            {
                                                "x": 304.0,
                                                "y": 429.0
                                            },
                                            {
                                                "x": 210.0,
                                                "y": 429.0
                                            }
                                        ]
                                    }
                                ]
                            },
                            "cardInfo": {
                                "company": {
                                    "text": "**Card",
                                    "formatted": {
                                        "value": "**Card"
                                    },
                                    "keyText": "[Credit card company name]",
                                    "confidenceScore": 0.92768,
                                    "boundingPolys": [
                                        {
                                            "vertices": [
                                                {
                                                    "x": 252.0,
                                                    "y": 1104.0
                                                },
                                                {
                                                    "x": 391.0,
                                                    "y": 1104.0
                                                },
                                                {
                                                    "x": 391.0,
                                                    "y": 1141.0
                                                },
                                                {
                                                    "x": 252.0,
                                                    "y": 1141.0
                                                }
                                            ]
                                        }
                                    ],
                                    "maskingPolys": []
                                },
                                "number": {
                                    "text": "37L 80-****-",
                                    "formatted": {
                                        "value": "37L 80-****-"
                                    },
                                    "keyText": "[Card number]",
                                    "confidenceScore": 0.35504,
                                    "boundingPolys": [
                                        {
                                            "vertices": [
                                                {
                                                    "x": 227.0,
                                                    "y": 1025.0
                                                },
                                                {
                                                    "x": 311.0,
                                                    "y": 1025.0
                                                },
                                                {
                                                    "x": 311.0,
                                                    "y": 1063.0
                                                },
                                                {
                                                    "x": 227.0,
                                                    "y": 1063.0
                                                }
                                            ]
                                        },
                                        {
                                            "vertices": [
                                                {
                                                    "x": 368.0,
                                                    "y": 1030.0
                                                },
                                                {
                                                    "x": 491.0,
                                                    "y": 1030.0
                                                },
                                                {
                                                    "x": 491.0,
                                                    "y": 1057.0
                                                },
                                                {
                                                    "x": 368.0,
                                                    "y": 1057.0
                                                }
                                            ]
                                        }
                                    ],
                                    "maskingPolys": []
                                }
                            },
                            "confirmNum": {
                                "text": "2881****",
                                "keyText": "[Authorization number]",
                                "confidenceScore": 0.97677,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 254.0,
                                                "y": 1224.0
                                            },
                                            {
                                                "x": 394.0,
                                                "y": 1224.0
                                            },
                                            {
                                                "x": 394.0,
                                                "y": 1257.0
                                            },
                                            {
                                                "x": 254.0,
                                                "y": 1257.0
                                            }
                                        ]
                                    }
                                ]
                            }
                        },
                        "subResults": [
                            {
                                "items": [
                                    {
                                        "name": {
                                            "text": "***)*Ramen (mild flavor",
                                            "formatted": {
                                                "value": "***)*Ramen (mild flavor"
                                            },
                                            "keyText": "",
                                            "confidenceScore": 0.84299,
                                            "boundingPolys": [
                                                {
                                                    "vertices": [
                                                        {
                                                            "x": 32.0,
                                                            "y": 470.0
                                                        },
                                                        {
                                                            "x": 360.0,
                                                            "y": 470.0
                                                        },
                                                        {
                                                            "x": 360.0,
                                                            "y": 508.0
                                                        },
                                                        {
                                                            "x": 32.0,
                                                            "y": 508.0
                                                        }
                                                    ]
                                                }
                                            ],
                                            "maskingPolys": []
                                        },
                                        "count": {
                                            "text": "2",
                                            "formatted": {
                                                "value": "2"
                                            },
                                            "keyText": "",
                                            "confidenceScore": 0.94584,
                                            "boundingPolys": [
                                                {
                                                    "vertices": [
                                                        {
                                                            "x": 268.0,
                                                            "y": 511.0
                                                        },
                                                        {
                                                            "x": 328.0,
                                                            "y": 511.0
                                                        },
                                                        {
                                                            "x": 328.0,
                                                            "y": 547.0
                                                        },
                                                        {
                                                            "x": 268.0,
                                                            "y": 547.0
                                                        }
                                                    ]
                                                }
                                            ]
                                        },
                                        "price": {
                                            "price": {
                                                "text": "1,600",
                                                "formatted": {
                                                    "value": "1600"
                                                },
                                                "keyText": "",
                                                "confidenceScore": 0.95924,
                                                "boundingPolys": [
                                                    {
                                                        "vertices": [
                                                            {
                                                                "x": 596.0,
                                                                "y": 514.0
                                                            },
                                                            {
                                                                "x": 685.0,
                                                                "y": 514.0
                                                            },
                                                            {
                                                                "x": 685.0,
                                                                "y": 549.0
                                                            },
                                                            {
                                                                "x": 596.0,
                                                                "y": 549.0
                                                            }
                                                        ]
                                                    }
                                                ]
                                            },
                                            "unitPrice": {
                                                "text": "800",
                                                "formatted": {
                                                    "value": "800"
                                                },
                                                "keyText": "",
                                                "confidenceScore": 0.78166,
                                                "boundingPolys": [
                                                    {
                                                        "vertices": [
                                                            {
                                                                "x": 27.0,
                                                                "y": 513.0
                                                            },
                                                            {
                                                                "x": 90.0,
                                                                "y": 513.0
                                                            },
                                                            {
                                                                "x": 90.0,
                                                                "y": 547.0
                                                            },
                                                            {
                                                                "x": 27.0,
                                                                "y": 547.0
                                                            }
                                                        ]
                                                    }
                                                ]
                                            }
                                        }
                                    }
                                ]
                            }
                        ],
                        "totalPrice": {
                            "price": {
                                "text": "1,600",
                                "formatted": {
                                    "value": "1600"
                                },
                                "keyText": "Amount to receive:",
                                "confidenceScore": 0.89884,
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 521.0,
                                                "y": 751.0
                                            },
                                            {
                                                "x": 678.0,
                                                "y": 751.0
                                            },
                                            {
                                                "x": 678.0,
                                                "y": 786.0
                                            },
                                            {
                                                "x": 521.0,
                                                "y": 786.0
                                            }
                                        ]
                                    }
                                ]
                            }
                        },
                        "subTotal": [
                            {
                                "taxPrice": [
                                    {
                                        "text": "145",
                                        "formatted": {
                                            "value": "145"
                                        },
                                        "keyText": "VAT:",
                                        "confidenceScore": 0.93311,
                                        "boundingPolys": [
                                            {
                                                "vertices": [
                                                    {
                                                        "x": 626.0,
                                                        "y": 631.0
                                                    },
                                                    {
                                                        "x": 683.0,
                                                        "y": 631.0
                                                    },
                                                    {
                                                        "x": 683.0,
                                                        "y": 667.0
                                                    },
                                                    {
                                                        "x": 626.0,
                                                        "y": 667.0
                                                    }
                                                ]
                                            }
                                        ]
                                    }
                                ]
                            }
                        ]
                    }
                }
            }
        ]
    }
    

    Failure

    The following is a sample response upon a failed call.

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

    Was this article helpful?

    What's Next
    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.