Ublion API Quick Start

Understanding Ublion API

Introduction

The Ublion API is organized around REST. The API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the Ublion API to process your documents directly from your file system directories, to interact with any system, software, tool, or even document exchange platforms.

Ublion API supports asynchronous processing. This means that you executes tasks “in the background” without to wait for the task to finish.

API BASE URL

https://{{tenant}}-connectapi.{{domain}}.com
*Where tenant is the tenant name you entered during registration of your account.

Multitenant

Ublion asks you to create a tenant when you create an account. Tenant is a term borrowed from software multitenancy. It refers to an architecture where a single software instance serves multiple tenants. In Ublion, a tenant is logically isolated. No tenant can access the data of another tenant, even though multiple tenants might be running on the same machine.

Ublion Tenant charactetristics:

  • The tenant name has to be unique. It will be used to create your personal domain.
  • The tenant name can contain only lowercase alphanumeric characters and hyphens (“-“). It cannot begin or end with a hyphen.
  • The tenant name must be a minimum of three characters and maximum of 64 characters.
  • The tenant name cannot be changed after creation.
  • You can create more than one tenant; in fact, you are encouraged to do so for each environment you have (such as administrations or customers).
  • You can create additional tenants at any time. To do so, go to the administration menu in the user interface / portal.
  • By default, Ublion let you create up to 50 tenants with 10 users each.

Domains

When you create a new account with Ublion, you are asked to pick a name for your tenant. This name will be used for your Ublion domain. It’s the base URL you use to access the Ublion user interface and API and the URL where your users are redirected in order to authenticate.

Create multiple tenants

You can configure multiple tenants in the Ublion Portal or throug Ublion API to process documents for multiple users, trading partners, departments, locations,  or administrations.

For instance, if you have 10 different administrations, or would like to allow users or customers to log in different Ublion applications, the best solution is to create a tenant for each of them. This will allow you to have separate sets of environments for invoice processing, connections, languages, and users you need to support.

Authentication

Our APIs enables you to securely exchange your documents between your server and Ublion. Ublion APIs support JSON and require bearer token authentication.

  • A request will look like this: https://{{tenant}}-connectapi.{{domain}}.com/Api/TokenAuth/authenticate
  • Send a POST request to https://{{tenant}}-connectapi.{{domain}}.com/Api/TokenAuth/authenticate with the Context-Type=”application/json” header as shown:

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

When the authentication is successfull, Ublion will provide you with an access token. Use the token to authorize your API calls.

Name

Value

Content type

"Application/Json"

Method

Post

UserNameOrEmailAddress

Username

Password

The authentication password

Name

Value

Result.AccessToken

Bearertoken

TargetURL

Success

True or False

Error

UnauthorizedRequest

False

__abp

True

Ublion will give the following response.

Name

Value

Method

Get

Content-type

Application/Json

Authorization

Bearer your-auth-token

To test the connection you can use the document service to get a list of documents. For example by sending a POST request to https://{{tenant}}-connectapi.{{domain}}.com/api/services/app/Document/GetAll

Note that the result will be empty as you didn’t process any documents yet.

Data pipeline configuration

The endpoint to configure the data pipeline can be reached at: /api/services/app/Document/SetPipeline

Push-Pull

For immediate notification and transport, Ublion’s push-pull mechanism is used to inform the Ublion workers about new tasks.

The name of the push-pull channel contains three elements: {language}_{product}_{scope}.

Document storage (retention)
To ensure processing, the entire document life cycle is saved in cache. And the configuration of the database is done in the application.json.

Document properties

Name

Field

Default value

Description

Ublion cache name

App.Document.CacheName

documentNode

This setting defines where Ublion has to save the successful generated files (JSON, EDI, XML, PDF, UBL, etcetera)

Document number

App.document.Number

0

Used to determine the next document number (ID), used to generate Invoice numbers, Order numbers etc. 

Pipeline

App.Document.PipelineDoc.Doc

nl_shared_ublion

The pipeline that is used. A pipeline processes your documents.

Document upload

Upload your disparate semi- and unstructured documents via Ublion online portal or through API in a multi-tenanted, one to many manner. Upload your documents using the https://{{tenant}}-connectapi.{{domain}}.com/api/services/app/Document/Create service.

Note, the ublion end user interface has a built in file to base64 decoder.

Ublion will return an internal id when your upload a document. You can use this ID to find documents, processing states, etcetera.

The flow:

API Rate limit

The default API rate limit lets you upload 250 documents per hour, 1,000 documents per day, and 10,000 documents / month.

Name

Value

Method

Post

Content-type

Application/Json

Name

Document name as is should be displayed in the online portal /validation portal

File

Base64 encoded file string, max 1 MB (by default)

ID

Optional: your GUID /UUID. Ublion will auto-generate one if not provided. 

