Documentation

Sign up for free!

Get instant access to the API with your free API token. No billing details required!

Sign up now

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

Use live endpoints to request and return the receipt/invoice data in the same request.

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

Use queue endpoints to send your request to be processed in the background. You can retrieve the data later by passing the returned UUID to our scan status endpoint.

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();