Overview

An easy-to-use portal for uploading documents

Components

HTTP verbs

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to replace an existing resource

PATCH

Used to update an existing resource, including partial updates

DELETE

Used to delete an existing resource

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

401 Unauthorized

The request is unauthorized

404 Not Found

The requested resource did not exist

Authentication and Authorization

Authorization header

Each api call should contain "Authorization" header. Example:

GET /v1/upload HTTP/1.1
Authorization: Bearer {JWT_ACCESS_TOKEN}
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_USER
Host: localhost:8080

JWT_ACCESS_TOKEN required for each call should be requested from Cognito identity provider. See https://docs.aws.amazon.com/cognito/latest/developerguide/authentication.html

Example login Request

POST https://cognito-idp.eu-central-1.amazonaws.com
Content-Type: application/x-amz-json-1.1
X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth

{
    "AuthParameters" : {
        "USERNAME": "Some@Email",
        "PASSWORD": "SecretPassword"
    },
    "AuthFlow": "USER_PASSWORD_AUTH",
    "ClientId": "<CLIENT_ID>"
}

CLIENT_ID can be provided by support team on request.

Example login response

HTTP/1.1 200 OK
Content-Type: application/x-amz-json-1.1
Content-Length: 4148

{
    "AuthenticationResult": {
        "AccessToken":"JWT_ACCESS_TOKEN",
        "ExpiresIn":3600,
        "IdToken":"JWT_ID_TOKEN",
        "RefreshToken":"JWT_REFRESH_TOKEN",
        "TokenType":"Bearer"
    },
    "ChallengeParameters":{}
}

Requester-Role header

Each api call should contain "X-PF-DWC-Requester-Role" header. Example:

GET /v1/upload HTTP/1.1
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_UPLOADER
Host: localhost:8080

Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:

Path Type Description

id

String

internal

status

String

The HTTP status code, e.g. 400

message

String

A description of the cause of the error, e.g. 'Validation error'

messageCode

String

Internal code of the cause of the error

debugMessages

Array

Extended description to the error, e.g. 'contractNumber: must not be blank'

path

String

The path to which the request was made

timestamp

String

The time, in milliseconds, at which the error occurred

For example, a request that attempts to apply a non-existent tag to a note will produce a 400 Bad Request response:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 293

{
  "id" : "b62a2fb5-1205-4fd3-b269-f70754059ad0",
  "status" : "BAD_REQUEST",
  "timestamp" : "2025-08-12T13:32:49.125030871Z",
  "message" : "Bad Request",
  "messageCode" : "de.profiforms.docxworld.upload.error.client.bad_request",
  "debugMessages" : [ null ],
  "path" : "/v1/something"
}

User

Register new user request

POST /v1/users HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 103
Host: localhost:8080

{"email":"email@email.com","firstName":"Max","lastName":"Musterman","companyId":null,"status":"ACTIVE"}

Request fields

Path Type Description Constraints

email

String

Login E-Mail of the user. Must be unique

Must be a well-formed email address. Must not be blank

status

UserStatus

User status. Allowed values: [ACTIVE, INACTIVE]. Default: ACTIVE

firstName

String

First name of the user

lastName

String

Last name of the user

companyId

UUID

Company-Id of the user

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 496

{
  "id" : "123",
  "firstName" : "Max",
  "lastName" : "Musterman",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "companyName",
  "email" : "email@email.com",
  "status" : "ACTIVE",
  "lastLogin" : "2007-12-03T10:15:30Z",
  "roles" : [ "ROLE_PF_ADMIN" ],
  "scopedCustomerContracts" : {
    "ROLE_PF_ADMIN" : [ {
      "number" : "customerNumber",
      "customerContracts" : [ {
        "number" : "customerContract"
      } ]
    } ]
  },
  "scopedTargets" : { }
}

Response fields

Path Type Description

id

String

User id

firstName

String

First name of the user

lastName

String

Last name of the user

email

String

Login E-Mail of the user

roles

Set<PublicRole>

Set of roles assigned to the user

status

UserStatus

User status

companyId

UUID

Company-Id of the user

companyName

String

Company-Name of the user

lastLogin

Instant

Last login of the user

scopedCustomerContracts

Map<PublicRole, Set<CustomerNumber>>

Scoped contracts for different roles

scopedTargets

Map<PublicRole, Set<UUID>>

Scoped targets for different roles

Get user request

GET /v1/users/{userId}
Parameter Description

userId

id of the user

Example request

GET /v1/users/123 HTTP/1.1
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 388

{
  "id" : "123",
  "firstName" : "firstName_123",
  "lastName" : "lastName_123",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "companyName",
  "email" : "123@profiforms.de",
  "status" : "ACTIVE",
  "lastLogin" : "2007-12-03T10:15:30Z",
  "roles" : [ "ROLE_PF_ADMIN" ],
  "scopedCustomerContracts" : {
    "ROLE_PF_ADMIN" : [ ]
  },
  "scopedTargets" : { }
}

List users request

GET /v1/users
Parameter Description

freeSearch

Filter and return users containing provided sequence in last name, first name or E-Mail. Case insensitive.

roles

Filter and return users assigned to provided roles. Allowed values: [ROLE_SYS_ADMIN, ROLE_PF_ADMIN, ROLE_CUSTOMER_ADMIN, ROLE_CUSTOMER_USER, ROLE_CUSTOMER_UPLOADER, ROLE_CUSTOMER_DOWNLOADER_RESULTS, ROLE_CUSTOMER_DOWNLOADER_REPORTS, ROLE_CUSTOMER_APPROVER] and special value ROLE_NO_ROLE for users not assigned to any role.

companyIds

Filter and return users assigned to provided companies. Special value SYS_COMPANY for users not assigned to any company.

page

Page number to return. [0,totalPages)

size

Page size. Default 35

sort

Sorting in format property[,property][,ASC|DESC]. Allowed values: [email, status]. Allowed direction: [ASC, DESC]. Default direction is ASC.

Example request

GET /v1/users?sort=email&sort=status%2CDESC&page=0&size=10&freeSearch=email&roles=ROLE_NO_ROLE&roles=ROLE_CUSTOMER_USER&companyIds=SYS_COMPANY&companyIds=00000000-0000-0000-0000-000000000001 HTTP/1.1
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 829

{
  "content" : [ {
    "id" : "123",
    "firstName" : "name1",
    "lastName" : "lastname",
    "companyId" : "00000000-0000-0000-0000-000000000001",
    "companyName" : "companyName",
    "email" : "email1",
    "status" : "ACTIVE",
    "lastLogin" : null,
    "roles" : [ ],
    "scopedCustomerContracts" : { },
    "scopedTargets" : { }
  }, {
    "id" : "456",
    "firstName" : "name2",
    "lastName" : "lastname",
    "companyId" : "00000000-0000-0000-0000-000000000001",
    "companyName" : "companyName",
    "email" : "email2",
    "status" : "ACTIVE",
    "lastLogin" : null,
    "roles" : [ ],
    "scopedCustomerContracts" : { },
    "scopedTargets" : { }
  } ],
  "totalElements" : 2,
  "totalPages" : 1,
  "last" : true,
  "first" : true,
  "numberOfElements" : 2,
  "size" : 35,
  "number" : 0,
  "sort" : [ ]
}

Update user request

PUT /v1/users/{userId}
Parameter Description

userId

id of the user

Request fields

Path Type Description Constraints

firstName

String

First name of the user

lastName

String

Last name of the user

Example request

PUT /v1/users/123 HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 42
Host: localhost:8080

{"firstName":"Max","lastName":"Musterman"}

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 373

{
  "id" : "123",
  "firstName" : "Max",
  "lastName" : "Musterman",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "companyName",
  "email" : "email@email.com",
  "status" : "ACTIVE",
  "lastLogin" : "2007-12-03T10:15:30Z",
  "roles" : [ "ROLE_PF_ADMIN" ],
  "scopedCustomerContracts" : {
    "ROLE_PF_ADMIN" : [ ]
  },
  "scopedTargets" : { }
}

Response fields

Path Type Description

id

String

User id

firstName

String

First name of the user

lastName

String

Last name of the user

email

String

Login E-Mail of the user

roles

Set<PublicRole>

Set of roles assigned to the user

status

UserStatus

User status

companyId

UUID

Company-Id of the user

companyName

String

Company-Name of the user

lastLogin

Instant

Last login of the user

scopedCustomerContracts

Map<PublicRole, Set<CustomerNumber>>

Scoped contracts for different roles

scopedTargets

Map<PublicRole, Set<UUID>>

Scoped targets for different roles

Set user state request

Status has to changed separately from other user metadata with following request

PUT /v1/users/{userId}/state
Parameter Description

userId

id of the user

Example request

PUT /v1/users/123/state HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 19
Host: localhost:8080

{"status":"ACTIVE"}

Request fields

Path Type Description Constraints

status

UserStatus

User status. Allowed values: [ACTIVE, INACTIVE]

Must not be null

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 373

{
  "id" : "123",
  "firstName" : "Max",
  "lastName" : "Musterman",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "companyName",
  "email" : "email@email.com",
  "status" : "ACTIVE",
  "lastLogin" : "2007-12-03T10:15:30Z",
  "roles" : [ "ROLE_PF_ADMIN" ],
  "scopedCustomerContracts" : {
    "ROLE_PF_ADMIN" : [ ]
  },
  "scopedTargets" : { }
}

Response fields

Path Type Description

id

String

User id

firstName

String

First name of the user

lastName

String

Last name of the user

email

String

Login E-Mail of the user

roles

Set<PublicRole>

Set of roles assigned to the user

status

UserStatus

User status

companyId

UUID

Company-Id of the user

companyName

String

Company-Name of the user

lastLogin

Instant

Last login of the user

scopedCustomerContracts

Map<PublicRole, Set<CustomerNumber>>

Scoped contracts for different roles

scopedTargets

Map<PublicRole, Set<UUID>>

Scoped targets for different roles

Assign role to user

PUT /v1/users/{userId}/roles
Parameter Description

userId

id of the user

Example request

PUT /v1/users/123/roles HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 24
Host: localhost:8080

{"role":"ROLE_PF_ADMIN"}

Request fields

Path Type Description Constraints

role

PublicRole

The role that is assigned to the user. Allowed values:: [ROLE_SYS_ADMIN, ROLE_PF_ADMIN, ROLE_CUSTOMER_ADMIN, ROLE_CUSTOMER_USER, ROLE_CUSTOMER_UPLOADER, ROLE_CUSTOMER_DOWNLOADER_RESULTS, ROLE_CUSTOMER_DOWNLOADER_REPORTS, ROLE_CUSTOMER_APPROVER]

Must not be null

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 373

{
  "id" : "123",
  "firstName" : "Max",
  "lastName" : "Musterman",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "companyName",
  "email" : "email@email.com",
  "status" : "ACTIVE",
  "lastLogin" : "2007-12-03T10:15:30Z",
  "roles" : [ "ROLE_PF_ADMIN" ],
  "scopedCustomerContracts" : {
    "ROLE_PF_ADMIN" : [ ]
  },
  "scopedTargets" : { }
}

Response fields

Path Type Description

id

String

User id

firstName

String

First name of the user

lastName

String

Last name of the user

email

String

Login E-Mail of the user

roles

Set<PublicRole>

Set of roles assigned to the user

status

UserStatus

User status

companyId

UUID

Company-Id of the user

companyName

String

Company-Name of the user

lastLogin

Instant

Last login of the user

scopedCustomerContracts

Map<PublicRole, Set<CustomerNumber>>

Scoped contracts for different roles

scopedTargets

Map<PublicRole, Set<UUID>>

Scoped targets for different roles

Retract role from user

DELETE /v1/users/{userId}/roles
Parameter Description

userId

id of the user

Example request

DELETE /v1/users/123/roles HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 24
Host: localhost:8080

{"role":"ROLE_PF_ADMIN"}

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 373

{
  "id" : "123",
  "firstName" : "Max",
  "lastName" : "Musterman",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "companyName",
  "email" : "email@email.com",
  "status" : "ACTIVE",
  "lastLogin" : "2007-12-03T10:15:30Z",
  "roles" : [ "ROLE_PF_ADMIN" ],
  "scopedCustomerContracts" : {
    "ROLE_PF_ADMIN" : [ ]
  },
  "scopedTargets" : { }
}

Response fields

Path Type Description

id

String

User id

firstName

String

First name of the user

lastName

