Capture an invoice or receipt in real time

A typical REST API POST of a PDF or image that is less than 1MB or 3 pages takes about 4-7 seconds to return a structured JSON response. Snippets of API calls in various languages, such as python, PHP, JAVA, C#, etc., are available upon request.

The following section explains how to pass your credentials to authenticate API requests and receive your JSON response.

You can submit local files or files at a url. This first example will submit a file by its url, but we have examples to submit local files with code at the end this page.

cURL

curl --location --request POST 'https://api.photoncommerce.com/api/v4?url=https://photon-api-demo.s3.us-west-1.amazonaws.com/demo_docs/02-02-2021_-_TuneGO_2.0.pdf' \
--header 'PASSWORD: Passit123@' \
--header 'SECRET-KEY: KNYh8XJX3xXEFftfoAd5' \
--header 'AUTHORIZATION: apikey pran.81gmail.com:e-hmk5s3qeSaWhc368pd' \
--header 'CLIENT-ID: iyeHs0oJRAooRw'

Python

import requests

url = "https://api.photoncommerce.com/api/v4?url=https://photon-api-demo.s3.us-west-1.amazonaws.com/demo_docs/02-02-2021_-_TuneGO_2.0.pdf"

headers = {
  'PASSWORD': 'Passit123@',
  'SECRET-KEY': 'KNYh8XJX3xXEFftfoAd5',
  'AUTHORIZATION': 'apikey pran.81gmail.com:e-hmk5s3qeSaWhc368pd',
  'CLIENT-ID': 'iyeHs0oJRAooRw'
}

response = requests.request("POST", url, headers=headers)

Specify Document Type: Our API intelligently and accurately classifies the documents into the following document types:

1. Invoice (Photon doctype value: invoice)

2. Receipt (Photon doctype value: receipt)

3. Check (Photon doctype value: check)

4. Remittance (Photon doctype value: remittance)

5. Statement (Photon doctype value: statement)

6. Purchase Order (Photon doctype value: purchaseorder)

You can pre-specify the document type by using the doctype parameter.

***Note: The value of this parameter should be in lowercase and must not contain any spaces. If any arbitrary document type is specified, Photon will re-classify the document using its own logic. Here is an example python script.

Python

import requests

# Pre-specifying document type as invoice
url = "https://api.photoncommerce.com/api/v4?doctype=invoice"

# path to your local file/document
path_to_file = ''

headers = {
  'PASSWORD': 'Passit123@',
  'SECRET-KEY': 'KNYh8XJX3xXEFftfoAd5',
  'AUTHORIZATION': 'apikey pran.81gmail.com:e-hmk5s3qeSaWhc368pd',
  'CLIENT-ID': 'iyeHs0oJRAooRw'
}

files = {'pdf': open(path_to_file, 'rb')}

response = requests.request("POST", url, headers=headers, files=files)

Validations - If you wish to retrieve validation scores in the form of the following keys, set 'Validations' to 'true' in the Authentication Header:

• FraudScore: Value from 0-100 which indicates the similarity of the document with any previously uploaded documents. If the same document has been uploaded before, the Fraud_Score will be '100'

• Subtotal_Line_Items: Binary value ('0' or '1') based on whether the subtotal is equal to the sum of all the amounts in Line_Items.

• Total_Subtotal: Binary value ('0' or '1') based on whether Total = Subtotal + Shipping + Tax -Discount

Python

# To retrieve validation scores, set 'Validations' to 'true' in the Authentication Header
file_url = 'https://photon-sample.s3.amazonaws.com/02-02-2021_-_TuneGO_2.0.pdf'
headers = {
    # Remember to include your login credentials as well...
    'Validations': 'true'
}

response = requests.post(f'https://api.photoncommerce.com/api/v4?url={file_url}', headers=headers)

Header - Only: If you wish to prioritise speed over line item extraction accuracy, you can get faster results by setting the parameter 'Header-Only' to 'true' in the Authentication Header

Python

# To retrieve validation scores, set 'Validations' to 'true' in the Authentication Header
files = {'pdf': open('<path-to-file>', 'rb')}
headers = {
    # Remember to include your login credentials as well...
    'Header-Only': 'true'
}

