Using Postman with DocDigitizer PowerCapture API

Brief description how to use DocDigitizer PowerCapture API using Postman

In this tutorial, we'll lead you through the basic steps on how to integrate with DocDigitizer PowerCapture API using Postman.

DocDigitizer PowerCapture API is a REST API that conforms to the constraints of REST architectural style and allows for interaction with RESTful web services.

For this tutorial, use a standard Customer scenario using Windows App Postman.
You can download the app from Postman

If you aren't familiar with Postman, please check the following resources:
Postman Learning
Postman Getting Started

Request access

The first step is to request DocDigitizer to create an Account.

To request a Free Trial Account, go to this below link and fill out the request form.
Free Trial Account

After you will receive an email with information to help get started and with Postman Collection.
The Postman Collection is already configured with API_KEY that authorizes access to the DocDigitizer PowerCapture API and also identifies the organization/company/entity.

Setup Postman Collection

Open Postman and import the Collection file that you received.

640640 13151315 582582

Process flow overview

The standard customer scenario involves 3 requests to DocDigitizer PowerCapture API, and as an optional service, DocDigitizer sends notifications about the status of the document submitted client side.

701701

HTTP Headers & Authorization

As previously mentioned, for your request to be authorized you need API_KEY.
Click on one of the requests and go to the "Header" tab and check KEY "Authorization" where you can see your API_KEY.

The Content-Type = "multipart/form-data" is needed only for the "Submit document," because in this service you are sending files (encode the data that forms the body of the request).

640640

Submit document

Purpose: submit a file for processing indicating the class of the document. In the response, there is the value of “document_id” that identifies the submission
Method: POST

Path Parameters:

  • document_class : “financial-document”
    The “Document Class” in the scope of Free Trial Accounts are: “Financial Documents
    To obtain information about these types of documents (Invoice, Credit Note, etc.) in the scope of “Financial Documents” and their rules, please consult Guides Financial Documents
    To get detailed information about fields extracted from “Financial Documents” and the meaning of each file, please consult Data Schema

Body Parameters:

  • files : file to submitted to extract data
  • callback_url : (optional parameter) you can add the URL of your service to receive a notification when there is a change in the status of the document submitted (e.g. review process finished).
925925

When sending the request, in case of Accepted (Status=202), you will receive a response similar to the following:

{
    "detail": "Accepted",
    "status": 202,
    "task": {
        "created": "2021-11-02T12:14:26.564283",
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "links": {
            "self": "/api/v1/tasks/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "collection": "/api/v1/tasks"
        },
        "status": "PENDING"
    }
}

To get the ID of documents submitted to the DocDigitizer platform, you need to check the Header of the response.
On the Postman response area, go to the "Header" tab and check KEY X-Document-Location
The document ID value is the GUID that you find at end of the URL (see image below).
This value will be used on the next services.

624624

Receive data extracted from the document

Purpose: Get data extract from any given document
Method: GET

Path params:

  • document_id : (if callback) Id send in the notification service; Id receive "Submit Document"

For this tutorial we will assume that there is no service (callback) to receive the notification.
Use the Document Id receive on the "Submit Document" and used when calling this service.

822822

When you call this service, check the response and see values:

  • "reviewed": if True this means that the process of this document has finished, otherwise (False) reviewed process is still "running."
    If True check "annotations" group that will have data extracted (when reviewed is False the fields can have values but the the validation/human process is not finished)
  • "rejected": If True, this means that the process has finished and the document was rejected.

Note: The extraction/reviewed process is asynchronous and by default (as is the case of Free Trial Account) involves “Human Revision.”
For this reason, the data extract will not be immediately available, having an SLA of 30 minutes

To get detailed information about fields extracted from “Financial Documents” and the meaning of each file, please consult Data Schema

{
    "status": 200,
    "detail": "Ok",
    "document": {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "annotation_status": "success",
        "reviewed": true,
        "context": "[email protected]",
        "rejected": false,
        "annotations": {
            "links": {
                "self": "/api/v1/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/annotations",
                "document": "/api/v1/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
            },
            "data": {
                "document:financial-document:document_type": "Invoice",
                "document:financial-document:supplier_name": "ACME LDA",
                "document:class": "financial-document",
                "document:financial-document:due_date": "2021-01-31T00:00:00",
                "document:financial-document:amount_tax_total": "28.52",
                "document:financial-document:tax_breakdown": [
                    {
                        "tax_total": "152.52",
                        "tax_rate": "0.23",
                        "tax_base": "124.00",
                        "tax_amount": "28.52",
                        "tax_code": "IVA"
                    }
                ],
                "document:financial-document:amount_rounding": "",
                "document:financial-document:amout_base_total": "124.00",
                "document:financial-document:currency": "EUR",
                "document:financial-document:document_identifier": "FT A/173",
                "document:financial-document:amount_total": "152.52",
                "document:financial-document:order_number": [],
                "document:financial-document:line_items": [
                    {
                        "item_base_amount": "2.00",
                        "item_base_total_amount_base": "4.00",
                        "item_tax": "",
                        "item_code": "",
                        "item_description": "CUSTOM - CANDIDATURAS",
                        "item_unit": "",
                        "item_amount": "",
                        "item_amount_total": "4.92",
                        "item_rate": "0.23",
                        "item_order_number": "",
                        "item_quantity": "2.0"
                    },
                    {
                        "item_code": "",
                        "item_amount_total": "147.60",
                        "item_base_amount": "40.00",
                        "item_amount": "",
                        "item_tax": "",
                        "item_base_total_amount_base": "120.00",
                        "item_rate": "0.23",
                        "item_order_number": "",
                        "item_description": "CUSTOM - DESCRIPTION",
                        "item_unit": "",
                        "item_quantity": "3.0"
                    }
                ],
                "document:financial-document:recipient_tax_number": "506412580",
                "document:financial-document:issue_date": "2021-01-31T00:00:00",
                "document:financial-document:amount_due": "152.52",
                "document:financial-document:recipient_name": "ACME SERVICES, S.A.",
                "document:financial-document:amount_paid": "",
                "document:financial-document:supplier_tax_number": "123456789"
            }
        },
        "created": "2021-10-29T10:48:51.813448+00:00",
        "tags": [],
        "links": {
            "self": "/api/v1/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "collection": "/api/v1/documents",
            "reviews": "/api/v1/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/reviews",
            "annotations": "/api/v1/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/annotations",
            "assets": "/api/v1/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/assets"
        },
        "review_date": "2021-10-29T11:07:04.876735+00:00"
    }
}

In the scenario that you supplied "callback_url" (Notification service), call this service when receiving “Notification” with “status“=“annotated” (passing the corresponding “document_id”)

Get rejection information

Reject a document
Purpose: Get information about rejection of a document of given document
Method: GET

Path params:

  • document_id : id send in the notification

Call this service when receiving a response with "rejected"=True

813813

You will receive a response with information about the rejection.

{
    "status": 200,
    "detail": "Ok",
    "rejection": {
        "rejected_at": "2021-07-09T15:04:55.555487+00:00",
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "justification_code": "OTHER",
        "justification": "Invalid document type"
    }
}

Noification Service

Notification
Purpose: Receive notification about a change in the status of the submitted document
Service to be provider by the Customer
Method: GET

Parameters:

  • document_id : id of the document
  • status : status of the document (annotated, rejected, …)

For more information see Callback service (status notification)

Next steps

Postman lets you explore the DocDigitizer PowerCapture API and easily add or change any requests that you want to test.
You can use the requests that came with the Collection provided and transform them into program code.
Postman offers functionalities to transform the request you issue with its Generate Code Snippets tool.


Did this page help you?