--- parser: v2 auto_validation: true time: 15 tags: [tutorial>beginner, topic>machine-learning, topic>artificial-intelligence, topic>cloud, software-product>sap-business-technology-platform, software-product>sap-ai-services, software-product>sap-document-ai, tutorial>free-tier] primary_tag: topic>machine-learning author_name: Juliana Morais author_profile: https://github.com/Juliana-Morais slug: cp-aibus-dox-swagger-ui canonical_url: https://developers.sap.com/tutorials/cp-aibus-dox-swagger-ui --- # Use Machine Learning to Extract Information from Documents with Swagger UI Get machine learning model predictions for the documents you upload to SAP Document AI. ## You will learn - How to call and test SAP Document AI - How to access and use Swagger UI (User Interface) - How to extract information from files with SAP Document AI ## Intro The core functionality of SAP Document AI is to automatically extract structured information from documents using machine learning. When you finish this tutorial, you will get field value predictions for the documents you upload to SAP Document AI. --- ### Access and authorize Swagger UI You'll use Swagger UI, via any web browser, to call the SAP Document AI APIs. Swagger UI allows developers to effortlessly interact and try out every single operation an API exposes for easy consumption. For more information, see [Swagger UI](https://swagger.io/tools/swagger-ui/). You need the service key that you created for SAP Document AI in the previous tutorial – either [Use Trial to Create a Service Instance for SAP Document AI](cp-aibus-dox-service-instance) or [Use Free Tier to Create a Service Instance for SAP Document AI](cp-aibus-dox-free-service-instance). Outside the `uaa` section of the service key, you'll find an entry called `tenantuiurl` and another called `swagger` (highlighted in the image below). 1. To access the SAP Document AI Swagger UI, first copy the `tenantuiurl` value and paste it into a text editor. Then, copy the `swagger` value and paste it onto the end of the `tenantuiurl` value. Finally, copy the resulting string, paste it into the address bar of your web browser, and press **Enter**. ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/service-key-details.png) 2. To be able to use the Swagger UI endpoints, you need to authorize yourself. In the top right corner, click **Authorize**. ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/swagger0.png) 3. Get the `access_token` value created in the previous tutorial [Get OAuth Access Token for SAP Document AI Using Any Web Browser](cp-aibus-dox-web-oauth-token), then add **Bearer** in front of it, and enter in the **Value** field. ``` Bearer ``` ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/Authorize.png) 4. Click **Authorize**, and then click **Close**. ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/Authorize2.png) ### See list of document fields you can extract Use the **GET /capabilities** endpoint to see the list of document fields and enrichment data for each document type you can process with SAP Document AI. Click the endpoint name to expand it, click **Try it out**, and then **Execute**. ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/capabilities.png) ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/capabilities2.png) You should receive a response like the following: ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/capabilitiesResponse.png) >If you get an error response code 401 (Unauthorized), your token is probably incorrect. Check if you have added the word **`Bearer`** before the token and if the token value is complete and has been properly copied from the **`access_token`** value you received in the previous tutorial: [Get OAuth Access Token for SAP Document AI via Web Browser](cp-aibus-dox-web-oauth-token). ### Get client When you create a service instance for SAP Document AI, a `default` client is automatically created. A client is used in most of the endpoints to distinguish and separate data. Free tier and trial users can only create one client. To see your list of clients: 1. Expand the **GET /clients** endpoint. 2. Click **Try it out**. 3. Enter a maximum number of clients to be listed in the **limit** field. 4. Click **Execute**. ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/listClient.png) You should receive a response like the following: ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/listClientResponse.png) ### Delete client Use the **DELETE /clients** endpoint to delete the `default` client. 1. Expand the **DELETE /clients** endpoint. 2. Click **Try it out**. 3. Enter in the **payload** field the client id (`default`) you want to delete. 4. Click **Execute**. ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/deleteClient.png) You should receive a response like the following: ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/deleteClientResponse.png) ### Create client Use the **POST /clients** endpoint to create your own client. The **`clientId`** value created here will be used in other SAP Document AI endpoints. 1. Expand the **POST /clients** endpoint. 2. Click **Try it out**. 3. Enter your **`clientId`** and **`clientName`** values in the **payload** field in the format you see in **Examples for payload parameter** (`c_00` and `client 00`, for example). 4. Click **Execute**. ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/createClient.png) You should receive a response like the following: ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/createClientResponse.png) You can repeat step 3 to see the **`clientId`** and **`clientName`** of the client you have just created. >**CAUTION:** >When using the free tier option for SAP Document AI or a trial account, be aware of the technical limits listed in [Free Tier Option and Trial Account Technical Constraints](https://help.sap.com/docs/document-information-extraction/document-information-extraction/free-tier-option-and-trial-account-technical-constraints). ### Upload document >SAP Document AI uses a globally pretrained machine learning model that currently obtains better accuracy results with invoices and payment advices in the languages listed in [Supported Languages and Countries](https://help.sap.com/viewer/5fa7265b9ff64d73bac7cec61ee55ae6/SHIP/en-US/5bf847f7d1a848dcb3513eff9ec70412.html). The team is working to support additional document types and languages in the near future. Use the **POST /document/jobs** endpoint to upload to SAP Document AI any document file in PDF or single-page PNG and JPEG format that has content in headers and tables, such as an invoice. >As an alternative to uploading your own document to SAP Document AI, you can use any of the following sample invoice files (right click on the link, then click ***Save link as*** to download the files locally): >- [Sample Invoice 1](https://github.com/SAPDocuments/Tutorials/raw/master/tutorials/cp-aibus-dox-swagger-ui/sample-invoice-1.pdf) >- [Sample Invoice 2](https://github.com/SAPDocuments/Tutorials/raw/master/tutorials/cp-aibus-dox-swagger-ui/sample-invoice-2.pdf) >- [Sample Invoice 3](https://github.com/SAPDocuments/Tutorials/raw/master/tutorials/cp-aibus-dox-swagger-ui/sample-invoice-3.pdf) Do the following: 1. Expand the **POST /document/jobs** endpoint. 2. Click **Try it out**. 3. Upload a document file. 4. In **options**, enter the list of fields to be extracted from the uploaded file (`documentNumber`, `taxId`, `purchaseOrderNumber`, `shippingAmount`, `netAmount`, `senderAddress`, `senderName`, `grossAmount`, for example), the client you created in step 5 (`c_00`, for example), and the document type (`invoice`, for example). In this case, you can use the following: ```JSON { "extraction":{ "headerFields":[ "documentNumber", "taxId", "purchaseOrderNumber", "shippingAmount", "netAmount", "senderAddress", "senderName", "grossAmount", "currencyCode", "receiverContact", "documentDate", "taxAmount", "taxRate", "receiverName", "receiverAddress" ], "lineItemFields":[ "description", "netAmount", "quantity", "unitPrice", "materialNumber" ] }, "clientId":"c_00", "documentType":"invoice", "receivedDate":"2020-02-17", "enrichment":{ "sender":{ "top":5, "type":"businessEntity", "subtype":"supplier" }, "employee":{ "type":"employee" } } } ``` 5. Click **Execute**. ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/testInvoice.png) After you have clicked **Execute**, you should receive a response like the following: ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/testInvoiceResult.png) Copy the **`id`** from the **Response body** to see the result of the extraction in the next step. ### See extracted fields You can now use the **GET /document/jobs/{`id`}** endpoint to receive the prediction. 1. Expand the **GET /document/jobs/{`id`}** endpoint. 2. Click **Try it out**. 3. Set **`extractedValues`** to `true` to get the extracted values. 4. Enter the **`id`** received in the **POST /document/jobs** endpoint as the **`id`**. 5. Click **Execute**. ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/getResults.png) You should receive a response like the following: ![DOX](https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/cp-aibus-dox-swagger-ui/getResultsResponse.png) In the response, you will find some general information about the document you uploaded. In `headerFields`, such as `documentDate` and `taxAmount`, and in `lineItems`, such as `description` and `quantity`, you will find the prediction for the extracted fields. The prediction is made with a probability indicated by the **confidence** field which represents how certain the model is about its prediction. A confidence of 1 means that the model is 100% sure about its prediction. If the status of the document (indicated by the **status** field) is **PENDING** instead of **DONE**, then it means that SAP Document AI is still extracting some fields and the returned JSON file does not yet contain all the requested fields. You have now successfully used our machine learning model to get field value predictions for the document you uploaded to SAP Document AI. You can repeat step 4 and delete the client you created in step 5. Congratulations, you have completed this tutorial.