1. General

Using Smart Upload partners can allow users to upload documents either directly or via personalized links. In case of direct uploads, users are asked to enter the identification number. What the identification number looks like is up to the partner. It can be an insurance number, account number or any identifier that will let the partner uniquely identify the user. All documents uploaded by the user along with the extraction data can be provided to the partner in a number of possible ways(immediate transfer, nightly upload) using the protocol of their choosing, e.g. REST, SFTP etc. User’s identification number is transferred along with the data uploaded by the user.

If a partner uses personalized links, user identification number is already part of the url so the user does not need to provide additional info. Users can immediately start uploading documents.

Partners can use the API to retrieve the metadata of the uploaded documents and the extractions of each document.

1.1. Authentication

Basic authentication headers are expected for the partners that use personalized links. For basic auth, you need a valid client ID and a client secret. If you don’t have the client ID and the client secret already, please contact your sales representative.

1.2. Security

  • Smart upload generates a link using the token with a specified or default expiration date(24hours). Partner provides the link to the user outside smart upload, e.g. via encrypted email

  • Personalized link can be used by the user only to upload documents, not to view already uploaded documents

  • Smart upload keeps track of failed attempts using the link until it reaches a threshold (10 by default). After that threshold is reached, the link becomes invalid.

  • As a core backend infrastructure, smart upload relies on same services fuelling our main products, like Foto├╝berweisung. Data is stored on secure ISO-certified servers

  • Maximum document size allowed by Smart Upload is 50Mb

2.1. Request

Request headers

Name Description

Authorization

Basic auth credentials via client-id and client-secret

Request parameters

Parameter Description

user_identifier

Unique code identifying the user, e.g. Versicherungsnummer

expires_in_min

(Optional) Personalized link validity in minutes

2.2. Response

Path Type Description

userIdentifier

String

Unique code identifying the user, e.g. Versicherungsnummer

uploadLink

URI

Personilized link to be used by end user for uploading documents

createdAt

Date

Creation date of the personalized link

expiresAt

Date

Expiration date of the personalized link

2.3. Curl Sample Request

$ curl 'http://localhost:8080/partners/links/' -i -u 'super_client:super_partner' -X POST \
    -d 'user_identifier=versicherungsnummer_123&expires_in_min=15'

2.4. Sample Request

POST /partners/links/ HTTP/1.1
Authorization: Basic c3VwZXJfY2xpZW50OnN1cGVyX3BhcnRuZXI=
Host: localhost:8080
Content-Type: application/x-www-form-urlencoded

user_identifier=versicherungsnummer_123&expires_in_min=15

2.5. Sample Response

{
  "userIdentifier" : "versicherungsnummer_123",
  "uploadLink" : "http://localhost:8080/token/Tp7p1bhPo5Vg",
  "createdAt" : "2020-07-28 17:46:00",
  "expiresAt" : "2020-07-29 17:46:00"
}

3.1. Request

Request headers

Name Description

Authorization

Basic auth credentials via client-id and client-secret

Request parameters

Parameter Description

user_identifiers

Comma-separated list of unique codes identifying the users, e.g. Versicherungsnummer. If not provided, all personalized links of this partner are returned

3.2. Response

Path Type Description

[0].userIdentifier

String

Unique code identifying the user, e.g. Versicherungsnummer

[0].uploadLink

URI

Personilized link to be used by end user for uploading documents

[0].createdAt

Date

Creation date of the personalized link

[0].expiresAt

Date

Expiration date of the personalized link

[0].lastUpdatedAt

Date

Timestamp when the user last interacted with the personalized link. Empty if user has not yet accessed the link

[0].status

Enum

Internal status of the auth token. Possible values: GENERATED, VIEWED, TOKEN_VERIFIED, UPLOADED

3.3. Curl Sample Request

$ curl 'http://localhost:8080/partners/links/?user_identifiers=versicherungsnummer_123' -i -u 'super_client:super_partner' -X GET

3.4. Sample Request

GET /partners/links/?user_identifiers=versicherungsnummer_123 HTTP/1.1
Authorization: Basic c3VwZXJfY2xpZW50OnN1cGVyX3BhcnRuZXI=
Host: localhost:8080

3.5. Sample Response

[ {
  "userIdentifier" : "versicherungsnummer_123",
  "uploadLink" : "http://localhost:8080/token/Tp7p1bhPo5Vg",
  "createdAt" : "2020-07-28 17:46:00",
  "expiresAt" : "2020-07-29 17:46:00",
  "lastUpdatedAt" : "2020-07-29 12:46:00",
  "status" : "VIEWED"
} ]

