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 thevendor_
prefix at the root level have been moved inside thevendor
objectthe
vendor_
prefix on all vendor fields has been strippedall fields with
bill_to_
prefix have been moved into thebill_to
objectall fields with
ship_to_
prefix have been moved into theship_to
objectall fields with
payment_
prefix have been moved into thepayments
objectcreated
is nowcreated_date
updated
is nowupdated_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&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
}
}
Other Related Articles:
For bug reports and feature requests, please reach out to us at support@veryfi.com