response = requests.post(f'https://api.photoncommerce.com/api/v4', headers=headers, files=files)

If you contacted Photon Commerce to receive an API Key, skip the following POST request section and read on. If you registered for credentials using your email address and password, the authentication parameters in your API requests will slightly differ. The following block explains how to pass your credentials to authenticate API requests.

Invoice and receipt capture

POST https://api.photoncommerce.com/api/v4

Capture invoices and receipts using your Client ID, Client Secret, API Key and Username

Headers

Name	Type	Description
PASSWORD	string	The password you used for your email registration
SECRET-KEY	string	Your secret key as a string
AUTHORIZATION	string	Pass your username and unique API key in the form 'apikey <your_username>:<your_api_key>'
CLIENT-ID	string	Unique Client_ID for every user. Incorrect value will lead to an authorization error.

Request Body

Name	Type	Description
doctype	string	One can specify the type of document. E.g invoice, receipt, check, etc.
coordinates	integer	To retrieve bounding box coordinates for the values, set this parameter to 1
confidence	integer	To retrieve confidence scores for the values, set this parameter to 1
pdf	string	The path to the pdf, document, or image needing to be captured. Any image or Word document are also acceptable.

200

{'data': 
    {'Total': 1568.0, 
    'Subtotal': 0.0, 
    'Shipping': 0.0, 
    'Tax': 0.0, 
    'Tip': 0.0, 
    'Cashback': 0.0, 
    'Discount': 0.0, 
    'Date': '2021-01-29', 
    'Document_Type': 'Invoice', 
    'Invoice_Number': 'PIN113786', 
    'PO_Number': '144', 
    'Account_Number': '164246', 
    'Category': 'Job Supplies', 
    'Bill_To_Name': 'Rejuvenate Bio Inc', 
    'Bill_To_Address': '10210 Campus Point Drive\nSan Diego, CA 92121', 
    'Bill_To_Email': '', 
    'Bill_To_Vat_Number': '', 
    'Bill_To_Recipient': '', 
    'Bill_To_Address_Line': '10210 Campus Point Drive', 
    'Bill_To_City': 'San Diego', 
    'Bill_To_State': 'CA', 
    'Bill_To_Zipcode': '92121', 
    'Card_Number': '', 
    'Created': '2021-06-26 09:24:00', 
    'Currency_Code': 'USD', 
    'Due_Date': '2021-02-28', 
    'Payment_Terms': '30 days', 
    'Payment_Display_Name': '', 
    'Payment_Type': '', 
    'Phone_Number': '011-200-365', 
    'Reference_Number': '', 
    'Service_Start_Date': '', 
    'Service_End_Date': '', 
    'Tax_Lines': [], 
    'Tracking_Number': '', 
    'Vat_Number': '890783897RT0001', 
    'Vendor_Name': 'The Jackson Laboratory.', 
    'Vendor_Address': '90260 Collection Center Dr, Chicago IL 60693', 
    'Vendor_Address_Line': '90260 Collection Center Dr', 
    'Vendor_City': 'Chicago', 
    'Vendor_State': 'IL', 
    'Vendor_Zipcode': '60693', 
    'Vendor_Country': 'US', 
    'Vendor_Email': '', 
    'Vendor_Account_Number': '9429239533', 
    'Vendor_Bank_Name': 'Bank of America', 
    'Vendor_Bank_Number': '026-009-593', 
    'Vendor_Bank_Swift': 'BOFAUS3N', 
    'Vendor_IBAN': '', 
    'Vendor_ABN_Number': '', 
    'Vendor_Fax': '011-200-365', 
    'Vendor_Phone': '011-200-365', 
    'Vendor_Website': 'https://www.jax.org/jax-mice-and', 
    'Vendor_Raw_Name': 'The Jackson Laboratory.', 
    'Vendor_Recipient': '', 
    'Vendor_Type': '', 
    'Remit_To_Name': '', 
    'Remit_To_Address': '', 
    'Is_Duplicate': 0, 
    'Ship_To_Name': '', 
    'Ship_To_Address': '', 
    'Order_Date': '', 
    'Ship_Date': '', 
    'Delivery_Date': '', 
    'Carrier': '', 
    'Notes': '', 
    'Pages': 1, 
    'Line_Items': [{'Line': 1, 'SKU': '', 'Date': '', 'Order': 1, 'Reference': '', 'Description': 'Holding Box SBSH', 'QTY': 1.0, 'Unit': '', 'Tax': 0.0, 'Tax_Rate': 0.0, 'Type': 'product', 'Price': 1120.0, 'Discount': 0.0, 'Amount': 1120.0}, {'Line': 2, 'SKU': '', 'Date': '', 'Order': 2, 'Reference': '', 'Description': 'Insourcing\n Shipping Charges', 'QTY': 1.0, 'Unit': '', 'Tax': 0.0, 'Tax_Rate': 0.0, 'Type': 'product', 'Price': 448.0, 'Discount': 0.0, 'Amount': 448.0}], 
    'All_Email_Addresses': '', 
    'Raw_Text': "PROJECT INVOICE\nThe Jackson\nLaboratory\nREMIT TO: The Jackson Laboratory - Please Reference our Invoice Number(s):\nLeading the search\t\t\tLockbox Payments: Bank of America/Jackson Laboratory\nfor tomorrow's cures\t\t\t90260 Collection Center Dr, Chicago IL 60693\n\tElectronic Payments: Bank of America - Account #9429239533\nTERMS: Net 30 days\t\t\t\t\tWIRES-ABA#026-009-593 ACH -ABA# 011-200-365\n\tAccounts Receivable: (ph)207-288-1420 | GST#890783897RT0001\nPayable in USD (USD)\t\t\t\tE.I.N.: 01-0211513 | DUNS#:04-214-0483 | Swift#: BOFAUS3N\n\tPhysical Address - 600-610 Main St., Bar Harbor, ME 04609\nRejuvenate Bio Inc\nAccounts Payable\t\t\t\t\t\tINVOICE DATE\t29 Jan 2021\n10210 Campus Point Drive\nSan Diego, CA 92121\t\t\t\t\t\tINVOICE NO.\tPIN113786\n\tPROJECT NO.\t123441\n\tCustomer ID No.\t164246\n\nPURCHASE ORDER NO. 144\nCUSTOMER REF. NO.\nRE: Noah Davidsohn / Dr. Noah Davidsohn\nSUMMARY OF PROJECT CHARGES\nPO Line\t\t\t\t\t\t\t\t\t\tTotal\nReference Description\t\t\t\tQty\tUnit Price\tAdjust\tExt Total\nPHASE 1: In Vivo Other Studies\nHolding Box SBSH\t\t\t1.00\t1,120.00\t\t\t1,120.00\nInsourcing\t\t\t\t1.00\t448.00\t\t\t448.00\nShipping Charges\t\t\t\t\t\t\t\t\t\t\t0.00\nTax\t\t\t\t\t\t\t\t\t\t\t\t0.00\nINVOICE TOTAL\t\t\t\t\t$1,568.00\nBALANCE DUE\t\t\t\t\t$1,568.00\nSHIPPING CHARGES:\nThis carrier consolidates shipments for multiple recipients from The Jackson Laboratory. Individual freight bills shipped on a consolidated\nbasis are not available to our customers from the carrier, the carrier does not bill in this way. Freight charges are calculated according to the\ntotal number of boxes shipped.\nItems listed on this invoice were shipped using the above referenced carrier. We certify that the freight bills associated with orders to our\ncustomers are calculated based on the consolidated shipping charges and represent the lowest amounts charged for freight of similar shipments\nto recipients in geographical areas close to your shipping destination. Proof of delivery can be provided if necessary.\n\nCONDITIONS OF USE AND GENERAL TERMS OF SALE:\nThis sale is transacted subject to the JAX Terms and Conditions which can be found at: https://www.jax.org/about-us/legal\ninformation/terms-and-conditions-of-product-use. Please also note the specific policy for live mice at: https://www.jax.org/jax-mice-and\nservices/customer-support#miceCredit.\n\n\tPage 1 of 1", 
    'photon_key': 'data/abcdefggmail.com/02-23-57_PIN113786.json'
    }, 
'message': 'success', 
'status': 'success'

cURL

curl  -X POST -H "CLIENT-ID:<client-id>" -H "AUTHORIZATION:apikey <username>:<api-key>" -H 'PASSWORD:<password>' -H "SECRET-KEY:<secret-key>" -F "pdf=@<path-to-file>" "https://api.photoncommerce.com/api/v4"

Python

import requests
headers = {
    'CLIENT-ID': '<client-id>',
    'AUTHORIZATION': 'apikey <username>:<api-key>',
    'PASSWORD':'<Your-valid-password>',
    'SECRET-KEY':'<your-client-secret>'
}

### FEATURE UPDATE - Confidence Scores and Coordinates
# To retrieve confidence score and coordinates, use the following request/URL
# response = requests.post('https://api.photoncommerce.com/api/v4?confidence=1&coordinates=1', headers=headers, files=files)

files = {'pdf': open('<path-to-file>', 'rb')}
response = requests.post('https://api.photoncommerce.com/api/v4', headers=headers, files=files)

NodeJS

var request = require('request');

var headers = {
    'CLIENT-ID': '<client-id>',
    'AUTHORIZATION': 'apikey <username>:<api-key>',
    'PASSWORD': '<password>',
    'SECRET-KEY': '<secret-key>'
};

var options = {
    url: 'https://api.photoncommerce.com/api/v4',
    method: 'POST',
    headers: headers
};

function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}

