Documentation
Sign up for free!
Get instant access to the API with your free API token. No billing details required!
Getting Started
Introduction
ReceiptUp was developed to provide accurate and affordable OCR and AI technology via an easy to use REST API to convert receipt and invoice images to structured data formats.
To get started simply sign up and use your API token in any of the available API endpoints documented below for instant access.
If you have any questions or concerns, feel free to contact us.
Authentication
As mentioned above, when you sign up for free you will find your API token on your dashboard. Simply add this to any of our API endpoints as a GET or POST parameter to gain access. Examples of how this is done can be found below.
API Endpoints
Live scans
File
Endpoint
POST https://api.receiptup.com/v1/scan/file HTTP/1.1
HTTP POST Parameters
| name | required | description |
|---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
file |
true |
The full path to your file. Max size: 25MB. Allowed types: jpeg,jpg,bmp,png,gif,svg,pdf |
include_line_items |
false | Choose if you would like to include or exclude line items. Setting this to true can
significantly increase processing time, especially on receipts/invoices with many line items. Default: true
|
store_result |
false | Choose if you would like to store the result when finished processing. This result is stored in
our database and you can retrieve it later using the uuid in our
scan status endpoint.Default: true
|
Response Objects
| name | description |
|---|---|
uuid |
The unique identifier for your scan. |
status.stage |
The stage of scan processing. One of: Uploaded, Processing, Completed, Failed |
status.description |
A description of the scan stage. |
result.receipt_date |
Date and time of the receipt. |
result.receipt_id |
Identifier for the receipt. |
result.merchant_tax_payer_id |
Tax payer ID of the merchant. |
result.merchant_tax_payer_type |
Type of tax payer for the merchant (one of: ABN, GST, PAN, VAT). |
result.recipient_tax_payer_id |
Tax payer ID of the recipient. |
result.recipient_tax_payer_type |
Type of tax payer for the recipient (one of: ABN, GST, PAN, VAT). |
result.customer_number |
Customer number associated with the transaction. |
result.account_number |
Account number associated with the transaction. |
result.currency_code |
Currency code for the transaction (e.g., 'GBP'). |
result.merchant |
Object containing details of the merchant. |
result.merchant.name |
Name of the merchant (e.g., 'TESCO'). |
result.merchant.address |
Address of the merchant. |
result.merchant.city |
City of the merchant. |
result.merchant.state |
State of the merchant. |
result.merchant.country_code |
Country code of the merchant. |
result.merchant.postal_code |
Postal code of the merchant. |
result.merchant.phone_number |
Phone number of the merchant. |
result.recipient |
Object containing details of the recipient. |
result.recipient.name |
Name of the recipient. |
result.recipient.address |
Address of the recipient. |
result.recipient.city |
City of the recipient. |
result.recipient.state |
State of the recipient. |
result.recipient.country_code |
Country code of the recipient. |
result.recipient.postal_code |
Postal code of the recipient. |
result.recipient.phone_number |
Phone number of the recipient. |
result.order_date |
Date of the order. |
result.due_date |
Due date for payment or delivery. |
result.delivery_date |
Date of delivery. |
result.po_number |
Purchase order number. |
result.total |
Total amount of the transaction. |
result.amount_due |
Amount due for the transaction. |
result.amount_paid |
Amount paid for the transaction. |
result.subtotal |
Subtotal amount before taxes and other charges. |
result.tax |
Tax amount for the transaction. |
result.service_charge |
Service charge for the transaction. |
result.gratuity |
Gratuity amount, if applicable. |
result.prior_balance |
Balance from previous transactions, if any. |
result.discount |
Discount applied, if any. |
result.shipping_charge |
Shipping charge for the transaction. |
result.line_items[Array].item |
Name of the item in the transaction. |
result.line_items[Array].qty |
Quantity of the item purchased. |
result.line_items[Array].price |
Price of the item. |
result.line_items[Array].unit_price |
Unit price of the item. |
result.line_items[Array].sku |
Stock Keeping Unit (SKU) identifier, if available. |
Example Request (cURL POST)
curl --location 'https://api.receiptup.com/v1/scan/file' \
--form 'api_token="YOUR_API_TOKEN"' \
--form 'file=@"/path/to/your/file.jpg"' \
--form 'include_line_items="true"' \
--form 'store_result="true"'
Example Response
{
"uuid": "0c0ff8b9-92e7-4f10-a900-b2107af10ab7",
"status": {
"stage": "Completed",
"description": "File processed successfully."
},
"result": {
"receipt_date": "2021-07-01 12:00:00",
"receipt_id": null,
"merchant_tax_payer_id": null,
"merchant_tax_payer_type": null,
"recipient_tax_payer_id": null,
"recipient_tax_payer_type": null,
"customer_number": null,
"account_number": null,
"currency_code": "GBP",
"merchant": {
"name": "TESCO",
"address": "ADDLESTONE",
"city": null,
"state": null,
"country_code": null,
"postal_code": null,
"phone_number": "0345 6778999"
},
"recipient": {
"name": null,
"address": null,
"city": null,
"state": null,
"country_code": null,
"postal_code": null,
"phone_number": null
},
"order_date": null,
"due_date": null,
"delivery_date": null,
"po_number": null,
"total": 54.73,
"amount_due": null,
"amount_paid": null,
"subtotal": null,
"tax": null,
"service_charge": null,
"gratuity": null,
"prior_balance": null,
"discount": null,
"shipping_charge": null,
"line_items": [
{
"item": "BS 4 WHT BAPS",
"qty": 1,
"price": 0.6,
"unit_price": 0.6,
"sku": null
},
{
"item": "GOV BAG CHARGE+*",
"qty": 1,
"price": 0.05,
"unit_price": 0.05,
"sku": null
},
{
"item": "GOV BAG CHARGE+*",
"qty": 1,
"price": 0.05,
"unit_price": 0.05,
"sku": null
},
{
"item": "BABYLEAF SALAD",
"qty": 1,
"price": 0.79,
"unit_price": 0.79,
"sku": null
},
{
"item": "TOMATOES",
"qty": 1,
"price": 0.9,
"unit_price": 0.9,
"sku": null
},
{
"item": "MOZZARELLA",
"qty": 1,
"price": 2.5,
"unit_price": 2.5,
"sku": null
},
{
"item": "SOREEN",
"qty": 1,
"price": 1.25,
"unit_price": 1.25,
"sku": null
},
{
"item": "ASPARAGUS",
"qty": 1,
"price": 1.5,
"unit_price": 1.5,
"sku": null
},
{
"item": "DIP",
"qty": 1,
"price": 1.5,
"unit_price": 1.5,
"sku": null
},
{
"item": "H/ROAST HAM",
"qty": 1,
"price": 4.17,
"unit_price": 4.17,
"sku": null
},
{
"item": "EGGS",
"qty": 1,
"price": 0.89,
"unit_price": 0.89,
"sku": null
},
{
"item": "PRAWN C.TAIL",
"qty": 1,
"price": 2,
"unit_price": 2,
"sku": null
},
{
"item": "RIPE AVOCADO",
"qty": 1,
"price": 1,
"unit_price": 1,
"sku": null
},
{
"item": "PROVENCE WINE *",
"qty": 1,
"price": 6,
"unit_price": 6,
"sku": null
},
{
"item": "CHOC. ORANGE *",
"qty": 1,
"price": 1,
"unit_price": 1,
"sku": null
},
{
"item": "CHOC DESSERT",
"qty": 1,
"price": 3,
"unit_price": 3,
"sku": null
},
{
"item": "CHOC DESSERT",
"qty": 1,
"price": 3,
"unit_price": 3,
"sku": null
},
{
"item": "READY MEAL",
"qty": 1,
"price": 3,
"unit_price": 3,
"sku": null
},
{
"item": "POTATO",
"qty": 1,
"price": 3,
"unit_price": 3,
"sku": null
},
{
"item": "STEAK",
"qty": 1,
"price": 6,
"unit_price": 6,
"sku": null
},
{
"item": "STEAK",
"qty": 1,
"price": 6,
"unit_price": 6,
"sku": null
},
{
"item": "MAILLE SAUCE",
"qty": 1,
"price": 1.53,
"unit_price": 1.53,
"sku": null
},
{
"item": "OTEX *",
"qty": 1,
"price": 5,
"unit_price": 5,
"sku": null
}
]
}
}
Base64
Endpoint
POST https://api.receiptup.com/v1/scan/base64 HTTP/1.1
HTTP POST Parameters
| name | required | description |
|---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
base64 |
true |
The base64 encoded version of your file. Max size: 25MB. Allowed types: jpeg,jpg,bmp,png,gif,svg,pdf |
include_line_items |
false | Choose if you would like to include or exclude line items. Setting this to true can
significantly increase processing time, especially on receipts/invoices with many line items. Default: true
|
store_result |
false | Choose if you would like to store the result when finished processing. This result is stored in
our database and you can retrieve it later using the uuid in our
scan status endpoint.Default: true
|
Response Objects
| name | description |
|---|---|
uuid |
The unique identifier for your scan. |
status.stage |
The stage of scan processing. One of: Uploaded, Processing, Completed, Failed |
status.description |
A description of the scan stage. |
result.receipt_date |
Date and time of the receipt. |
result.receipt_id |
Identifier for the receipt. |
result.merchant_tax_payer_id |
Tax payer ID of the merchant. |
result.merchant_tax_payer_type |
Type of tax payer for the merchant (one of: ABN, GST, PAN, VAT). |
result.recipient_tax_payer_id |
Tax payer ID of the recipient. |
result.recipient_tax_payer_type |
Type of tax payer for the recipient (one of: ABN, GST, PAN, VAT). |
result.customer_number |
Customer number associated with the transaction. |
result.account_number |
Account number associated with the transaction. |
result.currency_code |
Currency code for the transaction (e.g., 'GBP'). |
result.merchant |
Object containing details of the merchant. |
result.merchant.name |
Name of the merchant (e.g., 'TESCO'). |
result.merchant.address |
Address of the merchant. |
result.merchant.city |
City of the merchant. |
result.merchant.state |
State of the merchant. |
result.merchant.country_code |
Country code of the merchant. |
result.merchant.postal_code |
Postal code of the merchant. |
result.merchant.phone_number |
Phone number of the merchant. |
result.recipient |
Object containing details of the recipient. |
result.recipient.name |
Name of the recipient. |
result.recipient.address |
Address of the recipient. |
result.recipient.city |
City of the recipient. |
result.recipient.state |
State of the recipient. |
result.recipient.country_code |
Country code of the recipient. |
result.recipient.postal_code |
Postal code of the recipient. |
result.recipient.phone_number |
Phone number of the recipient. |
result.order_date |
Date of the order. |
result.due_date |
Due date for payment or delivery. |
result.delivery_date |
Date of delivery. |
result.po_number |
Purchase order number. |
result.total |
Total amount of the transaction. |
result.amount_due |
Amount due for the transaction. |
result.amount_paid |
Amount paid for the transaction. |
result.subtotal |
Subtotal amount before taxes and other charges. |
result.tax |
Tax amount for the transaction. |
result.service_charge |
Service charge for the transaction. |
result.gratuity |
Gratuity amount, if applicable. |
result.prior_balance |
Balance from previous transactions, if any. |
result.discount |
Discount applied, if any. |
result.shipping_charge |
Shipping charge for the transaction. |
result.line_items[Array].item |
Name of the item in the transaction. |
result.line_items[Array].qty |
Quantity of the item purchased. |
result.line_items[Array].price |
Price of the item. |
result.line_items[Array].unit_price |
Unit price of the item. |
result.line_items[Array].sku |
Stock Keeping Unit (SKU) identifier, if available. |
Example Request (cURL POST)
curl --location 'https://api.receiptup.com/v1/scan/base64' \
--form 'api_token="YOUR_API_TOKEN"' \
--form 'base64="base64 encoded file"' \
--form 'include_line_items="true"' \
--form 'store_result="true"'
Example Response
{
"uuid": "0c0ff8b9-92e7-4f10-a900-b2107af10ab7",
"status": {
"stage": "Completed",
"description": "File processed successfully."
},
"result": {
"receipt_date": "2021-07-01 12:00:00",
"receipt_id": null,
"merchant_tax_payer_id": null,
"merchant_tax_payer_type": null,
"recipient_tax_payer_id": null,
"recipient_tax_payer_type": null,
"customer_number": null,
"account_number": null,
"currency_code": "GBP",
"merchant": {
"name": "TESCO",
"address": "ADDLESTONE",
"city": null,
"state": null,
"country_code": null,
"postal_code": null,
"phone_number": "0345 6778999"
},
"recipient": {
"name": null,
"address": null,
"city": null,
"state": null,
"country_code": null,
"postal_code": null,
"phone_number": null
},
"order_date": null,
"due_date": null,
"delivery_date": null,
"po_number": null,
"total": 54.73,
"amount_due": null,
"amount_paid": null,
"subtotal": null,
"tax": null,
"service_charge": null,
"gratuity": null,
"prior_balance": null,
"discount": null,
"shipping_charge": null,
"line_items": [
{
"item": "BS 4 WHT BAPS",
"qty": 1,
"price": 0.6,
"unit_price": 0.6,
"sku": null
},
{
"item": "GOV BAG CHARGE+*",
"qty": 1,
"price": 0.05,
"unit_price": 0.05,
"sku": null
},
{
"item": "GOV BAG CHARGE+*",
"qty": 1,
"price": 0.05,
"unit_price": 0.05,
"sku": null
},
{
"item": "BABYLEAF SALAD",
"qty": 1,
"price": 0.79,
"unit_price": 0.79,
"sku": null
},
{
"item": "TOMATOES",
"qty": 1,
"price": 0.9,
"unit_price": 0.9,
"sku": null
},
{
"item": "MOZZARELLA",
"qty": 1,
"price": 2.5,
"unit_price": 2.5,
"sku": null
},
{
"item": "SOREEN",
"qty": 1,
"price": 1.25,
"unit_price": 1.25,
"sku": null
},
{
"item": "ASPARAGUS",
"qty": 1,
"price": 1.5,
"unit_price": 1.5,
"sku": null
},
{
"item": "DIP",
"qty": 1,
"price": 1.5,
"unit_price": 1.5,
"sku": null
},
{
"item": "H/ROAST HAM",
"qty": 1,
"price": 4.17,
"unit_price": 4.17,
"sku": null
},
{
"item": "EGGS",
"qty": 1,
"price": 0.89,
"unit_price": 0.89,
"sku": null
},
{
"item": "PRAWN C.TAIL",
"qty": 1,
"price": 2,
"unit_price": 2,
"sku": null
},
{
"item": "RIPE AVOCADO",
"qty": 1,
"price": 1,
"unit_price": 1,
"sku": null
},
{
"item": "PROVENCE WINE *",
"qty": 1,
"price": 6,
"unit_price": 6,
"sku": null
},
{
"item": "CHOC. ORANGE *",
"qty": 1,
"price": 1,
"unit_price": 1,
"sku": null
},
{
"item": "CHOC DESSERT",
"qty": 1,
"price": 3,
"unit_price": 3,
"sku": null
},
{
"item": "CHOC DESSERT",
"qty": 1,
"price": 3,
"unit_price": 3,
"sku": null
},
{
"item": "READY MEAL",
"qty": 1,
"price": 3,
"unit_price": 3,
"sku": null
},
{
"item": "POTATO",
"qty": 1,
"price": 3,
"unit_price": 3,
"sku": null
},
{
"item": "STEAK",
"qty": 1,
"price": 6,
"unit_price": 6,
"sku": null
},
{
"item": "STEAK",
"qty": 1,
"price": 6,
"unit_price": 6,
"sku": null
},
{
"item": "MAILLE SAUCE",
"qty": 1,
"price": 1.53,
"unit_price": 1.53,
"sku": null
},
{
"item": "OTEX *",
"qty": 1,
"price": 5,
"unit_price": 5,
"sku": null
}
]
}
}
Queue scans
File
Endpoint
POST https://api.receiptup.com/v1/scan/file/queue HTTP/1.1
HTTP POST Parameters
| name | required | description |
|---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
file |
true |
The full path to your file. Max size: 25MB. Allowed types: jpeg,jpg,bmp,png,gif,svg,pdf |
include_line_items |
false | Choose if you would like to include or exclude line items. Setting this to true can
significantly increase processing time, especially on receipts/invoices with many line items. Default: true
|
Response Objects
| name | description |
|---|---|
uuid |
The unique identifier for your scan. |
Example Request (cURL POST)
curl --location 'https://api.receiptup.com/v1/scan/file/queue' \
--form 'api_token="YOUR_API_TOKEN"' \
--form 'file=@"/path/to/your/file.jpg"' \
--form 'include_line_items="true"'
Example Response
{
"uuid": "d3754a04-6fa1-447d-831f-d654775bad9e"
}
Base64
Endpoint
POST https://api.receiptup.com/v1/scan/base64/queue HTTP/1.1
HTTP POST Parameters
| name | required | description |
|---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
base64 |
true |
The base64 encoded version of your file. Max size: 25MB. Allowed types: jpeg,jpg,bmp,png,gif,svg,pdf |
include_line_items |
false | Choose if you would like to include or exclude line items. Setting this to true can
significantly increase processing time, especially on receipts/invoices with many line items. Default: true
|
Response Objects
| name | description |
|---|---|
uuid |
The unique identifier for your scan. |
Example Request (cURL POST)
curl --location 'https://api.receiptup.com/v1/scan/base64/queue' \
--form 'api_token="YOUR_API_TOKEN"' \
--form 'base64="base64 encoded file"' \
--form 'include_line_items="true"' \
--form 'store_result="true"'
Example Response
{
"uuid": "d3754a04-6fa1-447d-831f-d654775bad9e"
}
Scan status & search
Scan status
Use the scan status endpoint to retrieve the results or status for queued scans or results from previous live scans.
Live scan results can only be retrieved from this endpoint when store_result is set to true
when making a request to a live scan endpoint.
Requests made to the scan status endpoint does not contribute to your number of monthly available scans. Requests can be made as either GET or POST methods.
Endpoint
GET https://api.receiptup.com/v1/scan/status HTTP/1.1
HTTP GET or POST Parameters
| name | required | description |
|---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
uuid |
true | The UUID which was provided to you via our live or queued scan endpoints. |
Response Objects
| name | description |
|---|---|
uuid |
The unique identifier for your scan. |
status.stage |
The stage of scan processing. One of: Uploaded, Processing, Completed, Failed |
status.description |
A description of the scan stage. |
result.receipt_date |
Date and time of the receipt. |
result.receipt_id |
Identifier for the receipt. |
result.merchant_tax_payer_id |
Tax payer ID of the merchant. |
result.merchant_tax_payer_type |
Type of tax payer for the merchant (one of: ABN, GST, PAN, VAT). |
result.recipient_tax_payer_id |
Tax payer ID of the recipient. |
result.recipient_tax_payer_type |
Type of tax payer for the recipient (one of: ABN, GST, PAN, VAT). |
result.customer_number |
Customer number associated with the transaction. |
result.account_number |
Account number associated with the transaction. |
result.currency_code |
Currency code for the transaction (e.g., 'GBP'). |
result.merchant |
Object containing details of the merchant. |
result.merchant.name |
Name of the merchant (e.g., 'TESCO'). |
result.merchant.address |
Address of the merchant. |
result.merchant.city |
City of the merchant. |
result.merchant.state |
State of the merchant. |
result.merchant.country_code |
Country code of the merchant. |
result.merchant.postal_code |
Postal code of the merchant. |
result.merchant.phone_number |
Phone number of the merchant. |
result.recipient |
Object containing details of the recipient. |
result.recipient.name |
Name of the recipient. |
result.recipient.address |
Address of the recipient. |
result.recipient.city |
City of the recipient. |
result.recipient.state |
State of the recipient. |
result.recipient.country_code |
Country code of the recipient. |
result.recipient.postal_code |
Postal code of the recipient. |
result.recipient.phone_number |
Phone number of the recipient. |
result.order_date |
Date of the order. |
result.due_date |
Due date for payment or delivery. |
result.delivery_date |
Date of delivery. |
result.po_number |
Purchase order number. |
result.total |
Total amount of the transaction. |
result.amount_due |
Amount due for the transaction. |
result.amount_paid |
Amount paid for the transaction. |
result.subtotal |
Subtotal amount before taxes and other charges. |
result.tax |
Tax amount for the transaction. |
result.service_charge |
Service charge for the transaction. |
result.gratuity |
Gratuity amount, if applicable. |
result.prior_balance |
Balance from previous transactions, if any. |
result.discount |
Discount applied, if any. |
result.shipping_charge |
Shipping charge for the transaction. |
result.line_items[Array].item |
Name of the item in the transaction. |
result.line_items[Array].qty |
Quantity of the item purchased. |
result.line_items[Array].price |
Price of the item. |
result.line_items[Array].unit_price |
Unit price of the item. |
result.line_items[Array].sku |
Stock Keeping Unit (SKU) identifier, if available. |
Example Request (cURL GET)
curl --location 'https://api.receiptup.com/v1/scan/status?api_token=YOUR_API_TOKEN&uuid=43d17453-6ba3-4a8c-ad57-b2dfdf8d34e2'
Example Response
{
"uuid": "0c0ff8b9-92e7-4f10-a900-b2107af10ab7",
"status": {
"stage": "Completed",
"description": "File processed successfully."
},
"result": {
"receipt_date": "2021-07-01 12:00:00",
"receipt_id": null,
"merchant_tax_payer_id": null,
"merchant_tax_payer_type": null,
"recipient_tax_payer_id": null,
"recipient_tax_payer_type": null,
"customer_number": null,
"account_number": null,
"currency_code": "GBP",
"merchant": {
"name": "TESCO",
"address": "ADDLESTONE",
"city": null,
"state": null,
"country_code": null,
"postal_code": null,
"phone_number": "0345 6778999"
},
"recipient": {
"name": null,
"address": null,
"city": null,
"state": null,
"country_code": null,
"postal_code": null,
"phone_number": null
},
"order_date": null,
"due_date": null,
"delivery_date": null,
"po_number": null,
"total": 54.73,
"amount_due": null,
"amount_paid": null,
"subtotal": null,
"tax": null,
"service_charge": null,
"gratuity": null,
"prior_balance": null,
"discount": null,
"shipping_charge": null,
"line_items": [
{
"item": "BS 4 WHT BAPS",
"qty": 1,
"price": 0.6,
"unit_price": 0.6,
"sku": null
},
{
"item": "GOV BAG CHARGE+*",
"qty": 1,
"price": 0.05,
"unit_price": 0.05,
"sku": null
},
{
"item": "GOV BAG CHARGE+*",
"qty": 1,
"price": 0.05,
"unit_price": 0.05,
"sku": null
},
{
"item": "BABYLEAF SALAD",
"qty": 1,
"price": 0.79,
"unit_price": 0.79,
"sku": null
},
{
"item": "TOMATOES",
"qty": 1,
"price": 0.9,
"unit_price": 0.9,
"sku": null
},
{
"item": "MOZZARELLA",
"qty": 1,
"price": 2.5,
"unit_price": 2.5,
"sku": null
},
{
"item": "SOREEN",
"qty": 1,
"price": 1.25,
"unit_price": 1.25,
"sku": null
},
{
"item": "ASPARAGUS",
"qty": 1,
"price": 1.5,
"unit_price": 1.5,
"sku": null
},
{
"item": "DIP",
"qty": 1,
"price": 1.5,
"unit_price": 1.5,
"sku": null
},
{
"item": "H/ROAST HAM",
"qty": 1,
"price": 4.17,
"unit_price": 4.17,
"sku": null
},
{
"item": "EGGS",
"qty": 1,
"price": 0.89,
"unit_price": 0.89,
"sku": null
},
{
"item": "PRAWN C.TAIL",
"qty": 1,
"price": 2,
"unit_price": 2,
"sku": null
},
{
"item": "RIPE AVOCADO",
"qty": 1,
"price": 1,
"unit_price": 1,
"sku": null
},
{
"item": "PROVENCE WINE *",
"qty": 1,
"price": 6,
"unit_price": 6,
"sku": null
},
{
"item": "CHOC. ORANGE *",
"qty": 1,
"price": 1,
"unit_price": 1,
"sku": null
},
{
"item": "CHOC DESSERT",
"qty": 1,
"price": 3,
"unit_price": 3,
"sku": null
},
{
"item": "CHOC DESSERT",
"qty": 1,
"price": 3,
"unit_price": 3,
"sku": null
},
{
"item": "READY MEAL",
"qty": 1,
"price": 3,
"unit_price": 3,
"sku": null
},
{
"item": "POTATO",
"qty": 1,
"price": 3,
"unit_price": 3,
"sku": null
},
{
"item": "STEAK",
"qty": 1,
"price": 6,
"unit_price": 6,
"sku": null
},
{
"item": "STEAK",
"qty": 1,
"price": 6,
"unit_price": 6,
"sku": null
},
{
"item": "MAILLE SAUCE",
"qty": 1,
"price": 1.53,
"unit_price": 1.53,
"sku": null
},
{
"item": "OTEX *",
"qty": 1,
"price": 5,
"unit_price": 5,
"sku": null
}
]
}
}
Scan search
Requests made to the scan search endpoint does not contribute to your number of monthly available scans. Requests can be made as either GET or POST methods.
Endpoint
GET https://api.receiptup.com/v1/scan/search HTTP/1.1
HTTP GET or POST Parameters
| name | required | description |
|---|---|---|
api_token |
true | Your API token which can be found on your account dashboard. |
page |
false | Paginate your scan results. Result limit is 20. Default page is 1. |
status |
false | Refine results by the scan status. Valid values include
completed, failed, processing, uploaded.
All status values are included by default.
|
show_result_attribute |
false | Choose whether to include the result attribute in the data output. Default is true. |
Response Objects
| name | description |
|---|---|
meta.current_page |
The current page of the pagination results, as defined by the page parameter. |
meta.results_per_page |
The number of results per page (the limit). |
meta.results_current_page |
The number of results on the current page. |
meta.results_total |
The total number of results. |
meta.results_last_page |
The last page of results (i.e. the max page). |
data[Array].uuid |
The unique identifier for the scan. |
data[Array].status.stage |
The stage of scan processing. Options include: Uploaded,Processing,
Completed,Failed
|
data[Array].status.description |
A description of the scan stage. |
data[Array].queued |
Whether the scan was queued, true/false. If false the scan was a live scan. |
data[Array].is_base_64 |
Whether the scan was made as a base64 scan, true/falase. |
data[Array].store_result |
Whether the result was stored. |
data[Array].include_list_items |
Whether the scan was requested to include line items in the result. |
data[Array].result |
The result of a scan. See live scan response object for example. Null if empty. |
Example Request (cURL GET)
curl --location 'https://api.receiptup.com/v1/scan/search?api_token=YOUR_API_TOKEN'
Example Response
{
"meta": {
"current_page": 1,
"results_per_page": 10,
"results_current_page": 10,
"results_total": 36,
"results_last_page": 4
},
"data": [
{
"uuid": "a2596e01-b9a4-4c48-92a2-34d3ff22f6cf",
"status": {
"stage": "Uploaded",
"description": "File uploaded, pending processing."
},
"queued": false,
"is_base_64": true,
"store_result": false,
"include_list_items": true,
"result": null
},
{
"uuid": "439c0f08-8351-4017-bb8c-1b0ae033dae4",
"status": {
"stage": "Completed",
"description": "File processed successfully."
},
"queued": true,
"is_base_64": true,
"store_result": false,
"include_list_items": true,
"result": null
},
{
"uuid": "3868f779-d645-442e-aa66-c763cac94473",
"status": {
"stage": "Uploaded",
"description": "File uploaded, pending processing."
},
"queued": false,
"is_base_64": false,
"store_result": false,
"include_list_items": true,
"result": null
},
{
"uuid": "6bdb2ebc-fc99-43fa-bbf7-90c8b01eaaf2",
"status": {
"stage": "Uploaded",
"description": "File uploaded, pending processing."
},
"queued": false,
"is_base_64": false,
"store_result": false,
"include_list_items": true,
"result": null
},
{
"uuid": "600e7f50-c348-4ead-a63a-d59abd5c5c71",
"status": {
"stage": "Uploaded",
"description": "File uploaded, pending processing."
},
"queued": false,
"is_base_64": false,
"store_result": false,
"include_list_items": true,
"result": null
},
{
"uuid": "971cb9f3-7b22-450c-8c15-36deb37168d7",
"status": {
"stage": "Uploaded",
"description": "File uploaded, pending processing."
},
"queued": false,
"is_base_64": false,
"store_result": false,
"include_list_items": true,
"result": null
},
{
"uuid": "d3754a04-6fa1-447d-831f-d654775bad9e",
"status": {
"stage": "Uploaded",
"description": "File uploaded, pending processing."
},
"queued": false,
"is_base_64": true,
"store_result": false,
"include_list_items": true,
"result": null
},
{
"uuid": "5584c81f-806f-4afb-9179-b12aea96d6f7",
"status": {
"stage": "Completed",
"description": "File processed successfully."
},
"queued": true,
"is_base_64": true,
"store_result": false,
"include_list_items": true,
"result": null
},
{
"uuid": "3cd03e37-919e-4d25-bc3e-79490df174b0",
"status": {
"stage": "Completed",
"description": "File processed successfully."
},
"queued": true,
"is_base_64": false,
"store_result": true,
"include_list_items": true,
"result": null
},
{
"uuid": "0dcb62b5-0417-4eb5-a0b0-c50b42108a80",
"status": {
"stage": "Uploaded",
"description": "File uploaded, pending processing."
},
"queued": false,
"is_base_64": false,
"store_result": false,
"include_list_items": true,
"result": null
}
]
}
Errors
Errors
If your request was unsuccessful, you will receive a JSON formatted error. Below you will find the potential errors you may encounter when using the API.
Errors
| error code | HTTP status | description |
|---|---|---|
malformed_parameters |
400 |
Validation of parameters failed. The failed parameters are usually shown in the error message. |
invalid_api_token |
401 |
Invalid API token. |
usage_limit_reached |
402 |
Usage limit of your plan has been reached. Usage limit and remaining requests can be found on the X-UsageLimit-Limit header. |
endpoint_access_restricted |
403 |
Access to the endpoint is not available on your current subscription plan. |
resource_not_found |
404 |
Resource could not be found. |
invalid_api_endpoint |
404 |
API route does not exist. |
method_not_allowed |
405 |
HTTP Method is not allowed (GET, POST). |
rate_limit_reached |
429 |
Too many requests in the past 60 seconds. Rate limit and remaining requests can be found on the X-RateLimit-Limit header. |
server_error |
500 |
A server error occured. |
maintenance_mode |
503 |
The service is currently under maintenance. |
Example Error Response
{
"error": {
"code": "malformed_parameters",
"message": "The file parameter(s) are incorrectly formatted."
}
}
Examples
Code Examples
See our prepared examples below to quickly get started implementing our API into your next project.
PHP
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.receiptup.com/v1/scan/file',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"api_token": "YOUR_API_TOKEN",
"file": "/path/to/your/file.png",
"include_line_items": "true",
"store_result": "true"
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Python
import requests
url = "https://api.receiptup.com/v1/scan/file"
payload = {'api_token': 'YOUR_API_TOKEN',
'include_line_items': 'true',
'store_result': 'true'}
files=[
('file',('file.png',open('/path/to/your/file.png','rb'),'image/png'))
]
headers = {}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)
Go
package main
import (
"fmt"
"bytes"
"mime/multipart"
"os"
"path/filepath"
"io"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.receiptup.com/v1/scan/file"
method := "POST"
payload := &bytes.Buffer{}
writer := multipart.NewWriter(payload)
_ = writer.WriteField("api_token", "YOUR_API_TOKEN")
file, errFile2 := os.Open("/path/to/your/file.png")
defer file.Close()
part2,
errFile2 := writer.CreateFormFile("file",filepath.Base("/path/to/your/file.png"))
_, errFile2 = io.Copy(part2, file)
if errFile2 != nil {
fmt.Println(errFile2)
return
}
_ = writer.WriteField("include_line_items", "true")
_ = writer.WriteField("store_result", "true")
err := writer.Close()
if err != nil {
fmt.Println(err)
return
}
client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
req.Header.Set("Content-Type", writer.FormDataContentType())
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
JavaScript
// WARNING: For POST requests, body is set to null by browsers.
var data = new FormData();
data.append("api_token", "YOUR_API_TOKEN");
data.append("file", fileInput.files[0], "file.png");
data.append("include_line_items", "true");
data.append("store_result", "true");
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.receiptup.com/v1/scan/file");
xhr.send(data);
C#
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.receiptup.com/v1/scan/file");
var content = new MultipartFormDataContent();
content.Add(new StringContent("YOUR_API_TOKEN"), "api_token");
content.Add(new StreamContent(File.OpenRead("/path/to/your/file.png")), "file", "/path/to/your/file.png");
content.Add(new StringContent("true"), "include_line_items");
content.Add(new StringContent("true"), "store_result");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
Java
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
.addFormDataPart("api_token","YOUR_API_TOKEN")
.addFormDataPart("file","file.png",
RequestBody.create(MediaType.parse("application/octet-stream"),
new File("/path/to/your/file.png")))
.addFormDataPart("include_line_items","true")
.addFormDataPart("store_result","true")
.build();
Request request = new Request.Builder()
.url("https://api.receiptup.com/v1/scan/file")
.method("POST", body)
.build();
Response response = client.newCall(request).execute();