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:
| Method | URI |
|---|---|
| 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:
| 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/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:
| 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 | - | Receipt image UID
|
name |
String | - | Receipt image name
|
inferResult |
String | - | Receipt 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 |
receipt |
Object | - | Receipt details |
receipt.meta |
Object | - | Meta information |
receipt.meta.estimatedLanguage |
String | - | OCR estimated language
|
receipt.result |
Object | - | Receipt OCR recognition result |
result
The following describes receipt.result.
| Field | Type | Required | Description |
|---|---|---|---|
storeInfo |
Object | - | Store information |
storeInfo.name |
Object | - | Store name details |
storeInfo.subName |
Object | - | Branch name details |
storeInfo.bizNum |
Object | - | Store business registration number details |
storeInfo.movieName |
Object | - | Movie ticket details |
storeInfo.addresses |
Array | - | Store address details |
storeInfo.tel |
Array | - | Store phone number details |
paymentInfo |
Object | - | Payment information |
paymentInfo.date |
Object | - | Payment date details |
paymentInfo.time |
Object | - | Payment time details |
paymentInfo.cardInfo |
Object | - | Payment card information |
paymentInfo.cardInfo.company |
Object | - | Credit card company details |
paymentInfo.cardInfo.number |
Object | - | Card number details |
paymentInfo.confirmNum |
Object | - | Authorization number details |
subResults |
Array | - | Product group information |
totalPrice |
Object | - | Total amount information |
totalPrice.price |
Object | - | Total amount details |
subTotal |
Array | - | Grand total details |
addresses
The following describes receipt.result.storeInfo.addresses.
| Field | Type | Required | Description |
|---|---|---|---|
text |
String | - | Recognized text |
formatted |
Object | - | Recognized text information |
formatted.value |
String | - | Recognized text value |
keyText |
String | - | Key value of recognized text |
confidenceScore |
Float | - | Confidence of recognized text
|
boundingPolys |
Array | - | boundingPoly details |
maskingPolys |
Array | - | maskingPoly details |
tel
The following describes receipt.result.storeInfo.tel.
| Field | Type | Required | Description |
|---|---|---|---|
text |
String | - | Recognized text |
formatted |
Object | - | Recognized text information |
formatted.value |
String | - | Recognized text value |
keyText |
String | - | Key value of recognized text |
confidenceScore |
Float | - | Confidence of recognized text
|
boundingPolys |
Array | - | boundingPoly details |
maskingPolys |
Array | - | maskingPoly details |
subResults
The following describes receipt.result.subResults.
| Field | Type | Required | Description |
|---|---|---|---|
items |
Array | - | Recognized product details |
items
The following describes receipt.result.subResults.items.
| Field | Type | Required | Description |
|---|---|---|---|
name |
Object | - | Item name details |
code |
Object | - | Item code details |
count |
Object | - | Item quantity details |
price |
Object | - | Item price information |
price.price |
Object | - | Item price details |
price.unitPrice |
Object | - | Item unit price details |
subTotal
The following describes receipt.result.subTotal.
| Field | Type | Required | Description |
|---|---|---|---|
taxPrice |
Array | - | VAT details |
discountPrice |
Array | - | Discount amount details |
taxPrice
The following describes receipt.result.subTotal.taxPrice.
| Field | Type | Required | Description |
|---|---|---|---|
text |
String | - | Recognized text |
formatted |
Object | - | Recognized text information |
formatted.value |
String | - | Recognized text value |
keyText |
String | - | Key value of recognized text |
confidenceScore |
Float | - | Confidence of recognized text
|
boundingPolys |
Array | - | boundingPoly details |
maskingPolys |
Array | - | maskingPoly details |
discountPrice
The following describes receipt.result.subTotal.discountPrice.
| Field | Type | Required | Description |
|---|---|---|---|
text |
String | - | Recognized text |
formatted |
Object | - | Recognized text information |
formatted.value |
String | - | Recognized text value |
keyText |
String | - | Key value of recognized text |
confidenceScore |
Float | - | Confidence of recognized text
|
boundingPolys |
Array | - | boundingPoly details |
maskingPolys |
Array | - | maskingPoly details |
Common object information
The following describes the common objects.
| Field | Type | Required | Description |
|---|---|---|---|
text |
String | - | Recognized text |
formatted |
Object | - | Recognized text information |
formatted.value |
String | - | Recognized text value |
keyText |
String | - | Key value of recognized text |
confidenceScore |
Float | - | Confidence of recognized text
|
boundingPolys |
Array | - | boundingPoly details |
maskingPolys |
Array | - | maskingPoly details |
Base object information
The following describes the base object information.
| Field | Type | Required | Description |
|---|---|---|---|
text |
String | - | Recognized text |
keyText |
String | - | Key value of recognized text |
confidenceScore |
Float | - | Confidence of recognized 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 text |
formatted |
Object | - | Recognized 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 text |
confidenceScore |
Float | - | Confidence of recognized text
|
boundingPolys |
Array | - | boundingPoly details |
maskingPolys |
Array | - | maskingPoly details |
Time object information
The following describes the time object.
| Field | Type | Required | Description |
|---|---|---|---|
text |
String | - | Recognized text |
formatted |
Object | - | Recognized text information |
formatted.hour |
String | - | Hour (HH) of recognized time |
formatted.minute |
String | - | Minute (MM) of recognized time |
formatted.second |
String | - | Second (ss) of recognized time |
keyText |
String | - | Key value of recognized text |
confidenceScore |
Float | - | Confidence of recognized text
|
boundingPolys |
Array | - | boundingPoly details |
maskingPolys |
Array | - | maskingPoly details |
Unit price object information
The following describes the unit price object.
| Field | Type | Required | Description |
|---|---|---|---|
text |
String | - | Recognized text |
formatted |
Object | - | Recognized text information |
formatted.value |
String | - | Recognized text value |
keyText |
String | - | Key value of recognized text |
confidenceScore |
Float | - | Confidence of recognized text
|
boundingPolys |
Array | - | boundingPoly 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 |
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 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"
}
}
]
}