request(options, callback);

Java

import java.io.IOException;
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;

class Main {

	public static void main(String[] args) throws IOException {
		URL url = new URL("https://api.photoncommerce.com/api/v4");
		HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
		httpConn.setRequestMethod("POST");

		httpConn.setRequestProperty("CLIENT-ID", "<client-id>");
		httpConn.setRequestProperty("AUTHORIZATION", "apikey <username>:<api-key>");
		httpConn.setRequestProperty("PASSWORD", "<password>");
		httpConn.setRequestProperty("SECRET-KEY", "<secret-key>");

		InputStream responseStream = httpConn.getResponseCode() / 100 == 2
				? httpConn.getInputStream()
				: httpConn.getErrorStream();
		Scanner s = new Scanner(responseStream).useDelimiter("\\A");
		String response = s.hasNext() ? s.next() : "";
		System.out.println(response);
	}
}

The following are key fields that the API returns, including the type and description. A complete list is below this table.

Field	Type	Description
Invoice_Number	string	Invoice number
PO_Number	string	Purchase Order number
Date	string <yyyy-MM-dd>	Document date as it appears in the document
Payment_Terms	string	Terms of payment, e.g., Net-30
Due_Date	string <yyyy-MM-dd>	Invoice due date
Currency_Code	string	Currency code, e.g., USD, EUR, CNY, etc.
Discount	decimal	Discount provided on the invoice or receipt
Vat_Number	string	The Value Added Tax number, e.g., 12-3456789
Total	decimal	Total of the invoice or receipt

