API Version 8

September 29, 2021

4 mins read

API Version 8

Related Knowledge

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/

Breaking Changes

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

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

Other Differences

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