4. Retrieve documents for the partner

4.1. Request

Request headers

Name Description

Authorization

Basic auth credentials via client-id and client-secret. Optional for partners without tokens

Request parameters

Parameter Description

partner

Name of the partner

user_identifier

(Optional) Unique code identifying the user, e.g. Versicherungsnummer

page

(Optional. Default 0) Page number for pagination

size

(Optional. Default 30) Number of documents to retrieve for the given page

4.2. Response

Path Type Description

[0].userIdentifier

String

Unique code identifying the user, e.g. Versicherungsnummer

[0].documents

list

List of documents belonging to this user identifier

[0].documents[].documentId

UUID

Expiration date of the personalized link

[0].documents[].status

Enum

Status of the document. Possible values: PENDING, VALID, INVALID, ERROR

[0].documents[].createdAt

Date

Document creation date

[0].documents[].extractionUri

URI

URI to the extractions of the given document

[0].documents[].message

String

(Optional) Error message in case status is error

4.3. Curl Sample Request

$ curl 'http://localhost:8080/partners/documents/?user_identifier=versicherungsnummer_123&partner=not_so_super_partner&page=5&size=100' -i -X GET

4.4. Sample Request

GET /partners/documents/?user_identifier=versicherungsnummer_123&partner=not_so_super_partner&page=5&size=100 HTTP/1.1
Host: localhost:8080

4.5. Sample Response

[ {
  "userIdentifier" : "versicherungsnummer_123",
  "documents" : [ {
    "documentId" : "ff4fc1ca-1ee2-471a-8c7f-6f1899c2327d",
    "status" : "VALID",
    "createdAt" : "2021-08-12 09:18:11",
    "extractionUri" : "http://localhost:8080/partners/extractions/vkb/?document_id=ff4fc1ca-1ee2-471a-8c7f-6f1899c2327d"
  } ]
} ]

5. Download document extractions as a partner

5.1. Request

Request headers

Name Description

Authorization

Basic auth credentials via client-id and client-secret. Optional for partners without tokens

Request parameters

Parameter Description

document_id

Id of the document to get extractions for

partner

Name of the partner

Response headers

Name Description

Content-Type

application/octet-stream

Content-Disposition

attachment; filename="docId123.json"

5.2. Response

Response contains the bytestream of the extractions json file

5.3. Curl Sample Request

$ curl 'http://localhost:8080/partners/extractions/?partner=super_partner&document_id=347ec9b2-f737-4f4c-a27a-33214021c25a' -i -u 'super_client:super_partner' -X GET

5.4. Sample Request

GET /partners/extractions/?partner=super_partner&document_id=347ec9b2-f737-4f4c-a27a-33214021c25a HTTP/1.1
Authorization: Basic c3VwZXJfY2xpZW50OnN1cGVyX3BhcnRuZXI=
Host: localhost:8080

6. Download document source as a partner

6.1. Request

Request headers

Name Description

Authorization

Basic auth credentials via client-id and client-secret. Optional for partners without tokens

Request parameters

Parameter Description

document_id

Id of the document to download source for

partner

Name of the partner

Response headers

Name Description

Content-Type

application/pdf

Content-Disposition

inline; filename="docId123.pdf"

6.2. Response

Response contains the bytestream of the processed pdf document

6.3. Curl Sample Request

$ curl 'http://localhost:8080/partners/source/?partner=super_partner&document_id=7242064c-3b9b-4a64-916d-96f920e8b03d' -i -u 'super_client:super_partner' -X GET

6.4. Sample Request

GET /partners/source/?partner=super_partner&document_id=7242064c-3b9b-4a64-916d-96f920e8b03d HTTP/1.1
Authorization: Basic c3VwZXJfY2xpZW50OnN1cGVyX3BhcnRuZXI=
Host: localhost:8080

7. Error handling

7.1. Error Response Fields

Path Type Description

status

String

Http status of the failed request

message

String

Description of the failure

timestamp

LocalDateTime

Response timestamp

7.2. Error Response Codes

Code Description

2xx

The request was successful.

4xx

The request was not successful. See the response body for details. Retrying with the same arguments will not work.

5xx

Some error occurred while processing the request. See the response body for possible details and try again.

7.3. Sample Error Response

{
  "status" : "INTERNAL_SERVER_ERROR",
  "message" : "Unexpected document state returned",
  "timestamp" : "2021-08-12 09:18:13"
}