The following describes the complete fields and value types. Empty and null values for all fields will appear as with 0 or empty quotations "", depending on if the field type is numeric or text. For an example response, please see the above "Response" tab.

{
	"data": {
	
		# Invoice data
		
		"Invoice_Number":  <invoice number string>,
		"PO_Number":       <purchase order number string>,
		"Date":            <invoice date yyyy-MM-dd string>,
		"Order_Date":      <the date when the items were ordered yyyy-MM-dd string>,
		"Payment_Terms":   <interpreted terms, e.g. Net-30>,
		"Due_Date":        <invoice due date yyyy-MM-dd string>,
		"Currency_Code":   <currency code e.g. USD string>,
		"Discount":        <decimal percent discount numeric>,
		"Vat_Number":      <tax number e.g. 12‑3456789 string>,
		"Pages":           <page count of the invoice>,
		"Is_Duplicate":    <binary value depicting whether the same invoice was uploaded earlier>,
		"Notes":           <any note if mentioned on the invoice string>,
		"Category":        <industry category depending on the line items>,
		"Document_Type":   <interpretation of document type>,
		
		# Purchase data
		
	  	"Total":                 <decimal dollar amount>,
		"Shipping":              <decimal dollars found for shipping>,
		"Subtotal":              <decimal pretax dollars subtotal>,
		"Tax":                   <decimal dollars found for tax>,
		"Tip":                   <decimal dollars found for tip>,
		"Cashback":              <decimal dollars found for cashback change>,
		"Balance_Due":           <decimal dollar amount owed to the vendor>,
		"Service_Start_Date":    <date of the start of the service string>,
		"Service_End_Date":      <date of the end of the service string>,
		"Tracking_Number":       <tracking number of the shipment string>,
		"Tax_Lines":             <list of decimals of line item tax amounts>,
		"Line_Items": [{
			"Line":                <integer incrementing counter>,
			"SKU":                 <parsed SKU code>,
			"Description":         <raw item description>,
			"Date":                <date of the line item as a string "YYYY-MM-DD">,
			"Reference":           <Reference ID for the item>,
			"Order:"               <integer representing order of the line item>,
			"QTY":                 <decimal number of units>,
			"Unit":                <unit of measure>,
			"Price":               <decimal unit price>,
			"Amount":              <decimal total pricing>,
			"Discount":            <decimal line item discount amount>,
			"Tax_Rate":            <decimal tax rate levied>,
			"Tax",                 <decimal line item tax amount>,
			"Type"                 <inferred product or service string>
		}],
		
		# Recipient/Payer data
		
		"Account_Number":        <payer account number>,
		"Bill_To_Name":          <payer company name>,
		"Bill_To_Recipient":     <payer person name>,
		"Bill_To_Address":       <payer address>,
		"Bill_To_Address_Line":  <parsed payer address line 1>,
		"Bill_To_City":          <parsed payer city>,
		"Bill_To_State":         <parsed payer state>,
		"Bill_To_Zipcode":       <parsed payer postal code>,
		"Bill_To_Vat_Number":    <payer VAT number>,
		"Bill_To_Email":         <payer email address>,
		"Card_Number":           <payment credit card number if present>,
		"Payment_Display_Name":  <fulltext of payment card info if present e.g. ***9999>,
		"Payment_Type":          <inferred payment method e.g. Visa>,	

		# Vendor data
		
		"Vendor_ABN_Number":     <Australian Business Number>, 
		"Vendor_Account_Number": <Vendor bank account number>,
		"Vendor_Bank_Name":      <Routing number of the bank>,
		"Vendor_Bank_Number":    <Bank routing number for payment routing>,
		"Vendor_Bank_Swift":     <SWIFT code of the vendor bank account>,
		"Vendor_IBAN":           <IBAN International Bank Account Number of the vendor>,
		"Vendor_Name":           <Invoice issuing vendor name>,
		"Vendor_Raw_Name":       <Invoice issuing vendor name - raw>,
		"Vendor_Email":          <Email address of the vendor>,
		"Vendor_Address":        <Full unparsed address of vendor company>,
		"Vendor_Recipient":      <Personal name of the vendor>,
		"Vendor_Address_Line":   <Vendor parsed address line 1 and 2>,
		"Vendor_City":           <Parsed city>,
		"Vendor_State":          <Full state e.g. California or state code e.g. CA>,
		"Vendor_Zipcode":        <Parsed postal code>,
		"Vendor_Country":        <The two letter country code of the vendor per ISO 3166-1 Alpha-2>,
		"Vendor_Phone":          <Vendor phone number - raw>,
		"Vendor_Fax":            <Vendor fax number - raw>,
		"Vendor_Type":           <Vendor industry category>,
		"Vendor_Website":        <Webpage address of the Vendor>,
		"Remit_To_Name":         <The name of the person/company to whom the payment should be made string>,
		"Remit_To_Address":      <The address to which checks should be mailed string>,
		
		"Phone_Number":          <payer phone number>,
		"All_Email_Addresses":   <comma-separated list of emails found in invoice>,
		
		# Ship to data
		"Ship_To_Name":          <the name of the person the shipment has to be delivered to>,
		"Ship_To_Address":       <the location where the consignment needs to be shipped>,
		"Ship_Date":             <date when the consignment will be shipped. yyyy-MM-dd string>,
		"Delivery_Date":         <the date when the consignment will be/is estimated to be delivered>,
		"Carrier":               <the carrier in charge of delivering the shipment>,
		
		# Photon Commerce data
		
		"Raw_Text":              <full parsed text>,
		"Reference_Number":      <internal photon ref #>,
		"photon_key":            <JSON data file location>
	},
	"message": "success",
	"status": "success"
}