Getting Started with the Photon Commerce API

Photon Commerce's various AI APIs may be powered in part by OpenAI, Microsoft, AWS, Nvidia, UIPath, and a host of other cutting edge automation technologies.

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!

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.

If you haven't already, sign up on our app to start using our API.

Capture an invoice or receipt in real time

A typical REST API POST of a PDF that is less than 1MB is 3-7 seconds to return a structured JSON response. API code in various languages, such as python, node, PHP, JAVA, C#, CURL, etc., are available upon request.

post
Invoice and receipt capture

https://api.photoncommerce.com/
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 accepts images, photographs, 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"
}

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 follow describes the complete fields and value types. For an example response, please see the above "Response" tab.

{
"data": {
# invoice info
"Invoice_Number": "<invoice number>",
"PO_Number": "<purchase order>",
"Date": "<invoice date yyyy-MM-dd>",
"Payment_Terms": "<interpreted terms, e.g. Net-30>",
"Due_Date": "<invoice due date yyyy-MM-dd>",
"Currency_Code": "<currency code e.g. USD>",
"Discount": < decimal percent discount > ,
"Vat_Number": "<tax number e.g. 12‑3456789>",
# purchase info
"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> ,
"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>
}],
"Tracking_Number": "<shipment info>",
# recipient/payer info
"Account_Number": <payer account number>,
"Bill_To_Name": <payer company name>,
"Bill_To_Recipient": <payer 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>,
"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 info
"Vendor_Account_Number": <bank account number>,
"Vendor_Bank_Name": <Bank name for payment routing>,
"Vendor_Bank_Number": <Bank acct # for payment routing>,
"Vendor_Name": <invoice issuing vendor name>,
"Vendor_Address": <Full unparsed address of vendor company>,
"Vendor_Recipient": <personal name of the vendor>,
"Vendor_Address_Line": <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>,
"Phone_Number": <payer phone number>,
"All_Email_Addresses": <comma-separated list of emails found in invoice>,
# Photon info
"Category": <interpretation of document type>,
"Raw_Text": <full parsed text>,
"Reference_Number": <internal photon ref #>,
"photon_key": <photon file location>
},
"message": "<success>",
"status": "<success>"
}

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
}