Document data unification

Ublion generates full, universal data sets from your uploaded documents. Regardless of the source, type, language, format, or size. Ublion validates on correctness and completeness by analyzing patterns and text. Extracted data /datasets are stored in an Ublion universal formats and can be reused for further processing. The universal format enables you to generate as many messages and compliant formats as needed.

By default the data retention is set to 7 days. 

Ublion sets timestamps to assure that every version of your dataset can be restored. The storage itself is extended with the tenant id when logged in. The prefix is set with the following endpoint: /api/services/app/Document/SetDocumentNodeIndex

Document processing states

You can use the document API service to get information about the document processing progress. A document has typically a state and a type. The state and type change automatically during the processing stages.

Note that the document states and types can be viewed and monitored from both the online portal /web interface and APIs. 

  • Document type: https://{{tenant}}-connectapi.{{domain}}.com/api/services/app/DocumentType/Create
  • Document state defines the current processing state: https://{{tenant}}-connectapi.{{domain}}.com/api/services/app/DocumentState/Create

Make a call to the https://{{tenant}}-connectapi.{{domain}}.com/api/services/app/Document/GetModifiedDocuments service if you want to monitor the processing progress of all your documents. The service will return all internal Ublion document ID’s with status that are changed since your last request.

Note: the internal Ublion document ID is returned to you when you used the /api/services/app/Document/Create service.

The steps which should be implemented are (example below is based on PDF invoice to UBL invoice conversion):

Document state

Service

Function

Input

Description

Document

GetAll

Get all invoice documents that you uploaded to Ublion.

Document

GetModifiedDocuments

StartDate(optional): DateTime

EndDate(optional): DateTime

Get the processing status of all documents since your last visit or within a period.

Document

Get

Guid: Id

Get a specific document that you uploaded to Ublion.

UBL

DownloadPDF

Guid: Id

Get a link to download the electronic invoice as PDF document, the UBL is mebedded. Note that the link is valid for only 1 minute

UBL

DownloadUBL

Guid: Id

Get a link to download the electronic invoice as UBL document, the PDF is embedded. Note that the link is valid for only 1 minute.

UBL

GetUblData

Guid: Id

Get the UBL data from a JSON file.

Document type

Abbreviation

Description

JSON example

New

A new document get’s the current state.

{ “iconClass”: “new”, “abbrevations”: “new”, “translations”: [ { “name”: “nl”, “language”: “Nieuw” }, { “name”: “en”, “language”: “New” } ] }

InProgress

The document is processed by Ublion

{ “iconClass”: “inProgress”, “abbrevations”: “inProgress”, “translations”: [ { “name”: “nl”, “language”: “Document wordt geanalyseerd” }, { “name”: “en”, “language”: “Document is processed” } ] }

NotValidated

The document is processed by Ublion but there are validations errors (data incompleteness, data incorrectness, document classficication, etcetera)

{ “iconClass”: “notValidated”, “abbrevations”: “notValidated”, “translations”: [ { “name”: “nl”, “language”: “Niet gevalideerd” }, { “name”: “en”, “language”: “Not validated” } ] }

Validated

The document is processed by Ublion and contains no erros; the entire document is processed successfully.

{ “iconClass”: “validated”, “abbrevations”: “validated”, “translations”: [ { “name”: “nl”, “language”: “Verwerkt en gevalideerd” }, { “name”: “en”, “language”: “Processed and validated” } ] }

Downloaded

The document is downloaded by user

{ “iconClass”: “downloaded”, “abbrevations”: “downloaded”, “translations”: [ { “name”: “nl”, “language”: “Gedownload” }, { “name”: “en”, “language”: “Downloaded” } ] }

InQueue

The document is waiting to be processed by Ublion

{ “iconClass”: “inQueue”, “abbrevations”: “inQueue”, “translations”: [ { “name”: “nl”, “language”: “Wachten op verwerking” }, { “name”: “en”, “language”: “Waiting for processing” } ] }

Get modified

File /message download

Download successful processed documents (state is validated) in any format you need for further processing. 

For example, download PDF invoices as UBL invoices through:

  • Use the service https://{{tenant}}-connectapi.{{domain}}.com/api/services/app/Ubl/DownloadPdf to download a generated PDF invoice with the UBL embedded
  • Use the https://{{tenant}}-connectapi.{{domain}}.com/api/services/app/Ubl/DownloadUbl to download a generated UBL file with the PDF invoice embedded
  • Use the https://{{tenant}}-connectapi.{{domain}}.com/api/services/app/Ubl/GetUblData to download a generated JSON file that contains the UBL data
    Ublion will return a link from where you can download the generated file. The link is valid for 1 minute.

Errors

We use ERROR 201 to indicate when errors occur. For some errors, the response will include an human readable error description. When the error is descriptive enough, the response body will be empty.