This FAQ is for users signed up for Veryfi before August 2022.

Why v8?

Over the past few months, API v8 transitioned from beta to production status, and it’s now the recommended API version for new users of the Veryfi platform.

We’ll continue to support v7 as long as you need, however, we are no longer adding new features to v7.

We encourage you to scope out your transition to API v8 as soon as you can, to take advantage of the following enhancements:

More logical; improved JSON structure
More stable; e.g., v7 has a limitation for the number of documents users can request with the GET call
More flexible; e.g., in v8 there are more fields that users can update
More fields; v8 includes many fields beyond what v7 supports. You can see the full list of JSON fields in this Interactive API schema.

For additional details on the differences between API versions 7 and 8, please consult the interactive API documentation.

How to switch

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/

For your convenience, just released an Interactive API Documentation feature in the Veryfi Portal (Hub). You can now try out Veryfi’s API versions while viewing the documentation directly on the Veryfi website.

Main Changes

The main differences between v7 and v8 of the Veryfi API are the request and response structure differences listed below. 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.

Boolean Parameters in Requests

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"

Affected parameters:

return_audit_trail
confidence_details
bounding_boxes
auto_delete
boost_mode
parse_address
detect_blur
async

Boolean Fields in Responses

Similar to the above, booleans in responses have also been moved from the 1/0 style to true/false.

Affected fields:

img_blur
is_document
is_duplicate
is_money_in
confidence_details

Missing Field Confidence Score

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
},

Response Structure Changes

abn_number, vat_number, phone_number and all fields with the vendor_ prefix at the root level have been moved inside the vendor object
the vendor_ prefix on all vendor fields has been stripped
all fields with bill_to_ prefix have been moved into the bill_to object
all fields with ship_to_ prefix have been moved into the ship_to object
all fields with payment_ prefix have been moved into the payments object
created is now created_date
updated is now updated_date

Comparison of v7 and v8 Responses

With the above changes in mind, let’s take a look at an example response snippet from v7 vs v8 for the same request.

API v7 Response

{
"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": "",
 ...
}

API v8 Response

{
"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": "",
},
 ...
}

For your convenience Interactive API allows you to see v7 and v8 API schema.

Pagination

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 query string 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&amp;page=1&amp;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
}
}