Getting Started with the Photon Commerce API

The industry's most intelligent reading of invoices and receipts, including line-item comprehension

Welcome to Photon Commerce!

You can use our API to access our endpoints, which can create, and access tasks. You'll be up and running in no time!

TL;DR Just give me the code

cURL
Python
C#
Java
JavaScript
NodeJs
Ruby
cURL
curl -F "[email protected]/path_to_your_document.jpg" https://api.photoncommerce.com/\?api_key\=your_api_key
Python
import requests
URL = "https://api.photoncommerce.com/?api_key="+your_api_key
files = {"pdf": open(path_to_your_doc, "rb")}
response = requests.post(URL, files=files)
C#
var client = new RestClient("https://api.photoncommerce.com/?api_key=api_key");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddFile("pdf", "/path_to_your_document.pdf");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Java
Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://api.photoncommerce.com/?api_key=api_key")
.field("file", new File("/path_to_your_document.pdf"))
.asString();
JavaScript
var formdata = new FormData();
formdata.append("pdf", fileInput.files[0], "your_document.pdf");
var requestOptions = {
method: 'POST',
body: formdata,
redirect: 'follow'
};
fetch("https://api.photoncommerce.com/?api_key=api_key", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
NodeJs
var request = require('request');
var fs = require('fs');
var options = {
'method': 'POST',
'url': 'https://api.photoncommerce.com/?api_key=api_key',
formData: {
'pdf': {
'value': fs.createReadStream('/path_to_your_document.pdf'),
'options': {
'filename': 'your_document.pdf',
'contentType': null
}
}
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
Ruby
require "uri"
require "net/http"
url = URI("https://api.photoncommerce.com/?api_key=api_key")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.new(url)
form_data = [['pdf', File.open('/path_to_your_document.pdf')]]
request.set_form form_data, 'multipart/form-data'
response = https.request(request)
puts response.read_body

If you haven't already, contact Photon Commerce at info @ photoncommerce.com to be set up with an account. Photon will send you your API keys.

The Photon Commerce API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Photon Commerce's various AI APIs may or may not be powered in part by its own proprietary pipelines, OpenAI, Microsoft, AWS, Nvidia, UIPath, and/or other cutting edge automation technologies.

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 is 3-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.

post
Invoice and receipt capture

https://api.photoncommerce.com/
Contact Photon Commerce at api @ photoncommerce.com to request free API access to a sandbox environment customized to your requirements.
Request
Response
Request
Path Parameters
api_key
required
string
Authentication token. Get your API key from Photon Commerce
Form Data Parameters
pdf
required
string
The path to the pdf, document, or image needing to be captured. Despite the field saying pdf, it has been expanded to accept images, photos, and word documents too
Response
200: OK
{
"data": {
"Total": 166.95,
"Date": "2020-09-11",
"Time": "16:47:00",
"Category": "",
"Subtotal": 166.95,
"Tax": 0.0,
"Tip": 0.0,
"Card_Number": "",
"Currency_Code": "USD",
"Payment_Display_Name": "Visa",
"Payment_Type": "visa",
"Phone_Number": "415-400-5754",
"Vendor_Name": "Sam's Club",
"Vendor_Address": "23 Lombard St, San Francisco, CA 94123",
"Vendor_Phone": "415-555-5555",
"Line_Items": [
{
"Line": 1,
"SKU": "",
"Description": "Services",
"QTY": 1.0,
"Unit": "",
"Price": 0.0,
"Amount": 35.0
},
{
"Line": 2,
"SKU": "",
"Description": "Engineering",
"QTY": 1.0,
"Unit": "",
"Price": 0.0,
"Amount": 100
}
],
"Raw_Text": "INVOICE"
},
"message": "success",
"status": "success"
}

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. 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>,
"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>,
# 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>,
"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 description>,
"QTY": <decimal number of units>,
"Unit": <unit of measure>,
"Price": <decimal unit price>,
"Amount": <decimal total pricing>,
"Discount", <decimal line item discount amount>,
"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>,
"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": <Bank name for payment routing>,
"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_Phone": <Vendor phone number - raw>,
"Vendor_Fax": <Vendor fax number - raw>,
"Vendor_Type": <Vendor industry category>,
"Phone_Number": <payer phone number>,
"All_Email_Addresses": <comma-separated list of emails found in invoice>,
# Photon Commerce data
"Category": <interpretation of document type>,
"Raw_Text": <full parsed text>,
"Reference_Number": <internal photon ref #>,
"photon_key": <photon file location>
},
"message": "success",
"status": "success"
}

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.

Asynchronous API for large, complex batches and queues of documents

post
Make a task

https://api.photoncommerce.com/
This endpoint creates a task to transcribe the document or image to data. Our process will convert the doc attachment into a structured JSON response or
Request
Response
Request
Headers
api_key
required
string
Authentication token in the form of YOUR_API_KEY
Form Data Parameters
format
optional
string
Output formats speciified. Examples include: Excel, csv, JSON, etc.
batch
optional
string
The name of the batch to associate this task with
project
optional
string
The name of the project to associate this task with
email
required
string
Email address for returning the data, notification, and callback to
doc
required
string
Location of file to be digitized in this format: @/path/to/file.png
instructions
required
string
Instructions in plain text for how to transcribe the document(s) in the task
Response
200: OK
{
"email": "[email protected]",
"doc": "gs://bucket/file.pdf",
"api_key": "your_api_key",
"instructions": [
"tracking number",
"origin address",
"destination address",
"line items"
],
"project": "my project",
"batch": "batch 1",
"_id": "5e5606fe93f61a002c8731c5",
"status": "submitted",
"md5": "9751f80554096d59180248d87f467de0",
"createdAt": "2020-02-26T05:49:50.761Z",
"updatedAt": "2020-02-26T05:49:50.761Z",
"__v": 0
}
500: Internal Server Error
{
"error": "problem with the task",
"code": 500
}

get
Retrieve data

https://api.photoncommerce.com/
Get a specific document
Request
Response
Request
Path Parameters
filename
required
string
The name of the file
Headers
api_key
required
string
Authentication token in the form of YOUR_API_KEY
Form Data Parameters
task
optional
string
The name of the task associated with the desired documents(s)
project
optional
string
The name of the project associated with the task or document(s)
Response
200: OK
{
"email": "[email protected]",
"doc": "gs://bucket/file.pdf",
"api_key": "your_api_key",
"instructions": [
"tracking number",
"origin address",
"destination address",
"line items"
],
"project": "my project",
"batch": "batch 1",
"message": "Task completed",
"response":
{
"heading": {
"Invoice #": "100001",
"Date": "2020-04-04"
},
{
"@type": "Invoice",
"broker": {
"@type": "LocalBusiness",
"name": "ACME Home Heating"
},
"accountId": "xxxx-xxxx-xxxx-1234",
"customer": {
"@type": "Person",
"name": "Jane Doe"
},
"paymentDueDate": "2015-01-30",
"minimumPaymentDue": {
"@type": "PriceSpecification",
"price": 0.00,
"priceCurrency": "USD"
},
"totalPaymentDue": {
"@type": "PriceSpecification",
"price": 0.00,
"priceCurrency": "USD"
},
"paymentStatus": "Complete",
"referencesOrder":
[
{
"@type": "Order",
"description": "furnace",
"orderDate": "2014-12-01",
"orderNumber": "123ABC",
"paymentMethod": "http://purl.org/goodrelations/v1#ByInvoice",
"orderedItem": {
"@type": "Product",
"name": "ACME Furnace 3000",
"productID": "ABC123"
}
},
{
"@type": "Order",
"description": "furnace installation",
"orderDate": "2014-12-02",
"paymentMethod": "http://purl.org/goodrelations/v1#ByInvoice",
"orderedItem": {
"@type": "Service",
"description": "furnace installation"
}
}
]
},
"_id": "5e5606fe93f61a002c8731c5",
"status": "submitted",
"md5": "9751f80554096d59180248d87f467de0",
"createdAt": "2020-02-26T05:49:50.761Z",
"updatedAt": "2020-02-26T05:49:50.761Z",
"__v": 0
}
404: Not Found
{
"error": "not found",
"code": 404
}