String

Last name of the user

email

String

Login E-Mail of the user

roles

Set<PublicRole>

Set of roles assigned to the user

status

UserStatus

User status

companyId

UUID

Company-Id of the user

companyName

String

Company-Name of the user

lastLogin

Instant

Last login of the user

scopedCustomerContracts

Map<PublicRole, Set<CustomerNumber>>

Scoped contracts for different roles

scopedTargets

Map<PublicRole, Set<UUID>>

Scoped targets for different roles

Assign contracts to user role

PUT /v1/users/{userId}/customer-contracts
Parameter Description

userId

id of the user

Example request

PUT /v1/users/123/customer-contracts HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 62
Host: localhost:8080

{"customerContracts":["number1"],"targetRole":"ROLE_PF_ADMIN"}

Request fields

Path Type Description Constraints

targetRole

PublicRole

The role the contracts should be assigned to. Allowed values: [ROLE_PF_ADMIN, ROLE_CUSTOMER_ADMIN]

Must not be null

customerContracts

Set<String>

The contracts that should be assigned to role.

Must not be empty

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 373

{
  "id" : "123",
  "firstName" : "Max",
  "lastName" : "Musterman",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "companyName",
  "email" : "email@email.com",
  "status" : "ACTIVE",
  "lastLogin" : "2007-12-03T10:15:30Z",
  "roles" : [ "ROLE_PF_ADMIN" ],
  "scopedCustomerContracts" : {
    "ROLE_PF_ADMIN" : [ ]
  },
  "scopedTargets" : { }
}

Response fields

Path Type Description

id

String

User id

firstName

String

First name of the user

lastName

String

Last name of the user

email

String

Login E-Mail of the user

roles

Set<PublicRole>

Set of roles assigned to the user

status

UserStatus

User status

companyId

UUID

Company-Id of the user

companyName

String

Company-Name of the user

lastLogin

Instant

Last login of the user

scopedCustomerContracts

Map<PublicRole, Set<CustomerNumber>>

Scoped contracts for different roles

scopedTargets

Map<PublicRole, Set<UUID>>

Scoped targets for different roles

Remove contracts from user role

DELETE /v1/users/{userId}/customer-contracts
Parameter Description

userId

id of the user

Example request

DELETE /v1/users/123/customer-contracts HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 62
Host: localhost:8080

{"customerContracts":["number1"],"targetRole":"ROLE_PF_ADMIN"}

Request fields

Path Type Description Constraints

targetRole

PublicRole

The role from which the contracts should removed assigned from. Allowed values: [ROLE_PF_ADMIN, ROLE_CUSTOMER_ADMIN]

Must not be null

customerContracts

Set<String>

The contracts that should be removed from role.

Must not be empty

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 373

{
  "id" : "123",
  "firstName" : "Max",
  "lastName" : "Musterman",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "companyName",
  "email" : "email@email.com",
  "status" : "ACTIVE",
  "lastLogin" : "2007-12-03T10:15:30Z",
  "roles" : [ "ROLE_PF_ADMIN" ],
  "scopedCustomerContracts" : {
    "ROLE_PF_ADMIN" : [ ]
  },
  "scopedTargets" : { }
}

Response fields

Path Type Description

id

String

User id

firstName

String

First name of the user

lastName

String

Last name of the user

email

String

Login E-Mail of the user

roles

Set<PublicRole>

Set of roles assigned to the user

status

UserStatus

User status

companyId

UUID

Company-Id of the user

companyName

String

Company-Name of the user

lastLogin

Instant

Last login of the user

scopedCustomerContracts

Map<PublicRole, Set<CustomerNumber>>

Scoped contracts for different roles

scopedTargets

Map<PublicRole, Set<UUID>>

Scoped targets for different roles

Assign targets to user role

PUT /v1/users/{userId}/targets
Parameter Description

userId

id of the user

Example request

PUT /v1/users/123/targets HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 90
Host: localhost:8080

{"targets":["00000000-0000-0000-0000-000000000001"],"targetRole":"ROLE_CUSTOMER_UPLOADER"}

Request fields

Path Type Description Constraints

targetRole

PublicRole

The role the targets should be assigned to. Allowed values: [ROLE_CUSTOMER_UPLOADER, ROLE_CUSTOMER_DOWNLOADER_RESULTS, ROLE_CUSTOMER_DOWNLOADER_REPORTS, ROLE_CUSTOMER_APPROVER]

Must not be null

targets

Set<UUID>

The targets that should be assigned to role.

Must not be empty

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 373

{
  "id" : "123",
  "firstName" : "Max",
  "lastName" : "Musterman",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "companyName",
  "email" : "email@email.com",
  "status" : "ACTIVE",
  "lastLogin" : "2007-12-03T10:15:30Z",
  "roles" : [ "ROLE_PF_ADMIN" ],
  "scopedCustomerContracts" : {
    "ROLE_PF_ADMIN" : [ ]
  },
  "scopedTargets" : { }
}

Response fields

Path Type Description

id

String

User id

firstName

String

First name of the user

lastName

String

Last name of the user

email

String

Login E-Mail of the user

roles

Set<PublicRole>

Set of roles assigned to the user

status

UserStatus

User status

companyId

UUID

Company-Id of the user

companyName

String

Company-Name of the user

lastLogin

Instant

Last login of the user

scopedCustomerContracts

Map<PublicRole, Set<CustomerNumber>>

Scoped contracts for different roles

scopedTargets

Map<PublicRole, Set<UUID>>

Scoped targets for different roles

Remove targets from user role

DELETE /v1/users/{userId}/targets
Parameter Description

userId

id of the user

Example request

DELETE /v1/users/123/targets HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 90
Host: localhost:8080

{"targets":["00000000-0000-0000-0000-000000000001"],"targetRole":"ROLE_CUSTOMER_UPLOADER"}

Request fields

Path Type Description Constraints

targetRole

PublicRole

The role from which the targets should removed assigned from. Allowed values: [ROLE_CUSTOMER_UPLOADER, ROLE_CUSTOMER_DOWNLOADER_RESULTS, ROLE_CUSTOMER_DOWNLOADER_REPORTS, ROLE_CUSTOMER_APPROVER]

Must not be null

targets

Set<UUID>

The targets that should be removed from role.

Must not be empty

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 373

{
  "id" : "123",
  "firstName" : "Max",
  "lastName" : "Musterman",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "companyName",
  "email" : "email@email.com",
  "status" : "ACTIVE",
  "lastLogin" : "2007-12-03T10:15:30Z",
  "roles" : [ "ROLE_PF_ADMIN" ],
  "scopedCustomerContracts" : {
    "ROLE_PF_ADMIN" : [ ]
  },
  "scopedTargets" : { }
}

Response fields

Path Type Description

id

String

User id

firstName

String

First name of the user

lastName

String

Last name of the user

email

String

Login E-Mail of the user

roles

Set<PublicRole>

Set of roles assigned to the user

status

UserStatus

User status

companyId

UUID

Company-Id of the user

companyName

String

Company-Name of the user

lastLogin

Instant

Last login of the user

scopedCustomerContracts

Map<PublicRole, Set<CustomerNumber>>

Scoped contracts for different roles

scopedTargets

Map<PublicRole, Set<UUID>>

Scoped targets for different roles

Retrieve current user Roles and Grants

GET /v1/users/grants HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 424

[ {
  "role" : "ROLE_PF_ADMIN",
  "grants" : [ {
    "action" : "user:updateState"
  }, {
    "action" : "role:removeUser",
    "target" : "ROLE_PF_ADMIN"
  } ],
  "companies" : [ ".*" ],
  "contracts" : null
}, {
  "role" : "ROLE_SYS_ADMIN",
  "grants" : [ {
    "action" : "user:create"
  }, {
    "action" : "role:addUser",
    "target" : "ROLE_PF_ADMIN"
  } ],
  "companies" : [ "SYS_COMPANY" ],
  "contracts" : null
} ]

Response fields

Path Type Description

[].role

PublicRole

Role, user is assigned to

[].companies

List<String>

Companies scope, role is restricted to

[].contracts

List<String>

Contracts scope, role is restricted to

[].grants

List<Map<String, String>>

List of Grants assigned to the role

Reset user’s initial password

PUT /v1/users/{userId}/reset-initial-password
Parameter Description

userId

id of the user

Example request

PUT /v1/users/123/reset-initial-password HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 373

{
  "id" : "123",
  "firstName" : "Max",
  "lastName" : "Musterman",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "companyName",
  "email" : "email@email.com",
  "status" : "ACTIVE",
  "lastLogin" : "2007-12-03T10:15:30Z",
  "roles" : [ "ROLE_PF_ADMIN" ],
  "scopedCustomerContracts" : {
    "ROLE_PF_ADMIN" : [ ]
  },
  "scopedTargets" : { }
}

Known error codes

Code Description

de.profiforms.docxworld.connect.usermanagement.error.client.access_denied

Access denied

de.profiforms.docxworld.connect.usermanagement.error.client.company_not_exists

Company not exists exception

de.profiforms.docxworld.connect.usermanagement.error.client.error

Client error

de.profiforms.docxworld.connect.usermanagement.error.client.group_not_exists

Group not exists exception

de.profiforms.docxworld.connect.usermanagement.error.client.initial_password_reset_not_allowed

Initial password reset not allowed.

de.profiforms.docxworld.connect.usermanagement.error.client.invalid_parameter_exception

Invalid parameter exception.

de.profiforms.docxworld.connect.usermanagement.error.client.invalid_sort_argument

Invalid sort argument exception

de.profiforms.docxworld.connect.usermanagement.error.client.malformed_request

Malformed JSON request

de.profiforms.docxworld.connect.usermanagement.error.client.role_header_missing

Required request header is missing

de.profiforms.docxworld.connect.usermanagement.error.client.role_not_assignable

User can not be assigned to this role

de.profiforms.docxworld.connect.usermanagement.error.client.role_not_assigned

User has not assigned requested role

de.profiforms.docxworld.connect.usermanagement.error.client.role_not_exists

Public role not exists exception

de.profiforms.docxworld.connect.usermanagement.error.client.targets_not_approvable

Targets are not approvable

de.profiforms.docxworld.connect.usermanagement.error.client.user_already_exists

User already exists exception

de.profiforms.docxworld.connect.usermanagement.error.client.user_not_exists

User not exists exception

de.profiforms.docxworld.connect.usermanagement.error.client.validation

Validation error

de.profiforms.docxworld.connect.usermanagement.error.server.unexpected_internal

Unexpected internal error

Upload

Uploading a file can be either done by uploading the file as a whole (Single-Upload) or splitting the file in several chunks and uploading them in sequence or in parallel (Chunked-Upload).

Uploading files using Single-Upload consists of 2 stages

  • getting the presigned URL for uploading,

  • uploading the file to s3.

Uploading files using Chunked-Upload consists of 3 stages:

  • getting several presigned URLs for uploading,

  • uploading the file-chunks to s3,

  • confirming that the upload is complete.

In the process of requesting for S3-Upload URL, the client has to provide the information if Chunked-Upload is supported, however the decision if Single-Upload or Chunked-Upload will be used is made by the backend. Which kind of file-upload actually should be done is given in the response for requesting for S3-Upload URL, where either one single URL is included or a list of URLs, respectively. If Chunked-Upload is used, the client may decide by itself how to split the file into chunks, however only the last chunk may be smaller 5MB.

Getting upload URL

A PUT request is used to get upload URL

/v1/uploads

Request fields

Path Type Description Constraints

supportedUploadFeatures

List<UploadFeature>

Allowed values: MULTIPART - if the file is larger than 100 mb, you can get multiple urls to upload(chunk upload); CS_CONTENT_ENCRYPTION - if client-side encryption is used

contractNumber

String

The contract number. Deprecated. Use targetId. If set, no target my be given

targetId

UUID

The target-ID. If set, no contract number may be given.

referenceId

String

Reference Id. If specified, it must be unique for current user

Size must be between 0 and 100 inclusive

jobCustomerReference1

String

Customer reference id 1

Size must be between 0 and 100 inclusive

jobCustomerReference2

String

Customer reference id 2

Size must be between 0 and 100 inclusive

jobCustomerReference3

String

Customer reference id 3

Size must be between 0 and 100 inclusive

jobCustomerReference4

String

Customer reference id 4

Size must be between 0 and 100 inclusive

jobCustomerReference5

String

Customer reference id 5

Size must be between 0 and 100 inclusive

