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. Generate a personalized link
2.1. Request
Request headers
Name | Description |
---|---|
|
Basic auth credentials via client-id and client-secret |
Request parameters
Parameter | Description |
---|---|
|
Unique code identifying the user, e.g. Versicherungsnummer |
|
(Optional) Personalized link validity in minutes |
2.2. Response
Path | Type | Description |
---|---|---|
|
|
Unique code identifying the user, e.g. Versicherungsnummer |
|
|
Personilized link to be used by end user for uploading documents |
|
|
Creation date of the personalized link |
|
|
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. Retrieve personalized links
3.1. Request
Request headers
Name | Description |
---|---|
|
Basic auth credentials via client-id and client-secret |
Request parameters
Parameter | Description |
---|---|
|
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 |
---|---|---|
|
|
Unique code identifying the user, e.g. Versicherungsnummer |
|
|
Personilized link to be used by end user for uploading documents |
|
|
Creation date of the personalized link |
|
|
Expiration date of the personalized link |
|
|
Timestamp when the user last interacted with the personalized link. Empty if user has not yet accessed the link |
|
|
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 |
---|---|
|
Basic auth credentials via client-id and client-secret. Optional for partners without tokens |
Request parameters
Parameter | Description |
---|---|
|
Name of the partner |
|
(Optional) Unique code identifying the user, e.g. Versicherungsnummer |
|
(Optional. Default 0) Page number for pagination |
|
(Optional. Default 30) Number of documents to retrieve for the given page |
4.2. Response
Path | Type | Description |
---|---|---|
|
|
Unique code identifying the user, e.g. Versicherungsnummer |
|
|
List of documents belonging to this user identifier |
|
|
Expiration date of the personalized link |
|
|
Status of the document. Possible values: PENDING, VALID, INVALID, ERROR |
|
|
Document creation date |
|
|
URI to the extractions of the given document |
|
|
(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" : "3abfdc72-0030-474f-b1b7-7bb1c1869d5e",
"status" : "VALID",
"createdAt" : "2022-03-23 10:57:35",
"extractionUri" : "http://localhost:8080/partners/extractions/vkb/?document_id=3abfdc72-0030-474f-b1b7-7bb1c1869d5e"
} ]
} ]
5. Download document extractions as a partner
5.1. Request
Request headers
Name | Description |
---|---|
|
Basic auth credentials via client-id and client-secret. Optional for partners without tokens |
Request parameters
Parameter | Description |
---|---|
|
Id of the document to get extractions for |
|
Name of the partner |
Response headers
Name | Description |
---|---|
|
application/octet-stream |
|
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=728f4efa-f375-47d1-ae19-4f85b8fab119' -i -u 'super_client:super_partner' -X GET
5.4. Sample Request
GET /partners/extractions/?partner=super_partner&document_id=728f4efa-f375-47d1-ae19-4f85b8fab119 HTTP/1.1
Authorization: Basic c3VwZXJfY2xpZW50OnN1cGVyX3BhcnRuZXI=
Host: localhost:8080
6. Download document source as a partner
6.1. Request
Request headers
Name | Description |
---|---|
|
Basic auth credentials via client-id and client-secret. Optional for partners without tokens |
Request parameters
Parameter | Description |
---|---|
|
Id of the document to download source for |
|
Name of the partner |
Response headers
Name | Description |
---|---|
|
application/pdf |
|
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=03b6c928-6157-41b3-9b90-567c520cdb2d' -i -u 'super_client:super_partner' -X GET
6.4. Sample Request
GET /partners/source/?partner=super_partner&document_id=03b6c928-6157-41b3-9b90-567c520cdb2d HTTP/1.1
Authorization: Basic c3VwZXJfY2xpZW50OnN1cGVyX3BhcnRuZXI=
Host: localhost:8080
7. Error handling
7.1. Error Response Fields
Path | Type | Description |
---|---|---|
|
|
Http status of the failed request |
|
|
Description of the failure |
|
|
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" : "2022-03-23 10:57:33"
}