API Version 8
Author: Andrew Bakonski
The Veryfi API version 8 release is here!
Making the switch to version 8 is as simple as changing the version portion of the API endpoint URLs. For example, if you’re currently using version 7, you’re used to submitting documents for processing at this endpoint:
https://api.veryfi.com/api/v7/partner/documents/
To switch to version 8, all you’ll need to do is change that v7
to a v8
like so:
https://api.veryfi.com/api/v8/partner/documents/
Before making the switch to API v8, make sure you’ve reviewed the following breaking changes as these will require corresponding implementation changes in your application code.
Version 8 abandons 1/0
style booleans for a more traditional true/false
style of boolean.
For example, when enabling the async
flag on a request, the JSON request body may look something like this:
{ "file_url": "https://example.com/invoice.png", "file_name": "invoice.png", "async": true }
NOTE: When working with multipart/form-data requests, you can set a parameter to false by either omitting the parameter from the request or by setting it to an empty string. To set the parameter to true, set it to the literal string: "true"
Similar to the above, booleans in responses have also been moved from the 1/0
style to true/false
.
In v8, when confidence scores are enabled and a field is not found on the document by the Veryfi AI, that field’s value is set to null
. The confidence score assigned to the field indicates how confident the AI model is that the field indeed doesn’t exist in the document.
In the below example, the model is about 98.9% confident that no Purchase Order Number exists on the document:
{ ... "purchase_order_number": { "score": 0.9890872435644269, "value": null }, ... }
abn_number
, vat_number
, phone_number
and all fields with the vendor_
prefix at the root level have been moved inside the vendor
objectvendor_
prefix on all vendor fields has been strippedbill_to_
prefix have been moved into the bill_to
objectship_to_
prefix have been moved into the ship_to
objectpayment_
prefix have been moved into the payments
objectcreated
is now created_date
updated
is now updated_date
With the above changes in mind, let’s take a look at an example response snippet from v7 vs v8 for the same request.
{ "abn_number": "", "bill_to_address": "", "bill_to_email": "", "bill_to_name": "", "bill_to_phone_number": "", "bill_to_reg_number": "", "bill_to_vat_number": "", "card_number": "", "created": "2021-07-22 18:55:01", "id": 23000001, "img_blur": 0, "is_approved": 0, "is_document": 0, "is_duplicate": 0, "is_money_in": 0, "payment_display_name": "No Payment,", "payment_type": "no_payment,", "phone_number": "", "ship_to_address": "", "ship_to_name": "", "updated": "2021-07-22 18:55:01", "vat_number": "", "vendor": { "address": "", "category": "", "email": "", "external_ids": [], "fax_number": "", "lat": 0.0, "lng": 0.0, "name": "", "phone_number": "", "raw_name": "", "vendor_logo": "", "vendor_reg_number": "", "vendor_type": "", "web": "" }, "vendor_account_number": "", "vendor_bank_name": "", "vendor_bank_number": "", "vendor_bank_swift": "", "vendor_iban": "", ... }
{ "bill_to": { "address": "", "email": "", "name": "", "phone_number": "", "reg_number": "", "vat_number": "", }, "created_date": "2021-07-22 16:39:52", "id": 23000001, "img_blur": false, "is_approved": false, "is_document": false, "is_duplicate": false, "is_money_in": false, "payment": { "card_number": "", "display_name": "No Payment", "type": "no_payment" }, "ship_to": { "address": "", "name": "" }, "updated_date": "2021-07-22 16:39:52", "vendor": { "abn_number": "", "account_number": "", "address": "", "bank_name": "", "bank_number": "", "bank_swift": "", "category": "", "email": "", "external_ids": [], "fax_number": "", "iban": "", "lat": 0.0, "lng": 0.0, "logo": "", "map_url": "", "name": "", "phone_number": "", "raw_name": "", "reg_number": "", "type": "", "vat_number": "", "web": "", }, ... }
Version 8 introduces pagination to document GET
requests. This provides control over how many documents are returned per search query and allows for short response times when a query results in a large number of documents.
To enable pagination, simply specify the page
and page_size
querystring parameters. For example, this request will return the first 50 documents:
curl --location --request GET 'https://api.veryfi.com/api/v8/partner/documents/?q=keyword&page=1&page_size=50' \ --header 'CLIENT-ID: **********' \ --header 'AUTHORIZATION: apikey *********:**********'
The response contains the pagination information inside the meta
object, for example:
{ "documents": [ { "id": "12345", ... }, { "id": "12346", ... }, ... ], "meta": { "documents_per_page": 50, "page_number": 1, "total_pages": 3, "total_results": 121 } }
At the time of writing, the main differences between v7 and v8 of the Veryfi API are the request and response structure differences listed above. Functionally the two versions are close to identical.
For bug reports and feature requests, please reach out to us at support@veryfi.com