jobCustomerReference6

String

Customer reference id 6

Size must be between 0 and 100 inclusive

priority

JobPriority

Priority, allowed values: NORMAL, HI

fileName

String

File name

Must not be blank

fileSize

Long

File size in bytes

b64ClientWrapKey

String

The key to wrap the data encryption key in BASE64 format

clientWrapKeyEncryptionAlg

ClientWrapKeyEncryptionAlg

The algorithm of key to wrap the data encryption key, allowed values: RSA/ECB/OAEPWithSHA-256AndMGF1Padding

dataEncryptionAlgorithm

DataEncryptionAlg

Data encryption algorithm, allowed values: AES/GCM/NoPadding

dataKeyProviderType

DataKeyProviderType

Data encryption key provider, allowed values: DOCXWORLD - keys are generated and stored on the docxworld side; KMS - keys are generated and stored in aws KMS service

Example request

PUT /v1/uploads HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_UPLOADER
Content-Length: 992
Host: localhost:8080

{"supportedUploadFeatures":["MULTIPART","CS_CONTENT_ENCRYPTION"],"contractNumber":"1231231234","targetId":null,"referenceId":"2341234345","jobCustomerReference1":"custom ref 1","jobCustomerReference2":"custom ref 2","jobCustomerReference3":"custom ref 3","jobCustomerReference4":"custom ref 4","jobCustomerReference5":"custom ref 5","jobCustomerReference6":"custom ref 6","fileName":"test.txt","priority":"NORMAL","fileSize":100,"b64ClientWrapKey":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsLPIMhdi5953f1pgE732rcDFBvoDOFG8F6XPH3JF/3WLueyTcD8Ox7WG1gVgSmvc/Jp/nuOyRPhpqHcxnzNbjdtk95wm5+b+UF3lWQVCvWVnCYXg+XqoFLGbxsP3agveHQCPWEdh8Yv3SVKXylQIjbLaEBDpg8G5A9C6NtsfppN3OWvtI4Ccg3kuO0MT0b5vysJVkYx803UO9m0OrO0+md2U3t/WKJpgmvXFt/3Z5ZLPfTSYXVzeW3EduUqFY/l/XMnfsYufUozdHiemYdAvte4Ik60HpFIc+hnE2tHENVdy/dvdBpDfJeUeylIOVGuS7xcs0cjsSu4sMN6/UO2MJwIDAQAB","dataEncryptionAlgorithm":"AES/GCM/NoPadding","clientWrapKeyEncryptionAlg":"RSA/ECB/OAEPWithSHA-256AndMGF1Padding","dataKeyProviderType":"DOCXWORLD"}

Response fields

Path Type Description

id

String

Upload id

headers

Map<String, String>

Headers to specify when uploading a file to s3

uploadUrls

List<URL>

URLs for uploading the file

s3Key

String

S3 key

jobAlreadyExists

boolean

True - if upload with same reference id already exist

b64encryptedDataKey

String

Data encryption key wrapped with b64ClientWrapKey in BASE64 format

b64Iv

String

Initialization vector for data encryption

b64DataKey

String

Data encryption key in plain text

clientWrapKeyEncryptionAlg

ClientWrapKeyEncryptionAlg

Algorithm that should be used to wrap the data key

dataEncryptionAlgorithm

DataEncryptionAlg

Algorithm that should be used to encrypt the data

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2102

{
  "id" : "5c636c12-53de-44cb-a1e1-a22233253e1e",
  "headers" : { },
  "uploadUrls" : [ "https://dwc-upload-dev.s3.eu-central-1.amazonaws.com/a84397c4-fadd-4fb7-9145-7d580646cc86-filename?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20201216T133930Z&X-Amz-SignedHeaders=host%3Bx-amz-meta-contractnumber%3Bx-amz-meta-datakeyprovidertype%3Bx-amz-meta-id%3Bx-amz-meta-jobpriority%3Bx-amz-meta-userid%3Bx-amz-meta-x-amz-cek-alg%3Bx-amz-meta-x-amz-iv%3Bx-amz-meta-x-amz-key-v2%3Bx-amz-meta-x-amz-matdesc%3Bx-amz-meta-x-amz-tag-len%3Bx-amz-meta-x-amz-unencrypted-content-length%3Bx-amz-meta-x-amz-wrap-alg&X-Amz-Expires=3587&X-Amz-Credential=AKIAWSSDUUOI3B7IN4U3%2F20201216%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Signature=995c8d2ffb7b71c3779ad594e81c63f8a49186a928b817e30e076bd50f9b4c46", "https://dwc-upload-dev.s3.eu-central-1.amazonaws.com/a84397c4-fadd-4fb7-9145-7d580646cc86-filename?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20201216T133930Z&X-Amz-SignedHeaders=host%3Bx-amz-meta-contractnumber%3Bx-amz-meta-datakeyprovidertype%3Bx-amz-meta-id%3Bx-amz-meta-jobpriority%3Bx-amz-meta-userid%3Bx-amz-meta-x-amz-cek-alg%3Bx-amz-meta-x-amz-iv%3Bx-amz-meta-x-amz-key-v2%3Bx-amz-meta-x-amz-matdesc%3Bx-amz-meta-x-amz-tag-len%3Bx-amz-meta-x-amz-unencrypted-content-length%3Bx-amz-meta-x-amz-wrap-alg&X-Amz-Expires=3587&X-Amz-Credential=AKIAWSSDUUOI3B7IN4U3%2F20201216%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Signature=995c8d2ffb7b71c3779ad594e81c63f8a49186a928b817e30e076bd50f9b4c46" ],
  "s3Key" : "5c636c12-53de-44cb-a1e1-a22233253e1etest.txt",
  "jobAlreadyExists" : false,
  "b64encryptedDataKey" : "Wf3g36oyGNErkbo7i8XLQichSejA+X4SEe3dXdBi/qbFKKtv8BQUAuu5bKBSCAUOBiI1ac6aKhzlR/F23k7v4mYchBvpBDqryXNiztd1DinjHUntJa7FhfL4631BrXMBgXsh0TJP3O24n8h+Sfd9AoDxA0XjkxGPRaDfd3TbL0qxvUs1cX/nBqX/pvhx8bAwQCNO3cip3xw7quOVBRMp/fWpepHjfCaKw+3X5OFivDQipnXN+IGwP3pWq0KrPuI5UvOkcgv2mh7ZIg3bEHNLuNWAePewlWrjA9bdxLiRABFhtpuovp10+U8jjuK4wT39DvmY0wd4495ry8h+qf4EuQ==",
  "b64Iv" : "LSy3GLifoC7NiX46LhpVuQ==",
  "b64DataKey" : null,
  "clientWrapKeyEncryptionAlg" : null,
  "dataEncryptionAlgorithm" : "AES/GCM/NoPadding"
}

In the case of Single-Upload, the response will contain a set of headers, that have to be included as headers in the file-upload request to S3. For the Chunked-Upload, no headers have to be used.

CURL request

$ curl 'http://localhost:8080/v1/uploads' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF8' \
    -H 'X-PF-DWC-Requester-Role: ROLE_CUSTOMER_UPLOADER' \
    -d '{"supportedUploadFeatures":["MULTIPART","CS_CONTENT_ENCRYPTION"],"contractNumber":"1231231234","targetId":null,"referenceId":"2341234345","jobCustomerReference1":"custom ref 1","jobCustomerReference2":"custom ref 2","jobCustomerReference3":"custom ref 3","jobCustomerReference4":"custom ref 4","jobCustomerReference5":"custom ref 5","jobCustomerReference6":"custom ref 6","fileName":"test.txt","priority":"NORMAL","fileSize":100,"b64ClientWrapKey":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsLPIMhdi5953f1pgE732rcDFBvoDOFG8F6XPH3JF/3WLueyTcD8Ox7WG1gVgSmvc/Jp/nuOyRPhpqHcxnzNbjdtk95wm5+b+UF3lWQVCvWVnCYXg+XqoFLGbxsP3agveHQCPWEdh8Yv3SVKXylQIjbLaEBDpg8G5A9C6NtsfppN3OWvtI4Ccg3kuO0MT0b5vysJVkYx803UO9m0OrO0+md2U3t/WKJpgmvXFt/3Z5ZLPfTSYXVzeW3EduUqFY/l/XMnfsYufUozdHiemYdAvte4Ik60HpFIc+hnE2tHENVdy/dvdBpDfJeUeylIOVGuS7xcs0cjsSu4sMN6/UO2MJwIDAQAB","dataEncryptionAlgorithm":"AES/GCM/NoPadding","clientWrapKeyEncryptionAlg":"RSA/ECB/OAEPWithSHA-256AndMGF1Padding","dataKeyProviderType":"DOCXWORLD"}'

Completing upload

This request has only to be done, if Chunked-Upload is used. While uploading the file-chunks to S3, each response contains an 'ETag' header that has to be included in the complete upload request in a map consisting of the counter of URL used to upload as key and the 'ETag' as value.

A PUT request is used to complete upload

/v1/uploads/complete

Request fields

Path Type Description Constraints

processId

String

ID received when requesting the upload URL

Must not be blank

etags

Map<Integer, String>

eTags

Example request

PUT /v1/uploads/complete HTTP/1.1
Content-Type: application/json;charset=UTF8
Content-Length: 36
Host: localhost:8080

{"processId":"processId","etags":{}}

Response fields

Path Type Description

message

String

The message about the successful completion

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 44

{
  "message" : "complete upload response"
}

CURL request

$ curl 'http://localhost:8080/v1/uploads/complete' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF8' \
    -d '{"processId":"processId","etags":{}}'

Getting upload

/v1/uploads/{id}

Response fields

Path Type Description

processId

String

Upload id

created

Instant

Timestamp of upload

targetId

UUID

upload target

targetName

String

upload target name

targetAbbreviation

String

upload target abbreviation

referenceId

String

Reference-Id

jobCustomerReference1

String

Customer upload reference 1

jobCustomerReference2

String

Customer upload reference 2

jobCustomerReference3

String

Customer upload reference 3

jobCustomerReference4

String

Customer upload reference 4

jobCustomerReference5

String

Customer upload reference 5

jobCustomerReference6

String

Customer upload reference 6

fileSize

Long

Filesize

fileName

String

Filename

events

List<EventLogDto>

Progress of upload. Allowed Values [SCHEDULED, UPLOADED, TRANSFER_FAILED, TRANSFERRED, DUPLICATED, DELETED, WAITING_FOR_COLLECT, COLLECTED]

approvalState

ApprovalState

Approval-State. Allowed Values [REQUIRED, NOT_REQUIRED, WAITING_APPROVAL, APPROVED, REJECTED, EXPIRED]

approverId

String

Id of the approver

approverName

String

Name of the approver

approverEmail

String

EMail of the approver

customerContract

String

Contract number

userId

String

User id

companyId

UUID

Company id

idInSpooler

String

Id in spooler

customerNumber

String

Customer number

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1059

{
  "processId" : "processId",
  "created" : "2007-12-03T10:15:30Z",
  "targetId" : "16e7769c-0ce5-3de7-a39b-179deed0c396",
  "targetName" : "targetName",
  "targetAbbreviation" : "targetAbbreviation",
  "referenceId" : "referenceId",
  "jobCustomerReference1" : "jobCustomerReference1",
  "jobCustomerReference2" : "jobCustomerReference2",
  "jobCustomerReference3" : "jobCustomerReference3",
  "jobCustomerReference4" : "jobCustomerReference4",
  "jobCustomerReference5" : "jobCustomerReference5",
  "jobCustomerReference6" : "jobCustomerReference6",
  "fileSize" : 100,
  "fileName" : "fileName",
  "events" : [ {
    "created" : "2007-12-03T10:15:30Z",
    "action" : "SCHEDULED"
  }, {
    "created" : "2007-12-03T10:15:30Z",
    "action" : "UPLOADED"
  } ],
  "approvalState" : "NOT_REQUIRED",
  "approverId" : null,
  "approverName" : null,
  "approverEmail" : null,
  "userId" : "userId",
  "companyId" : "00000000-0000-0000-0000-111111111111",
  "customerContract" : "customerContract",
  "customerNumber" : "customerNumber",
  "idInSpooler" : null
}

CURL request

$ curl 'http://localhost:8080/v1/uploads/processId' -i -X GET \
    -H 'X-PF-DWC-Requester-Role: ROLE_PF_ADMIN'
/v1/uploads/{id}/generate-link

Response fields

Path Type Description

downloadLink

URL

Download link

id

String

Upload ID

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 65

{
  "id" : "processId",
  "downloadLink" : "https://s3.aws/123"
}

CURL request

$ curl 'http://localhost:8080/v1/uploads/processId/generate-link' -i -X GET \
    -H 'X-PF-DWC-Requester-Role: ROLE_CUSTOMER_UPLOADER'

Getting uploads

/v1/uploads

Filter and sort parameters

GET /v1/uploads
Parameter Description

page

Page number to return.

size

Page size. Default 35

sort

Sorting in format [property][,ASC|DESC]. Allowed values: [customerContract, jobState, created, companyId, customerNumber, targetName, targetId, approvalState]. Allowed direction: [ASC, DESC]. Default direction is ASC.

companyId

Filter by company-id

customerNumber

Filter by customer number

jobState

Filter by job state. Allowed values [SCHEDULED, UPLOADED, TRANSFER_FAILED, TRANSFERRED, DUPLICATED, DELETED, WAITING_FOR_COLLECT, COLLECTED]

expectedFileFormat

Filter by expected-file-format. Allowed values [PDF, UNKNOWN]

startPeriod

Filter by created date: uploads created after the specified date

endPeriod

Filter by created date: uploads created before the specified date

Example request

GET /v1/uploads?sort=jobState%2CDESC&sort=customerContract&page=0&size=10&jobState=DUPLICATED&startPeriod=2000-12-24T09%3A38%3A40.982Z&endPeriod=2100-12-24T09%3A38%3A40.982Z&expectedFileFormat=PDF HTTP/1.1
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_UPLOADER
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1317

{
  "content" : [ {
    "processId" : "jobId",
    "referenceId" : "referenceId",
    "jobState" : "DUPLICATED",
    "created" : "2007-12-03T10:15:30Z",
    "fileName" : "fileName",
    "targetId" : "16e7769c-0ce5-3de7-a39b-179deed0c396",
    "targetName" : "targetName",
    "targetAbbreviation" : "targetAbbreviation",
    "expectedFileFormat" : "UNKNOWN",
    "pdfValidationState" : "NOT_REQUIRED",
    "approvalState" : "NOT_REQUIRED",
    "approverId" : null,
    "approverName" : null,
    "approverEmail" : null,
    "downloadable" : false,
    "hasApprovalTaskMessage" : false
  }, {
    "processId" : "jobId2",
    "referenceId" : "referenceId2",
    "jobState" : "DUPLICATED",
    "created" : "2007-12-03T10:15:30Z",
    "fileName" : "fileName2",
    "targetId" : "16e7769c-0ce5-3de7-a39b-179deed0c396",
    "targetName" : "targetName",
    "targetAbbreviation" : "targetAbbreviation",
    "expectedFileFormat" : "UNKNOWN",
    "pdfValidationState" : "NOT_REQUIRED",
    "approvalState" : "NOT_REQUIRED",
    "approverId" : null,
    "approverName" : null,
    "approverEmail" : null,
    "downloadable" : false,
    "hasApprovalTaskMessage" : false
  } ],
  "totalElements" : 2,
  "totalPages" : 1,
  "last" : true,
  "first" : true,
  "numberOfElements" : 2,
  "size" : 2,
  "number" : 0,
  "sort" : [ ]
}

Response fields

Path Type Description

content[].processId

String

Upload id

content[].created

Instant

Timestamp of upload

content[].targetId

UUID

upload target

content[].targetName

String

upload target name

content[].targetAbbreviation

String

upload target abbreviation

content[].referenceId

String

Reference-Id

content[].fileName

String

Filename

content[].jobState

JobState

Job-State. Allowed Values [SCHEDULED, UPLOADED, TRANSFER_FAILED, TRANSFERRED, DUPLICATED, DELETED, WAITING_FOR_COLLECT, COLLECTED]

content[].approvalState

ApprovalState

Approval-State. Allowed Values [REQUIRED, NOT_REQUIRED, WAITING_APPROVAL, APPROVED, REJECTED, EXPIRED]

content[].approverId

String

Id of the approver

content[].approverName

String

Name of the approver

content[].approverEmail

String

EMail of the approver

content[].pdfValidationState

PdfValidationState

PDF-Validation-State. Allowed Values [NOT_REQUIRED, WAITING_VALIDATION, VALIDATED, REJECTED]

content[].expectedFileFormat

FileFormat

Expected File-Format. Allowed Values [PDF, UNKNOWN]

content[].downloadable

boolean

File downloadable?

content[].hasApprovalTaskMessage

boolean

Approval-Task message provided?

CURL request

$ curl 'http://localhost:8080/v1/uploads?sort=jobState%2CDESC&sort=customerContract&page=0&size=10&jobState=DUPLICATED&startPeriod=2000-12-24T09%3A38%3A40.982Z&endPeriod=2100-12-24T09%3A38%3A40.982Z&expectedFileFormat=PDF' -i -X GET \
    -H 'X-PF-DWC-Requester-Role: ROLE_CUSTOMER_UPLOADER'

Getting approval-tasks

/v1/approval-tasks

Filter and sort parameters

GET /v1/approval-tasks
Parameter Description

page

Page number to return.

size

Page size. Default 35

sort

Sorting in format [property][,ASC|DESC]. Allowed values: [approvalState, uploadCreated, targetName, uploaderName]. Allowed direction: [ASC, DESC]. Default direction is ASC.

targetName

Name of workflow/target

processIds

Filter by process ids

approvalStates

Filter by approval state. Allowed values [REQUIRED, NOT_REQUIRED, WAITING_APPROVAL, APPROVED, REJECTED, EXPIRED]

freeSearch

Filter by free search of filename or uploaderName

Example request

GET /v1/approval-tasks?sort=approvalState%2CDESC&sort=uploadCreated%2CASC&page=1&size=5&targetName=targetName&approvalStates=WAITING_APPROVAL&approvalStates=APPROVED&freeSearch=free HTTP/1.1
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_APPROVER
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1322

{
  "content" : [ {
    "targetName" : "targetName",
    "targetId" : "16e7769c-0ce5-3de7-a39b-179deed0c396",
    "processId" : "processId1",
    "id" : "00000000-0000-0000-0000-000000000001",
    "uploadCreated" : "2007-12-03T10:15:30Z",
    "fileName" : "fileName",
    "approvalState" : "WAITING_APPROVAL",
    "uploaderName" : "uploaderFirstName uploaderLastName",
    "uploaderId" : "uploader",
    "uploaderEmail" : "uploaderEmail",
    "approverName" : "approverFirstName approverLastName",
    "approverId" : "approver",
    "approverEmail" : "approverEmail",
    "message" : null
  }, {
    "targetName" : "targetName",
    "targetId" : "16e7769c-0ce5-3de7-a39b-179deed0c396",
    "processId" : "processId2",
    "id" : "00000000-0000-0000-0000-000000000001",
    "uploadCreated" : "2007-12-03T10:15:30Z",
    "fileName" : "fileName",
    "approvalState" : "WAITING_APPROVAL",
    "uploaderName" : "uploaderFirstName uploaderLastName",
    "uploaderId" : "uploader",
    "uploaderEmail" : "uploaderEmail",
    "approverName" : "approverFirstName approverLastName",
    "approverId" : "approver",
    "approverEmail" : "approverEmail",
    "message" : null
  } ],
  "totalElements" : 2,
  "totalPages" : 1,
  "last" : true,
  "first" : true,
  "numberOfElements" : 2,
  "size" : 2,
  "number" : 0,
  "sort" : [ ]
}

Response fields

Path Type Description

content[].id

UUID

id of the approval task

content[].processId

Unknown

upload id

content[].targetId

Unknown

upload target id

content[].uploadCreated

Unknown

Timestamp of upload

content[].targetName

Unknown

upload target name

content[].fileName

Unknown

Filename

content[].uploaderId

Unknown

Uploader ID

content[].uploaderEmail

Unknown

Email of the Uploader

content[].approverId

Unknown

Approver ID

content[].approverEmail

Unknown

Email of the Approver

content[].approverName

Unknown

Name of the Approver

content[].uploaderName

Unknown

Name of the Uploader

content[].approvalState

ApprovalState

Approval-State. Allowed Values [REQUIRED, NOT_REQUIRED, WAITING_APPROVAL, APPROVED, REJECTED, EXPIRED]

content[].message

String

Approval message

CURL request

$ curl 'http://localhost:8080/v1/approval-tasks?sort=approvalState%2CDESC&sort=uploadCreated%2CASC&page=1&size=5&targetName=targetName&approvalStates=WAITING_APPROVAL&approvalStates=APPROVED&freeSearch=free' -i -X GET \
    -H 'X-PF-DWC-Requester-Role: ROLE_CUSTOMER_APPROVER'

Approve approval-tasks

/v1/approval-tasks/{id}/decide

Multipart post request is used to approve approval-tasks. Parts of the request are:

Part Description

file

The modified PDF to be processed

decision

The approval decision json

Decision fields are:

Path Type Description Constraints

approvalState

DecisionApprovalState

Result of the approval. Allowed values: [APPROVED, REJECTED]

Must not be null

message

String

The approval message

Size must be between 0 and 255 inclusive

emailOptions

EmailOption

An Email notification Option. By default: ONLY_UPLOADER. Allowed values: [ONLY_UPLOADER, CC_APPROVER]

Example request

POST /v1/approval-tasks/00000000-0000-0000-0000-000000000000/decide HTTP/1.1
Content-Type: multipart/form-data;charset=UTF8; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_APPROVER
Host: localhost:8080

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=file; filename=test.pdf
Content-Type: application/pdf

Default PDF content
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=decision; filename=decision.json
Content-Type: application/json

{"approvalState":"REJECTED","message":"message","emailOptions":"CC_APPROVER"}
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 535

{
  "targetName" : "targetName",
  "targetId" : "00000000-0000-0000-0000-000000000001",
  "processId" : "processId",
  "id" : "00000000-0000-0000-0000-000000000000",
  "uploadCreated" : "2007-12-03T10:15:30Z",
  "fileName" : "fileName",
  "approvalState" : "REJECTED",
  "uploaderName" : "uploaderFirstName uploaderLastName",
  "uploaderId" : "uploader",
  "uploaderEmail" : "uploaderEmail",
  "approverName" : "approverFirstName approverLastName",
  "approverId" : "approver",
  "approverEmail" : "approverEmail",
  "message" : null
}

Response fields

Path Type Description

id

UUID

id of the approval task

processId

Unknown

upload id

targetId

Unknown

upload target id

uploadCreated

Unknown

Timestamp of upload

targetName

Unknown

upload target name

fileName

Unknown

Filename

uploaderId

Unknown

Uploader ID

uploaderEmail

Unknown

Email of the Uploader

uploaderName

Unknown

Name of the Uploader

approverName

Unknown

Name of the Approver

approverId

Unknown

Approver ID

approverEmail

Unknown

Email of the Approver

approvalState

ApprovalState

Approval-State. Allowed Values [REQUIRED, NOT_REQUIRED, WAITING_APPROVAL, APPROVED, REJECTED, EXPIRED]

message

String

Approval message

CURL request

$ curl 'http://localhost:8080/v1/approval-tasks/00000000-0000-0000-0000-000000000000/decide' -i -X POST \
    -H 'Content-Type: multipart/form-data;charset=UTF8' \
    -H 'X-PF-DWC-Requester-Role: ROLE_CUSTOMER_APPROVER' \
    -F 'file=@test.pdf;type=application/pdf' \
    -F 'decision=@decision.json;type=application/json'

Known error codes

Code Description

de.profiforms.docxworld.upload.error.client.access_denied

Access denied

de.profiforms.docxworld.upload.error.client.bad_request

Bad Request

de.profiforms.docxworld.upload.error.client.chunk_missing

Cannot complete upload. Chunks are missing

de.profiforms.docxworld.upload.error.client.customer_contract_inactive

Customer contract is not active exception

de.profiforms.docxworld.upload.error.client.customer_contract_not_exists

Customer contract not exists exception

de.profiforms.docxworld.upload.error.client.customer_number_inactive

Customer number is not active exception

de.profiforms.docxworld.upload.error.client.encryption_not_allowed

Encryption not allowed exception

de.profiforms.docxworld.upload.error.client.encryption_parameters_missing

Incomplete set of data for encryption data key

de.profiforms.docxworld.upload.error.client.invalid_sort_argument

Invalid sort argument exception

de.profiforms.docxworld.upload.error.client.job_already_exists

Job already exists exception

de.profiforms.docxworld.upload.error.client.job_not_found

Job not exists exception

de.profiforms.docxworld.upload.error.client.malformed_request

Malformed request

de.profiforms.docxworld.upload.error.client.s3_complete_upload

Cannot complete upload.

de.profiforms.docxworld.upload.error.client.s3_key_not_found

Job not exists exception

de.profiforms.docxworld.upload.error.client.target_inactive

Target inactive exception

de.profiforms.docxworld.upload.error.client.target_not_exists

Target not exists exception

de.profiforms.docxworld.upload.error.client.unauthorized

Unauthorized access error.

de.profiforms.docxworld.upload.error.client.user_not_found

User not found

de.profiforms.docxworld.upload.error.client.validation

Validation error

de.profiforms.docxworld.upload.error.server.approval_task_not_decidable

Approval task not decidable exception

de.profiforms.docxworld.upload.error.server.approval_task_not_found

Approval task not exists exception

de.profiforms.docxworld.upload.error.server.file_not_downloadable

File not downloadable

de.profiforms.docxworld.upload.error.server.file_not_exists

File not exists

de.profiforms.docxworld.upload.error.server.job_collection_not_found

Job collection not exists exception

de.profiforms.docxworld.upload.error.server.no_such_client_key_encr_algorithm

No such key encryption algorithm

de.profiforms.docxworld.upload.error.server.no_such_data_encr_algorithm

No such data encryption algorithm

de.profiforms.docxworld.upload.error.server.unexpected_internal

Unexpected internal error

Company

Get company by ID

GET /v1/companies/00000000-0000-0000-0000-000000000001 HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 909

{
  "id" : "00000000-0000-0000-0000-000000000001",
  "version" : 0,
  "name" : "Company Name",
  "customerNumbers" : [ {
    "number" : "customerNumber-1",
    "version" : 0,
    "states" : [ {
      "state" : "ACTIVE",
      "validFrom" : "2121-01-31T11:22:33.456Z"
    }, {
      "state" : "INACTIVE",
      "validFrom" : "2121-02-01T11:22:33.456Z"
    } ],
    "customerContracts" : [ {
      "number" : "customerContract-2",
      "version" : 0,
      "description" : "customerContract-2 description",
      "states" : [ {
        "state" : "ACTIVE",
        "validFrom" : "2121-01-31T11:22:33.456Z"
      }, {
        "state" : "INACTIVE",
        "validFrom" : "2121-02-01T11:22:33.456Z"
      } ],
      "approvable" : false,
      "collectable" : false,
      "outputType" : "DW24",
      "fileType" : "PDF",
      "uploadType" : "JOB",
      "isActive" : false
    } ],
    "isActive" : false
  } ]
}

Read companies

GET /v1/companies HTTP/1.1
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 5998

{
  "content" : [ {
    "id" : "00000000-0000-0000-0000-000000000001",
    "version" : null,
    "name" : "Company Name",
    "customerNumbers" : [ {
      "number" : "customerNumber-1",
      "version" : null,
      "states" : [ {
        "state" : "ACTIVE",
        "validFrom" : "2121-01-31T11:22:33.456Z"
      }, {
        "state" : "INACTIVE",
        "validFrom" : "2121-02-01T11:22:33.456Z"
      } ],
      "customerContracts" : [ {
        "number" : "customerContract-1-1",
        "version" : null,
        "description" : "customerContract-1-1 description",
        "states" : [ {
          "state" : "ACTIVE",
          "validFrom" : "2121-01-31T11:22:33.456Z"
        }, {
          "state" : "INACTIVE",
          "validFrom" : "2121-02-01T11:22:33.456Z"
        } ],
        "approvable" : false,
        "collectable" : false,
        "outputType" : "DW24",
        "fileType" : "PDF",
        "uploadType" : "JOB",
        "isActive" : false
      }, {
        "number" : "customerContract-1-2",
        "version" : null,
        "description" : "customerContract-1-2 description",
        "states" : [ {
          "state" : "ACTIVE",
          "validFrom" : "2121-01-31T11:22:33.456Z"
        }, {
          "state" : "INACTIVE",
          "validFrom" : "2121-02-01T11:22:33.456Z"
        } ],
        "approvable" : false,
        "collectable" : false,
        "outputType" : "DW24",
        "fileType" : "RAW",
        "uploadType" : "SINGLE",
        "isActive" : false
      } ],
      "isActive" : false
    }, {
      "number" : "customerNumber-2",
      "version" : null,
      "states" : [ {
        "state" : "ACTIVE",
        "validFrom" : "2121-01-31T11:22:33.456Z"
      }, {
        "state" : "INACTIVE",
        "validFrom" : "2121-02-01T11:22:33.456Z"
      } ],
      "customerContracts" : [ {
        "number" : "customerContract-2-1",
        "version" : null,
        "description" : "customerContract-2-1 description",
        "states" : [ {
          "state" : "ACTIVE",
          "validFrom" : "2121-01-31T11:22:33.456Z"
        }, {
          "state" : "INACTIVE",
          "validFrom" : "2121-02-01T11:22:33.456Z"
        } ],
        "approvable" : false,
        "collectable" : false,
        "outputType" : "DW24",
        "fileType" : "PDF",
        "uploadType" : "JOB",
        "isActive" : false
      }, {
        "number" : "customerContract-2-2",
        "version" : null,
        "description" : "customerContract-2-2 description",
        "states" : [ {
          "state" : "ACTIVE",
          "validFrom" : "2121-01-31T11:22:33.456Z"
        }, {
          "state" : "INACTIVE",
          "validFrom" : "2121-02-01T11:22:33.456Z"
        } ],
        "approvable" : false,
        "collectable" : false,
        "outputType" : "DW24",
        "fileType" : "RAW",
        "uploadType" : "SINGLE",
        "isActive" : false
      } ],
      "isActive" : false
    } ]
  }, {
    "id" : "00000000-0000-0000-0000-000000000001",
    "version" : null,
    "name" : "Company Name",
    "customerNumbers" : [ {
      "number" : "customerNumber-1",
      "version" : null,
      "states" : [ {
        "state" : "ACTIVE",
        "validFrom" : "2121-01-31T11:22:33.456Z"
      }, {
        "state" : "INACTIVE",
        "validFrom" : "2121-02-01T11:22:33.456Z"
      } ],
      "customerContracts" : [ {
        "number" : "customerContract-1-1",
        "version" : null,
        "description" : "customerContract-1-1 description",
        "states" : [ {
          "state" : "ACTIVE",
          "validFrom" : "2121-01-31T11:22:33.456Z"
        }, {
          "state" : "INACTIVE",
          "validFrom" : "2121-02-01T11:22:33.456Z"
        } ],
        "approvable" : false,
        "collectable" : false,
        "outputType" : "DW24",
        "fileType" : "PDF",
        "uploadType" : "JOB",
        "isActive" : false
      }, {
        "number" : "customerContract-1-2",
        "version" : null,
        "description" : "customerContract-1-2 description",
        "states" : [ {
          "state" : "ACTIVE",
          "validFrom" : "2121-01-31T11:22:33.456Z"
        }, {
          "state" : "INACTIVE",
          "validFrom" : "2121-02-01T11:22:33.456Z"
        } ],
        "approvable" : false,
        "collectable" : false,
        "outputType" : "DW24",
        "fileType" : "RAW",
        "uploadType" : "SINGLE",
        "isActive" : false
      } ],
      "isActive" : false
    }, {
      "number" : "customerNumber-2",
      "version" : null,
      "states" : [ {
        "state" : "ACTIVE",
        "validFrom" : "2121-01-31T11:22:33.456Z"
      }, {
        "state" : "INACTIVE",
        "validFrom" : "2121-02-01T11:22:33.456Z"
      } ],
      "customerContracts" : [ {
        "number" : "customerContract-2-1",
        "version" : null,
        "description" : "customerContract-2-1 description",
        "states" : [ {
          "state" : "ACTIVE",
          "validFrom" : "2121-01-31T11:22:33.456Z"
        }, {
          "state" : "INACTIVE",
          "validFrom" : "2121-02-01T11:22:33.456Z"
        } ],
        "approvable" : false,
        "collectable" : false,
        "outputType" : "DW24",
        "fileType" : "PDF",
        "uploadType" : "JOB",
        "isActive" : false
      }, {
        "number" : "customerContract-2-2",
        "version" : null,
        "description" : "customerContract-2-2 description",
        "states" : [ {
          "state" : "ACTIVE",
          "validFrom" : "2121-01-31T11:22:33.456Z"
        }, {
          "state" : "INACTIVE",
          "validFrom" : "2121-02-01T11:22:33.456Z"
        } ],
        "approvable" : false,
        "collectable" : false,
        "outputType" : "DW24",
        "fileType" : "RAW",
        "uploadType" : "SINGLE",
        "isActive" : false
      } ],
      "isActive" : false
    } ]
  } ],
  "totalElements" : 2,
  "totalPages" : 1,
  "last" : true,
  "first" : true,
  "numberOfElements" : 2,
  "size" : 2,
  "number" : 0,
  "sort" : [ ]
}

Example. Read companies with filter

GET /v1/companies?freeSearch=123&page=0&size=5 HTTP/1.1
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Host: localhost:8080

Register new company request

POST /v1/companies HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 753
Host: localhost:8080

{
  "name" : "Company Name",
  "customerNumbers" : [ {
    "number" : "customerNumber-1",
    "states" : [ {
      "state" : "ACTIVE",
      "validFrom" : "2121-01-31T11:22:33.456Z"
    }, {
      "state" : "INACTIVE",
      "validFrom" : "2121-02-01T11:22:33.456Z"
    } ],
    "customerContracts" : [ {
      "number" : "customerContract-2",
      "description" : "customerContract-2 description",
      "states" : [ {
        "state" : "INACTIVE",
        "validFrom" : "2121-02-01T11:22:33.456Z"
      }, {
        "state" : "ACTIVE",
        "validFrom" : "2121-01-31T11:22:33.456Z"
      } ],
      "approvable" : false,
      "collectable" : false,
      "outputType" : "DW24",
      "fileType" : "PDF",
      "uploadType" : "JOB"
    } ]
  } ]
}

Request fields

Path Type Description Constraints

name

String

Company name. Must be unique(case insensitive)

Must not be blank

customerNumbers

Set<CustomerNumberCreateRequest>

Array of customer numbers, assigned to this company

Must not be empty. Must not contain objects with the same numbers

customerNumbers[].number

String

Customer number. Must be unique(case insensitive)

customerNumbers[].states

List<CustomerNumberStateTransitionDto>

Array of customer number state transitions.

customerNumbers[].customerContracts

List<CustomerContractResponse>

Array of customer contracts, assigned to particular customer number

customerNumbers[].states[].state

CustomerContractState

Customer number state. Allowed values: [ACTIVE, INACTIVE]. By default INACTIVE

Must not be null

customerNumbers[].states[].validFrom

Instant

Customer number state activation timestamp. By default current time

Must be in the future or the present within leeway. Must not be null

customerNumbers[].customerContracts[].number

String

Customer contract number. Must be unique(case insensitive)

customerNumbers[].customerContracts[].description

String

Customer contract number description

customerNumbers[].customerContracts[].states

List<CustomerContractStateTransitionDto>

Array of customer contract state transitions.

customerNumbers[].customerContracts[].approvable

boolean

Uploads approvable?

customerNumbers[].customerContracts[].collectable

boolean

Uploads collectable?

customerNumbers[].customerContracts[].outputType

CustomerContractOutputType

OutputType of upload. Allowed values: [DW24, EXTERNAL_OUTPUT, TRANSFER_TO_DOWNLOAD_SERVICE]

customerNumbers[].customerContracts[].fileType

FileType

FileType of upload. Allowed values: [PDF, RAW]

customerNumbers[].customerContracts[].uploadType

UploadType

UploadType of upload. Allowed values: [JOB, SINGLE]

customerNumbers[].customerContracts[].states[].state

CustomerContractState

Customer contract state. Allowed values: [ACTIVE, INACTIVE]. By default INACTIVE

Must not be null

customerNumbers[].customerContracts[].states[].validFrom

Instant

Customer contract state activation timestamp. By default current time

Must be in the future or the present within leeway. Must not be null

Example response

HTTP/1.1 201 Created
Location: http://localhost:8080/v1/companies/00000000-0000-0000-0000-000000000001
Content-Type: application/json
Content-Length: 909

{
  "id" : "00000000-0000-0000-0000-000000000001",
  "version" : 0,
  "name" : "Company Name",
  "customerNumbers" : [ {
    "number" : "customerNumber-1",
    "version" : 0,
    "states" : [ {
      "state" : "ACTIVE",
      "validFrom" : "2121-01-31T11:22:33.456Z"
    }, {
      "state" : "INACTIVE",
      "validFrom" : "2121-02-01T11:22:33.456Z"
    } ],
    "customerContracts" : [ {
      "number" : "customerContract-2",
      "version" : 0,
      "description" : "customerContract-2 description",
      "states" : [ {
        "state" : "ACTIVE",
        "validFrom" : "2121-01-31T11:22:33.456Z"
      }, {
        "state" : "INACTIVE",
        "validFrom" : "2121-02-01T11:22:33.456Z"
      } ],
      "approvable" : false,
      "collectable" : false,
      "outputType" : "DW24",
      "fileType" : "PDF",
      "uploadType" : "JOB",
      "isActive" : false
    } ],
    "isActive" : false
  } ]
}

Response fields

Path Type Description

id

UUID

Company id

name

String

Company name

version

Integer

Company revision. Changes to company will change it revision

customerNumbers

List<CustomerNumberResponse>

Array of customer numbers, assigned to this company

customerNumbers[].number

String

Customer number. Must be unique(case insensitive)

customerNumbers[].states

List<CustomerNumberStateTransitionDto>

Array of customer number state transitions. By default INACTIVE

customerNumbers[].version

Integer

Customer number revision. Changes to customer number will change it revision

customerNumbers[].isActive

boolean

True, if customerNumber is currently active

customerNumbers[].states[].state

CustomerNumberState

Customer number state. Allowed values: [ACTIVE, INACTIVE]

customerNumbers[].states[].validFrom

Instant

Customer number state activation timestamp. By default current time

customerNumbers[].customerContracts

List<CustomerContractResponse>

Array of customer contracts, assigned to particular customer number

customerNumbers[].customerContracts[].number

String

Customer contract number. Must be unique(case insensitive)

customerNumbers[].customerContracts[].description

String

Customer contract number description

customerNumbers[].customerContracts[].states

List<CustomerContractStateTransitionDto>

Array of customer contract state transitions. By default INACTIVE

customerNumbers[].customerContracts[].version

Integer

Customer contract revision. Changes to customer contract will change it revision

customerNumbers[].customerContracts[].isActive

boolean

True, if customerContract is currently active

customerNumbers[].customerContracts[].approvable

boolean

True, if customerContract is approvable

customerNumbers[].customerContracts[].collectable

boolean

True, if customerContract is collectable

customerNumbers[].customerContracts[].outputType

CustomerContractOutputType

OutputType of customerContract. Allowed values: [DW24, EXTERNAL_OUTPUT, TRANSFER_TO_DOWNLOAD_SERVICE]

customerNumbers[].customerContracts[].fileType

FileType

The file-type of the uploads

customerNumbers[].customerContracts[].uploadType

UploadType

The upload-type of the uploads

customerNumbers[].customerContracts[].states[].state

CustomerContractState

Customer contract state. Allowed values: [ACTIVE, INACTIVE]

customerNumbers[].customerContracts[].states[].validFrom

Instant

Customer contract state activation timestamp. By default current time

Example. Register new company minimal request and response

Request

POST /v1/companies HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 94
Host: localhost:8080

{
  "name" : "Profiforms",
  "customerNumbers" : [ {
    "number" : "customerNumber_1"
  } ]
}

Response

HTTP/1.1 201 Created
Location: http://localhost:8080/v1/companies/00000000-0000-0000-0000-000000000001
Content-Type: application/json
Content-Length: 338

{
  "id" : "00000000-0000-0000-0000-000000000001",
  "version" : 0,
  "name" : "Profiforms",
  "customerNumbers" : [ {
    "number" : "customerNumber_1",
    "version" : 0,
    "states" : [ {
      "state" : "INACTIVE",
      "validFrom" : "2121-01-31T11:22:33.456Z"
    } ],
    "customerContracts" : null,
    "isActive" : false
  } ]
}

Same default behaviour is valid for customer contracts.

Example. Register new company with custom customer number status

Request

POST /v1/companies HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 147
Host: localhost:8080

{
  "name" : "Profiforms",
  "customerNumbers" : [ {
    "number" : "customerNumber_1",
    "states" : [ {
      "state" : "ACTIVE"
    } ]
  } ]
}

Response

HTTP/1.1 201 Created
Location: http://localhost:8080/v1/companies/00000000-0000-0000-0000-000000000001
Content-Type: application/json
Content-Length: 336

{
  "id" : "00000000-0000-0000-0000-000000000001",
  "version" : 0,
  "name" : "Profiforms",
  "customerNumbers" : [ {
    "number" : "customerNumber_1",
    "version" : 0,
    "states" : [ {
      "state" : "ACTIVE",
      "validFrom" : "2121-01-31T11:22:33.456Z"
    } ],
    "customerContracts" : null,
    "isActive" : false
  } ]
}

Same default behaviour is valid for customer contracts.

Update company metadata request

PUT /v1/companies/00000000-0000-0000-0000-000000000001 HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 29
Host: localhost:8080

{
  "name" : "Company Name"
}

Request fields

Path Type Description Constraints

name

String

Company name. Must be unique(case insensitive)

Must not be blank

Response

See Example response

Adding customer numbers

POST /v1/companies/00000000-0000-0000-0000-000000000001/customer-numbers HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 1298
Host: localhost:8080

[ {
  "number" : "customerNumber-1",
  "states" : [ {
    "state" : "ACTIVE",
    "validFrom" : "2121-01-31T11:22:33.456Z"
  }, {
    "state" : "INACTIVE",
    "validFrom" : "2121-02-01T11:22:33.456Z"
  } ],
  "customerContracts" : [ {
    "number" : "customerContract-1",
    "description" : "customerContract-1 description",
    "states" : [ {
      "state" : "INACTIVE",
      "validFrom" : "2121-02-01T11:22:33.456Z"
    }, {
      "state" : "ACTIVE",
      "validFrom" : "2121-01-31T11:22:33.456Z"
    } ],
    "approvable" : false,
    "collectable" : false,
    "outputType" : "DW24",
    "fileType" : "PDF",
    "uploadType" : "JOB"
  } ]
}, {
  "number" : "customerNumber-2",
  "states" : [ {
    "state" : "ACTIVE",
    "validFrom" : "2121-01-31T11:22:33.456Z"
  }, {
    "state" : "INACTIVE",
    "validFrom" : "2121-02-01T11:22:33.456Z"
  } ],
  "customerContracts" : [ {
    "number" : "customerContract-2",
    "description" : "customerContract-2 description",
    "states" : [ {
      "state" : "INACTIVE",
      "validFrom" : "2121-02-01T11:22:33.456Z"
    }, {
      "state" : "ACTIVE",
      "validFrom" : "2121-01-31T11:22:33.456Z"
    } ],
    "approvable" : false,
    "collectable" : false,
    "outputType" : "DW24",
    "fileType" : "PDF",
    "uploadType" : "JOB"
  } ]
} ]

Request fields

Path Type Description Constraints

[]

Set<CustomerNumberCreateRequest>

Array of customer numbers, assigned to this company

[].number

String

Customer number. Must be unique(case insensitive)

[].states

List<CustomerNumberStateTransitionDto>

Array of customer number state transitions.

[].customerContracts

List<CustomerContractResponse>

Array of customer contracts, assigned to particular customer number

[].states[].state

CustomerContractState

Customer number state. Allowed values: [ACTIVE, INACTIVE]. By default INACTIVE

Must not be null

[].states[].validFrom

Instant

Customer number state activation timestamp. By default current time

Must be in the future or the present within leeway. Must not be null

[].customerContracts[].number

String

Customer contract number. Must be unique(case insensitive)

[].customerContracts[].description

String

Customer contract number description

[].customerContracts[].states

List<CustomerContractStateTransitionDto>

Array of customer contract state transitions.

[].customerContracts[].approvable

boolean

Uploads approvable?

[].customerContracts[].collectable

boolean

Uploads collectable?

[].customerContracts[].outputType

CustomerContractOutputType

OutputType of upload. Allowed values: [DW24, EXTERNAL_OUTPUT, TRANSFER_TO_DOWNLOAD_SERVICE]

[].customerContracts[].fileType

FileType

FileType of upload. Allowed values: [PDF, RAW]

[].customerContracts[].uploadType

UploadType

UploadType of upload. Allowed values: [JOB, SINGLE]

[].customerContracts[].states[].state

CustomerContractState

Customer contract state. Allowed values: [ACTIVE, INACTIVE]. By default INACTIVE

Must not be null

[].customerContracts[].states[].validFrom

Instant

Customer contract state activation timestamp. By default current time

Must be in the future or the present within leeway. Must not be null

Response

See Example response

Adding customer number states

POST /v1/companies/00000000-0000-0000-0000-000000000001/customer-numbers/1/states HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 144
Host: localhost:8080

[ {
  "state" : "ACTIVE",
  "validFrom" : "2121-01-31T11:22:33.456Z"
}, {
  "state" : "INACTIVE",
  "validFrom" : "2121-02-05T11:22:33.456Z"
} ]

Request fields

Path Type Description Constraints

[]

Set<CustomerNumberStateTransitionDto>

An array of customer number state transitions.

[].state

CustomerContractState

Customer number state. Allowed values: [ACTIVE, INACTIVE]. By default INACTIVE

Must not be null

[].validFrom

Instant

Customer number state activation timestamp. By default current time

Must be in the future or the present within leeway. Must not be null

Response

See Example response

Deleting customer number

DELETE /v1/companies/00000000-0000-0000-0000-000000000001/customer-numbers/67 HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Host: localhost:8080

Response

See Example response

Deleting customer number states

DELETE /v1/companies/00000000-0000-0000-0000-000000000001/customer-numbers/1/states HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 58
Host: localhost:8080

[ "2121-02-15T11:22:33.456Z", "2121-02-25T11:22:33.456Z" ]

Request fields

Path Type Description Constraints

[]

Set<Instant>

An array of instant states to be deleted.

Response

See Example response

Updating customer contract metadata

PUT /v1/companies/00000000-0000-0000-0000-000000000001/customer-numbers/1/customer-contracts/2 HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 39
Host: localhost:8080

{
  "description" : "new description"
}

Request fields

Path Type Description Constraints

description

String

Contract description

Response

See Example response

Adding customer contracts

POST /v1/companies/00000000-0000-0000-0000-000000000001/customer-numbers/1/customer-contracts HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 766
Host: localhost:8080

[ {
  "number" : "customerContract-1",
  "description" : "customerContract-1 description",
  "states" : [ {
    "state" : "INACTIVE",
    "validFrom" : "2121-02-01T11:22:33.456Z"
  }, {
    "state" : "ACTIVE",
    "validFrom" : "2121-01-31T11:22:33.456Z"
  } ],
  "approvable" : false,
  "collectable" : false,
  "outputType" : "DW24",
  "fileType" : "PDF",
  "uploadType" : "JOB"
}, {
  "number" : "customerContract-2",
  "description" : "customerContract-2 description",
  "states" : [ {
    "state" : "INACTIVE",
    "validFrom" : "2121-02-01T11:22:33.456Z"
  }, {
    "state" : "ACTIVE",
    "validFrom" : "2121-01-31T11:22:33.456Z"
  } ],
  "approvable" : false,
  "collectable" : false,
  "outputType" : "DW24",
  "fileType" : "PDF",
  "uploadType" : "JOB"
} ]

Request fields

Path Type Description Constraints

[]

Array

Array of customer contract numbers

[].number

String

Customer contract number. Must be unique(case insensitive)

[].description

String

Customer contract number description

[].states

List<CustomerContractStateTransitionDto>

Array of customer contract state transitions.

[].approvable

boolean

Uploads approvable?

[].collectable

boolean

Uploads collectable?

[].outputType

CustomerContractOutputType

OutputType of upload. Allowed values: [DW24, EXTERNAL_OUTPUT, TRANSFER_TO_DOWNLOAD_SERVICE]

[].fileType

FileType

FileType of upload. Allowed values: [PDF, RAW]

[].uploadType

UploadType

UploadType of upload. Allowed values: [JOB, SINGLE]

[].states[].state

CustomerContractState

Customer contract state. Allowed values: [ACTIVE, INACTIVE]. By default INACTIVE

Must not be null

[].states[].validFrom

Instant

Customer contract state activation timestamp. By default current time

Must be in the future or the present within leeway. Must not be null

Response

See Example response

Adding customer contract states

POST /v1/companies/00000000-0000-0000-0000-000000000001/customer-numbers/1/customer-contracts/1/states HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 144
Host: localhost:8080

[ {
  "state" : "ACTIVE",
  "validFrom" : "2121-01-31T11:22:33.456Z"
}, {
  "state" : "INACTIVE",
  "validFrom" : "2121-02-05T11:22:33.456Z"
} ]

Request fields

Path Type Description Constraints

[]

Array

An array of customer contract state transitions.

[].state

CustomerContractState

Customer contract state. Allowed values: [ACTIVE, INACTIVE]. By default INACTIVE

Must not be null

[].validFrom

Instant

Customer contract state activation timestamp. By default current time

Must be in the future or the present within leeway. Must not be null

Response

See Example response

Deleting customer contract

DELETE /v1/companies/00000000-0000-0000-0000-000000000001/customer-numbers/customerNumber-1/customer-contracts/3124 HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Host: localhost:8080

Response

See Example response

Deleting customer contract states

DELETE /v1/companies/00000000-0000-0000-0000-000000000001/customer-numbers/1/customer-contracts/1/states HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Content-Length: 58
Host: localhost:8080

[ "2121-02-15T11:22:33.456Z", "2121-02-25T11:22:33.456Z" ]

Request fields

Path Type Description Constraints

[]

Set<Instant>

An array of instant states to be deleted.

Response

See Example response

Read dw24 Companies

GET /v1/companies/dw24 HTTP/1.1
X-PF-DWC-Requester-Role: ROLE_PF_ADMIN
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf8
Content-Length: 632

[ {
  "customerNumber" : "customer1",
  "customerName" : "company1",
  "feedbackAddress" : "feed@back.com",
  "contracts" : [ {
    "contractNumber" : "contract",
    "description" : "description",
    "name" : "name",
    "validFrom" : "2020-09-14T13:56:01.314Z",
    "validTo" : "2020-09-14T13:56:01.314Z"
  } ]
}, {
  "customerNumber" : "customer2",
  "customerName" : "company2",
  "feedbackAddress" : "feed@back.com",
  "contracts" : [ {
    "contractNumber" : "contract",
    "description" : "description",
    "name" : "name",
    "validFrom" : "2020-09-14T13:56:01.314Z",
    "validTo" : "2020-09-14T13:56:01.314Z"
  } ]
} ]

Response fields

Path Type Description

[].customerNumber

String

Company customer number

[].customerName

String

Company customer name

[].feedbackAddress

String

Feedback address

[].contracts

List<Dw24Contract>

Company contracts

[].contracts[].contractNumber

String

Company contract number

[].contracts[].description

String

Company contract description

[].contracts[].name

String

Company contract name

[].contracts[].validFrom

String

Company contract valid from

[].contracts[].validTo

String

Company contract valid to

Known error codes

Code Description

de.profiforms.docxworld.connect.company.error.client.external_receiver_url_validation_error

External receiver URL validation error

de.profiforms.docxworld.connect.company.error.client.workflow_approvalNeeded_state

invalid workflow approvalNeeded state

de.profiforms.docxworld.connect.company.error.client.invalid_sort_argument

Invalid sort argument exception

de.profiforms.docxworld.connect.company.error.client.customer_contract_already_exists

CustomerContract already exists exception

de.profiforms.docxworld.connect.company.error.client.instant_duplicate_in_request

Request contains duplicate instants

de.profiforms.docxworld.connect.company.error.client.workflow_not_exists

Workflow not exist

de.profiforms.docxworld.connect.company.error.client.customer_contract_not_exists

Customer contract not exist

de.profiforms.docxworld.connect.company.error.client.customer_number_not_exists

Customer number not exist

de.profiforms.docxworld.connect.company.error.client.target_not_exists

Target not exist

de.profiforms.docxworld.connect.company.error.client.customer_already_exists

Customer already exists

de.profiforms.docxworld.connect.company.error.client.workflow_already_exists

workflow with such name or abbreviation already exists

de.profiforms.docxworld.connect.company.error.client.access_denied

Access denied

de.profiforms.docxworld.connect.company.error.client.validation

Validation error

de.profiforms.docxworld.connect.company.error.client.company_not_exists

Company not exist

de.profiforms.docxworld.connect.company.error.client.role_header_missing

Required request header is missing

de.profiforms.docxworld.connect.company.error.client.customer_number_already_exists

CustomerNumber already exists exception

de.profiforms.docxworld.connect.company.error.server.unexpected_internal

Unexpected internal error

de.profiforms.docxworld.connect.company.error.client.malformed_request

Malformed JSON request

de.profiforms.docxworld.connect.company.error.client.transition_state_already_exists

TransitionState already exists exception

de.profiforms.docxworld.connect.company.error.client.customer_contract_cant_be_deleted

CustomerContract can’t be deleted

de.profiforms.docxworld.connect.company.error.client.customer_number_cant_be_deleted

CustomerNumber can’t be deleted

de.profiforms.docxworld.connect.company.error.client.instant_state_in_the_past

States from the past cannot be deleted

de.profiforms.docxworld.connect.company.error.sns.send_message_failed

Failed to send notifications. Changes cannot be applied.

Contract

Example request

GET /v1/customer-contracts?sort=fileType%2CDESC&sort=uploadType%2CDESC&page=0&size=10&customerContracts=customerContract&customerNumbers=customerNumber&companyIds=00000000-0000-0000-0000-000000000001&uploadTypes=JOB&fileTypes=PDF&approvable=true&collectable=true&state=ACTIVE&expectedFileFormat=PDF HTTP/1.1
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_ADMIN
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1150

{
  "content" : [ {
    "number" : "customerContract-customerContract1",
    "version" : null,
    "description" : "customerContract-customerContract1 description",
    "states" : [ {
      "state" : "ACTIVE",
      "validFrom" : "2121-01-31T11:22:33.456Z"
    }, {
      "state" : "INACTIVE",
      "validFrom" : "2121-02-01T11:22:33.456Z"
    } ],
    "approvable" : false,
    "collectable" : false,
    "outputType" : "DW24",
    "fileType" : "PDF",
    "uploadType" : "JOB",
    "isActive" : false
  }, {
    "number" : "customerContract-customerContract2",
    "version" : null,
    "description" : "customerContract-customerContract2 description",
    "states" : [ {
      "state" : "ACTIVE",
      "validFrom" : "2121-01-31T11:22:33.456Z"
    }, {
      "state" : "INACTIVE",
      "validFrom" : "2121-02-01T11:22:33.456Z"
    } ],
    "approvable" : false,
    "collectable" : false,
    "outputType" : "DW24",
    "fileType" : "PDF",
    "uploadType" : "JOB",
    "isActive" : false
  } ],
  "totalElements" : 2,
  "totalPages" : 1,
  "last" : true,
  "first" : true,
  "numberOfElements" : 2,
  "size" : 2,
  "number" : 0,
  "sort" : [ ]
}

Example. Read contracts with filter

GET /v1/customer-contracts?sort=fileType%2CDESC&sort=uploadType%2CDESC&page=0&size=10&customerContracts=customerContract&customerNumbers=customerNumber&companyIds=00000000-0000-0000-0000-000000000001&uploadTypes=JOB&fileTypes=PDF&approvable=true&collectable=true&state=ACTIVE&expectedFileFormat=PDF HTTP/1.1
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_ADMIN
Host: localhost:8080

Workflow

Register new workflow request

POST /v1/workflows HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_ADMIN
Content-Length: 268
Host: localhost:8080

{
  "customerContract" : "customerContract-1-1",
  "name" : "workflow 1",
  "abbreviation" : "W1",
  "description" : "description workflow 1",
  "approvalNeeded" : false,
  "status" : "ACTIVE",
  "externalReceiver" : {
    "url" : "https://external-receiver-url"
  }
}

Request fields

Path Type Description Constraints

name

String

Workflow name. Must be unique(case insensitive)

Must not be blank. Size must be between 1 and 64 inclusive

abbreviation

String

Workflow abbreviation. Must be unique(case insensitive)

Must not be blank. Size must be between 1 and 16 inclusive

customerContract

String

Customer contract number, workflow associated with

Must not be blank

description

String

Workflow description

Size must be between 0 and 255 inclusive

approvalNeeded

boolean

If approval is requered for this workflow

status

Status

Status of the workflow. Allowed values: [ACTIVE, INACTIVE]

externalReceiver.url

String

External receiver

Must be a well-formed URL. Must not be empty

Example response

HTTP/1.1 201 Created
Location: http://localhost:8080/v1/workflows/00000000-0000-0000-0000-000000000001
Content-Type: application/json
Content-Length: 441

{
  "id" : "00000000-0000-0000-0000-000000000001",
  "version" : 1,
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "customerContract" : "customerContract-1-1",
  "name" : "workflow 1",
  "abbreviation" : "W1",
  "description" : "description workflow 1",
  "approvalNeeded" : false,
  "status" : "ACTIVE",
  "encryptionAllowed" : true,
  "fileType" : null,
  "externalReceiver" : {
    "url" : "https://external-receiver-url"
  }
}

Response fields

Path Type Description

id

UUID

Workflow id

companyId

UUID

Company id

name

String

Workflow name

customerContract

String

Customer contract number, workflow associated with

abbreviation

String

Workflow abbreviation

description

String

Workflow description

approvalNeeded

boolean

If approval is required for this workflow

encryptionAllowed

boolean

If encryption is allowed for this workflow

version

Integer

Workflow revision. Changes to Workflow will change it revision

fileType

FileType

Expected file-type of this workflow.

status

Status

Workflow status. Possible values: [ACTIVE, INACTIVE]

externalReceiver.url

String

External receiver url

Update workflow meta-data request

PUT /v1/workflows/00000000-0000-0000-0000-000000000001 HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_ADMIN
Content-Length: 98
Host: localhost:8080

{
  "name" : "newName",
  "abbreviation" : "newAbbreviation",
  "description" : "newDescription"
}

Request fields

Path Type Description Constraints

name

String

Workflow name. Must be unique(case insensitive)

Must not be blank. Size must be between 1 and 64 inclusive

abbreviation

String

Workflow abbreviation. Must be unique(case insensitive)

Must not be blank. Size must be between 1 and 16 inclusive

description

String

Workflow description.

Size must be between 0 and 255 inclusive

Update workflow settings request

PUT /v1/workflows/00000000-0000-0000-0000-000000000001/settings HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_ADMIN
Content-Length: 29
Host: localhost:8080

{
  "approvalNeeded" : true
}

Request fields

Path Type Description Constraints

approvalNeeded

boolean

Workflow setting, if approval is needed.

Update workflow status request

PUT /v1/workflows/00000000-0000-0000-0000-000000000001/status HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_ADMIN
Content-Length: 27
Host: localhost:8080

{
  "status" : "INACTIVE"
}

Request fields

Path Type Description Constraints

status

Status

Workflow status. Allowed values: [ACTIVE, INACTIVE]

Must not be null

Get workflow by ID

GET /v1/workflows/00000000-0000-0000-0000-000000000001 HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_ADMIN
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 441

{
  "id" : "00000000-0000-0000-0000-000000000001",
  "version" : 1,
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "customerContract" : "customerContract-1-1",
  "name" : "workflow 1",
  "abbreviation" : "W1",
  "description" : "description workflow 1",
  "approvalNeeded" : false,
  "status" : "ACTIVE",
  "encryptionAllowed" : true,
  "fileType" : null,
  "externalReceiver" : {
    "url" : "https://external-receiver-url"
  }
}

List workflows request

Request parameters

GET /v1/workflows
Parameter Description

freeSearch

Filter and return workflows containing provided sequence in name, abbreviation or description. Case insensitive.

name

Filter and return workflows with provided name.

customerContracts

Filter and return workflows assigned to provided contracts.

companyIds

Filter and return workflows assigned to provided companies.

abbreviation

Filter and return workflows with provided abbreviation.

approvalNeeded

Filter and return workflows with provided approvalNeeded.

page

Page number to return. [0,totalPages)

size

Page size. Default 35

Example request

GET /v1/workflows?page=0&size=5&freeSearch=345&name=workflow&customerContracts=1&customerContracts=2&companyIds=00000000-0000-0000-0000-000000000001&companyIds=00000000-0000-0000-0000-000000000002&abbreviation=w1&approvalNeeded=false HTTP/1.1
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_ADMIN
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1122

{
  "content" : [ {
    "id" : "00000000-0000-0000-0000-000000000001",
    "version" : null,
    "companyId" : "00000000-0000-0000-0000-000000000001",
    "customerContract" : "customerContract-1-1",
    "name" : "workflow 1",
    "abbreviation" : "W1",
    "description" : "description workflow 1",
    "approvalNeeded" : false,
    "status" : "ACTIVE",
    "encryptionAllowed" : true,
    "fileType" : null,
    "externalReceiver" : {
      "url" : "https://external-receiver-url"
    }
  }, {
    "id" : "00000000-0000-0000-0000-000000000001",
    "version" : null,
    "companyId" : "00000000-0000-0000-0000-000000000001",
    "customerContract" : "customerContract-1-1",
    "name" : "workflow 1",
    "abbreviation" : "W1",
    "description" : "description workflow 1",
    "approvalNeeded" : false,
    "status" : "ACTIVE",
    "encryptionAllowed" : true,
    "fileType" : null,
    "externalReceiver" : {
      "url" : "https://external-receiver-url"
    }
  } ],
  "totalElements" : 2,
  "totalPages" : 1,
  "last" : true,
  "first" : true,
  "numberOfElements" : 2,
  "size" : 2,
  "number" : 0,
  "sort" : [ ]
}

Target

Get target by ID

GET /v1/targets/00000000-0000-0000-0000-000000000001 HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_ADMIN
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 590

{
  "id" : "00000000-0000-0000-0000-000000000001",
  "version" : null,
  "targetType" : "DEFAULT",
  "workflow" : {
    "id" : "00000000-0000-0000-0000-000000000001",
    "version" : null,
    "companyId" : "00000000-0000-0000-0000-000000000001",
    "customerContract" : "customerContract-1-1",
    "name" : "workflow 1",
    "abbreviation" : "W1",
    "description" : "description workflow 1",
    "approvalNeeded" : false,
    "status" : "ACTIVE",
    "encryptionAllowed" : true,
    "fileType" : null,
    "externalReceiver" : {
      "url" : "https://external-receiver-url"
    }
  }
}

List targets request

Request parameters

GET /v1/targets
Parameter Description

customerContracts

Filter and return targets assigned to provided contracts.

companyIds

Filter and return targets assigned to provided companies.

workflowIds

Filter and return targets assigned to provided workflows.

page

Page number to return. [0,totalPages)

size

Page size. Default 35

sort

Sorting in format [property][,ASC|DESC]. Allowed values: [workflow]. Allowed direction: [ASC, DESC]. Default direction is ASC.

Example request

GET /v1/targets?page=0&size=5&customerContracts=1&customerContracts=2&companyIds=00000000-0000-0000-0000-000000000001&companyIds=00000000-0000-0000-0000-000000000002&workflowIds=00000000-0000-0000-0000-000000000001&workflowIds=00000000-0000-0000-0000-000000000002 HTTP/1.1
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_ADMIN
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1434

{
  "content" : [ {
    "id" : "00000000-0000-0000-0000-000000000001",
    "version" : null,
    "targetType" : "DEFAULT",
    "workflow" : {
      "id" : "00000000-0000-0000-0000-000000000001",
      "version" : null,
      "companyId" : "00000000-0000-0000-0000-000000000001",
      "customerContract" : "customerContract-1-1",
      "name" : "workflow 1",
      "abbreviation" : "W1",
      "description" : "description workflow 1",
      "approvalNeeded" : false,
      "status" : "ACTIVE",
      "encryptionAllowed" : true,
      "fileType" : null,
      "externalReceiver" : {
        "url" : "https://external-receiver-url"
      }
    }
  }, {
    "id" : "00000000-0000-0000-0000-000000000001",
    "version" : null,
    "targetType" : "DEFAULT",
    "workflow" : {
      "id" : "00000000-0000-0000-0000-000000000001",
      "version" : null,
      "companyId" : "00000000-0000-0000-0000-000000000001",
      "customerContract" : "customerContract-1-1",
      "name" : "workflow 1",
      "abbreviation" : "W1",
      "description" : "description workflow 1",
      "approvalNeeded" : false,
      "status" : "ACTIVE",
      "encryptionAllowed" : true,
      "fileType" : null,
      "externalReceiver" : {
        "url" : "https://external-receiver-url"
      }
    }
  } ],
  "totalElements" : 2,
  "totalPages" : 1,
  "last" : true,
  "first" : true,
  "numberOfElements" : 2,
  "size" : 2,
  "number" : 0,
  "sort" : [ ]
}

Response fields

Path Type Description

id

UUID

Target id

version

Integer

Target revision. Changes to target will change it revision

targetType

TargetType

Target type. Possible values: [DEFAULT, MANUAL]

workflow.id

UUID

Workflow id

workflow.name

String

Workflow name

workflow.version

Integer

Workflow version

workflow.companyId

UUID

Company id

workflow.customerContract

String

Customer contract number, workflow associated with

workflow.abbreviation

String

Workflow abbreviation

workflow.description

String

Workflow description

workflow.approvalNeeded

boolean

If approval is required for this workflow

workflow.encryptionAllowed

boolean

If encryption is allowed for this workflow

workflow.fileType

FileType

Expected file-type for this workflow

workflow.status

Status

Workflow status. Possible values: [ACTIVE, INACTIVE]

workflow.externalReceiver.url

String

External receiver url

Download

List downloads request

GET /v1/downloads
Parameter Description

targets

Filter and return downloads for given targets.

targetName

Filter and return downloads for target-names containing input value.

downloaded

Filter and return downloads that are already downloaded or not. Allowed values: [true, false, null]

downloadTypes

Filter and return downloads for given download-types. Allowed values: [RESULT, REPORT]

freeSearch

Filter by free search of worflow-name, filename, document-id or reference-id.

page

Page number to return. [0,totalPages)

size

Page size. Default 35

sort

Sorting in format [property][,ASC|DESC]. Allowed values: [created, targetName, type]. Allowed direction: [ASC, DESC]. Default direction is ASC.

Example request

##

GET /v1/downloads?targets=00000000-0000-0000-0000-000000000001&targets=00000000-0000-0000-0000-000000000002&downloadTypes=RESULT&downloadTypes=REPORT&downloaded=false&freeSearch=filename HTTP/1.1
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_DOWNLOADER_RESULTS
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 936

{
  "content" : [ {
    "id" : "00000000-0000-0000-0000-000000000001",
    "referenceId" : "42",
    "fileName" : "download1",
    "customerContract" : "42",
    "targetId" : "00000000-0000-0000-0000-000000000001",
    "targetName" : "targetName_42",
    "created" : "2121-01-31T11:17:33.456Z",
    "downloaded" : null,
    "downloadLinkGenerated" : false,
    "size" : 42,
    "type" : "RESULT"
  }, {
    "id" : "00000000-0000-0000-0000-000000000002",
    "referenceId" : "42",
    "fileName" : "download2",
    "customerContract" : "42",
    "targetId" : "00000000-0000-0000-0000-000000000001",
    "targetName" : "targetName_42",
    "created" : "2121-01-31T11:17:33.456Z",
    "downloaded" : null,
    "downloadLinkGenerated" : false,
    "size" : 42,
    "type" : "RESULT"
  } ],
  "totalElements" : 2,
  "totalPages" : 1,
  "last" : true,
  "first" : true,
  "numberOfElements" : 2,
  "size" : 2,
  "number" : 0,
  "sort" : [ ]
}

Response fields

Path Type Description

content[].id

UUID

ID of the download

content[].referenceId

String

Reference-ID of the download

content[].fileName

String

Filename of the download

content[].customerContract

String

Customer-contract of the download

content[].targetId

UUID

Target-ID of the download

content[].targetName

String

Target-name of the download

content[].created

Instant

Creation time of the download

content[].downloadLinkGenerated

boolean

Download link already created

content[].downloaded

Instant

Download acknowledge time

content[].size

Long

Size of the download

content[].type

DownloadType

Type of the download

Example request

GET /v1/downloads/00000000-0000-0000-0000-000000000001/generate-link HTTP/1.1
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_DOWNLOADER_RESULTS
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 406

{
  "id" : "00000000-0000-0000-0000-000000000001",
  "downloadLink" : "https://dwc-ai-test.s3.eu-central-1.amazonaws.com/report.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20220607T153352Z&X-Amz-SignedHeaders=host&X-Amz-Expires=548767&X-Amz-Credential=AKIAWSSDUUOI3B7IN4U3%2F20220607%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Signature=45a70be4763f8adc3836218c2c0de829dc17b1e598a716e2d916131935fd23cb"
}

Acknowledge download

Call this endpoint to acknowledge that you have downloaded the file. Once acknowledged, the file will no longer appear when using the List downloads request endpoint with the "downloaded" filter.

Client-Id (required) A unique identifier for the download client. Ensure that the same Client-Id is sent during retries to distinguish between different clients.

Behavior

  • Only one client can successfully acknowledge a given download.

  • Subsequent calls using the same Client-Id will return the same result as the first successful call.

  • If a different Client-Id attempts to acknowledge an already acknowledged download, a 409 Conflict error is returned.

Endpoint

POST /v1/downloads/{id}/acknowledge
Parameter Description

id

id of the download to acknowledge

Example request

POST /v1/downloads/00000000-0000-0000-0000-000000000001/acknowledge HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_DOWNLOADER_RESULTS
Content-Length: 52
Host: localhost:8080

{"clientId":"spooler_1","referenceId":"idInSpooler"}
Path Type Description Constraints

clientId

String

Client identifier. Same client can call the endpoint multiple times. Always get the same result. Once acknowledge for one client, it is not acknowledge for any another client.

Must not be blank. Size must be between 1 and 255 inclusive

referenceId

String

Reference identifier in downloader system.

Size must be between 1 and 255 inclusive

Example response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 379

{
  "id" : "00000000-0000-0000-0000-000000000001",
  "referenceId" : "42",
  "fileName" : "download1",
  "customerContract" : "42",
  "targetId" : "00000000-0000-0000-0000-000000000001",
  "targetName" : "targetName_42",
  "created" : "2121-01-31T11:17:33.456Z",
  "downloaded" : "2121-01-31T11:22:33.456Z",
  "downloadLinkGenerated" : false,
  "size" : 42,
  "type" : "RESULT"
}

Conflict response

HTTP/1.1 409 Conflict
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 495

{
  "id" : "bef8474b-44dd-4c54-b0ca-5dfe6805b914",
  "status" : "CONFLICT",
  "timestamp" : "2025-08-12T13:19:14.419576082Z",
  "message" : "Download was marked as saved already",
  "messageCode" : "de.profiforms.docxworld.connect.download.error.client.download_already_saved",
  "debugMessages" : [ "Download with id '00000000-0000-0000-0000-000000000001' was already marked as acknowledged by client 'spooler_1'" ],
  "path" : "/v1/downloads/00000000-0000-0000-0000-000000000001/acknowledge"
}

Known error codes

Code Description

de.profiforms.docxworld.connect.download.error.client.download_not_exists

Download not exists exception

de.profiforms.docxworld.connect.download.error.client.access_denied

Access denied

de.profiforms.docxworld.connect.download.error.client.malformed_request

Malformed JSON request

de.profiforms.docxworld.connect.download.error.client.download_already_saved

Download was marked as saved already

de.profiforms.docxworld.connect.download.error.client.invalid_sort_argument

Invalid sort argument exception

de.profiforms.docxworld.connect.download.error.client.no_file_attached

No file attached exception

de.profiforms.docxworld.connect.download.error.client.validation

Validation error

de.profiforms.docxworld.connect.download.error.client.target_not_exists

Target not exists exception

de.profiforms.docxworld.connect.download.error.server.unexpected_internal

Unexpected internal error

de.profiforms.docxworld.connect.download.error.client.error

Client error

de.profiforms.docxworld.connect.download.error.client.file_not_exists

File not exists exception

de.profiforms.docxworld.connect.download.error.client.role_header_missing

Required request header is missing