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

The API supports two authentication types. Every endpoint documents which type(s) it accepts with an Authentication note that links back to the matching subsection below:

An endpoint may accept only one of the two types or both.

User authentication

Interactive access used by human users signed in to the portal. A request authenticates with a Cognito JWT access token and declares the acting role through the X-PF-DWC-Requester-Role header.

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

Technical authentication

Machine-to-machine access used by technical clients. A request authenticates with a technical JWT access token obtained through the OAuth client-credentials flow, using the one-time credentials issued by the Create technical access endpoint.

The acting role is derived from the token’s OAuth scope claim (for example tower/customer-uploader). Technical requests therefore do not send the X-PF-DWC-Requester-Role header; the role is taken from the token.

PUT /v1/uploads HTTP/1.1
Authorization: Bearer {JWT_ACCESS_TOKEN}
Host: localhost:8080

Technical clients and their scopes are managed through the Technical Access endpoints.

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
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: 264

{
  "debugMessages" : [ null ],
  "id" : "<generated-uuid>",
  "message" : "Bad Request",
  "messageCode" : "de.profiforms.docxworld.upload.error.client.bad_request",
  "path" : "/v1/something",
  "status" : "BAD_REQUEST",
  "timestamp" : "<generated-timestamp>"
}

User

Register new user request

Authentication: User authentication

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

{"companyId":null,"email":"email@email.com","firstName":"Max","lastName":"Musterman","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

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

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

Authentication: User authentication

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

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

List users request

Authentication: User authentication

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

Update user request

Authentication: User authentication

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

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

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

Authentication: User authentication

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

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

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

Authentication: User authentication

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

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

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

Authentication: User authentication

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

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

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

Authentication: User authentication

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

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

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

Authentication: User authentication

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

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

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

Authentication: User authentication

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

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

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

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

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

Authentication: User authentication

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

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

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

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

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

Authentication: User authentication

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

Example response

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

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

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

User notification settings

A user manages their own notification settings through the /v1/users/me/... endpoints. Settings are scoped per role: a user only has the settings that belong to the roles assigned to them. In the response the settings are keyed by the role they belong to, using the same role identifier as roles and scopedTargets (e.g. ROLE_CUSTOMER_UPLOADER). A role key is present only when the user actually has that role; its value carries the role’s notification block(s), populated with defaults when nothing has been persisted yet.

Each notification block is updated by its own endpoint, and the request path mirrors the location of the block in the response (settings.<ROLE>.<notification>) so that request and response stay symmetric. The field reference and the possible value combinations are documented per endpoint below.

Retrieve current user settings

Authentication: User authentication

Returns the caller’s profile together with the settings of every role the user holds. The example below is for a user holding both the uploader and the approver role, so every notification block is present.

All response fields other than settings are the standard user profile fields, documented under Register new user (Response fields). The settings field is described below.

GET /v1/users/me/settings 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: 1206

{
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "companyName",
  "email" : "123@profiforms.de",
  "firstName" : "firstName_123",
  "id" : "123",
  "lastLogin" : "2007-12-03T10:15:30Z",
  "lastName" : "lastName_123",
  "roles" : [ "ROLE_CUSTOMER_UPLOADER", "ROLE_CUSTOMER_APPROVER" ],
  "scopedCustomerContracts" : { },
  "scopedTargets" : {
    "ROLE_CUSTOMER_APPROVER" : [ "00000000-0000-0000-0000-000000000001" ],
    "ROLE_CUSTOMER_UPLOADER" : [ "00000000-0000-0000-0000-000000000001" ]
  },
  "settings" : {
    "ROLE_CUSTOMER_APPROVER" : {
      "newApprovalNotification" : {
        "allowedTargets" : [ "00000000-0000-0000-0000-000000000001" ],
        "deliveryMode" : "SCHEDULED",
        "mode" : "SELECTED",
        "scheduledTimes" : [ "09:00", "14:00" ],
        "selectedTargets" : [ "00000000-0000-0000-0000-000000000001" ],
        "timeZone" : "Europe/Berlin"
      }
    },
    "ROLE_CUSTOMER_UPLOADER" : {
      "approvalSuccessNotification" : {
        "allowedTargets" : [ "00000000-0000-0000-0000-000000000001" ],
        "mode" : "SELECTED",
        "selectedTargets" : [ "00000000-0000-0000-0000-000000000001" ]
      }
    }
  },
  "status" : "ACTIVE"
}

The notification settings are grouped under the role they belong to. Each block is managed by its own endpoint — follow the link for the field reference and the request examples:

Notification Managed by (PUT) — see

settings.ROLE_CUSTOMER_UPLOADER.approvalSuccessNotification

…/ROLE_CUSTOMER_UPLOADER/approvalSuccessNotification (Update the uploader approval-success notification)

settings.ROLE_CUSTOMER_APPROVER.newApprovalNotification

…/ROLE_CUSTOMER_APPROVER/newApprovalNotification (Update the approver new-approval notification)

Update the uploader approval-success notification

Authentication: User authentication

Manages settings.ROLE_CUSTOMER_UPLOADER.approvalSuccessNotification — the notification an uploader receives when one of their uploads has been approved. The caller must have ROLE_CUSTOMER_UPLOADER.

PUT /v1/users/me/settings/ROLE_CUSTOMER_UPLOADER/approvalSuccessNotification HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_UPLOADER
Content-Length: 72
Host: localhost:8080

{"mode":"SELECTED","targetIds":["00000000-0000-0000-0000-000000000001"]}
Request fields
Path Type Description Constraints

mode

NotificationTargetSelectionMode

Target selection mode. NONE disables the notification, ALL_ASSIGNED notifies about every target assigned to the uploader (and approvable), SELECTED notifies only about the targets in targetIds.

Must not be null

targetIds

Set<UUID>

Target ids to notify about. Every id must be assigned to the uploader and be approvable, otherwise the request is rejected with 400.

Required when mode is SELECTED. Must be empty otherwise.
Request examples

Disable the notification (mode = NONE):

{"mode":"NONE"}

Notify about every assigned target (mode = ALL_ASSIGNED):

{"mode":"ALL_ASSIGNED"}

Notify about specific targets only (mode = SELECTED):

{"mode":"SELECTED","targetIds":["00000000-0000-0000-0000-000000000001"]}
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 725

{
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "companyName",
  "email" : "123@profiforms.de",
  "firstName" : "firstName_123",
  "id" : "123",
  "lastLogin" : "2007-12-03T10:15:30Z",
  "lastName" : "lastName_123",
  "roles" : [ "ROLE_CUSTOMER_UPLOADER" ],
  "scopedCustomerContracts" : { },
  "scopedTargets" : {
    "ROLE_CUSTOMER_UPLOADER" : [ "00000000-0000-0000-0000-000000000001" ]
  },
  "settings" : {
    "ROLE_CUSTOMER_UPLOADER" : {
      "approvalSuccessNotification" : {
        "allowedTargets" : [ "00000000-0000-0000-0000-000000000001" ],
        "mode" : "SELECTED",
        "selectedTargets" : [ "00000000-0000-0000-0000-000000000001" ]
      }
    }
  },
  "status" : "ACTIVE"
}
Response fields
Path Type Description

settings.ROLE_CUSTOMER_UPLOADER.approvalSuccessNotification.mode

String

The stored selection mode.

settings.ROLE_CUSTOMER_UPLOADER.approvalSuccessNotification.allowedTargets

Array

All targets the uploader may choose from (assigned to the uploader and flagged approvable).

settings.ROLE_CUSTOMER_UPLOADER.approvalSuccessNotification.selectedTargets

Array

Targets the notification effectively applies to: empty for NONE, all of allowedTargets for ALL_ASSIGNED, the intersection of targetIds and allowedTargets for SELECTED.

Update the approver new-approval notification

Authentication: User authentication

Manages settings.ROLE_CUSTOMER_APPROVER.newApprovalNotification — the notification an approver receives when a new upload is waiting for their approval. The caller must have ROLE_CUSTOMER_APPROVER. The notification is configured by a target selection (mode, targetIds) and a delivery schedule (deliveryMode, scheduledTimes, timeZone), all described in the request fields below.

PUT /v1/users/me/settings/ROLE_CUSTOMER_APPROVER/newApprovalNotification HTTP/1.1
Content-Type: application/json;charset=UTF8
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_APPROVER
Content-Length: 200
Host: localhost:8080

{"deliveryMode":"SCHEDULED","mode":"SELECTED","scheduledTimes":["09:00","14:00"],"targetIds":["00000000-0000-0000-0000-000000000001","00000000-0000-0000-0000-000000000002"],"timeZone":"Europe/Berlin"}
Request fields
Path Type Description Constraints

mode

NotificationTargetSelectionMode

Target selection mode. NONE disables the notification, ALL_ASSIGNED notifies about every target assigned to the approver (and approvable), SELECTED notifies only about the targets in targetIds.

Must not be null

targetIds

Set<UUID>

Target ids to notify about. Every id must be assigned to the approver and be approvable, otherwise the request is rejected with 400.

Required when mode is SELECTED. Must be empty otherwise.

deliveryMode

NotificationDeliveryMode

IMMEDIATE sends a notification per event; SCHEDULED sends a digest at scheduledTimes.

Optional. Defaults to IMMEDIATE.

scheduledTimes

List<String>

Distinct full local-time hours (e.g. 09:00) at which the digest is sent.

Required when deliveryMode is SCHEDULED. Must be empty otherwise.

timeZone

String

IANA time zone applied to scheduledTimes (e.g. Europe/Berlin).

Optional. Defaults to Europe/Berlin.
Request examples

Disable the notification (mode = NONE):

{"mode":"NONE"}

Immediate notification for every assigned target (mode = ALL_ASSIGNED; deliveryMode defaults to IMMEDIATE):

{"mode":"ALL_ASSIGNED"}

Immediate notification for specific targets (mode = SELECTED; deliveryMode defaults to IMMEDIATE):

{"mode":"SELECTED","targetIds":["00000000-0000-0000-0000-000000000001"]}

Scheduled digest for every assigned target (mode = ALL_ASSIGNED, deliveryMode = SCHEDULED):

{"mode":"ALL_ASSIGNED","deliveryMode":"SCHEDULED","scheduledTimes":["09:00","14:00"]}

Scheduled digest for specific targets (mode = SELECTED, deliveryMode = SCHEDULED):

{"mode":"SELECTED","deliveryMode":"SCHEDULED","targetIds":["00000000-0000-0000-0000-000000000001"],"scheduledTimes":["09:00","14:00"]}
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 846

{
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "companyName",
  "email" : "123@profiforms.de",
  "firstName" : "firstName_123",
  "id" : "123",
  "lastLogin" : "2007-12-03T10:15:30Z",
  "lastName" : "lastName_123",
  "roles" : [ "ROLE_CUSTOMER_APPROVER" ],
  "scopedCustomerContracts" : { },
  "scopedTargets" : {
    "ROLE_CUSTOMER_APPROVER" : [ "00000000-0000-0000-0000-000000000001" ]
  },
  "settings" : {
    "ROLE_CUSTOMER_APPROVER" : {
      "newApprovalNotification" : {
        "allowedTargets" : [ "00000000-0000-0000-0000-000000000001" ],
        "deliveryMode" : "SCHEDULED",
        "mode" : "SELECTED",
        "scheduledTimes" : [ "09:00", "14:00" ],
        "selectedTargets" : [ "00000000-0000-0000-0000-000000000001" ],
        "timeZone" : "Europe/Berlin"
      }
    }
  },
  "status" : "ACTIVE"
}
Response fields
Path Type Description

settings.ROLE_CUSTOMER_APPROVER.newApprovalNotification.mode

String

The stored selection mode.

settings.ROLE_CUSTOMER_APPROVER.newApprovalNotification.deliveryMode

String

The stored delivery mode.

settings.ROLE_CUSTOMER_APPROVER.newApprovalNotification.allowedTargets

Array

All targets the approver may choose from (assigned to the approver and flagged approvable).

settings.ROLE_CUSTOMER_APPROVER.newApprovalNotification.selectedTargets

Array

Targets the notification effectively applies to: empty for NONE, all of allowedTargets for ALL_ASSIGNED, the intersection of targetIds and allowedTargets for SELECTED.

settings.ROLE_CUSTOMER_APPROVER.newApprovalNotification.scheduledTimes

Array

The stored schedule. Empty for deliveryMode = IMMEDIATE.

settings.ROLE_CUSTOMER_APPROVER.newApprovalNotification.timeZone

String

The stored time zone for scheduledTimes.

Reset user’s initial password

Authentication: User authentication

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

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

Technical Access

Create technical access

Authentication: User authentication

The create response contains an oauth descriptor with the one-time client credentials and the client-credentials metadata needed to exchange them for an access token.

POST /v1/technical-access HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_ADMIN
Content-Length: 138
Host: localhost:8080

{
  "companyId": "00000000-0000-0000-0000-000000000001",
  "name": "download integration",
  "allowedRoles": ["ROLE_CUSTOMER_UPLOADER"]
}

Request fields

Path Type Description Constraints

companyId

UUID

Company that owns the technical access

Must not be null

name

String

Display name of the technical access

Must not be blank

allowedRoles

Set<PublicRole>

Allowed technical roles for the client

Must not be empty

Example response

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

{
  "oauth" : {
    "clientId" : "client-id-123",
    "clientSecret" : "client-secret-456",
    "grantType" : "client_credentials",
    "issuer" : "https://cognito-idp.eu-central-1.amazonaws.com/eu-central-1_testPoolId",
    "scopeSeparator" : " ",
    "supportedScopes" : [ "tower/customer-uploader" ],
    "tokenEndpointAuthMethod" : "client_secret_basic",
    "tokenUrl" : "https://tower-auth.dev.profiforms-dev.de/oauth2/token"
  },
  "technicalAccess" : {
    "allowedRoles" : [ "ROLE_CUSTOMER_UPLOADER" ],
    "cognitoClientId" : "client-id-123",
    "companyId" : "00000000-0000-0000-0000-000000000001",
    "companyName" : "AI COM gmbh",
    "createdAt" : "2024-01-10T10:15:30Z",
    "createdBy" : "creator@profiforms.de",
    "createdByDisplay" : "creator@profiforms.de",
    "deletedAt" : null,
    "disabledAt" : null,
    "id" : "00000000-0000-0000-0000-000000000010",
    "lastAuthenticatedAt" : null,
    "lastRotatedAt" : null,
    "name" : "download integration",
    "rotationInProgress" : false,
    "rotationStartedAt" : null,
    "scopedTargets" : { },
    "status" : "ACTIVE"
  }
}

Response fields

Path Type Description

oauth.clientId

Unknown

Provisioned Cognito app client id

oauth.clientSecret

Unknown

One-time Cognito app client secret

oauth.issuer

Unknown

JWT issuer for the technical access token

oauth.tokenUrl

Unknown

OAuth token endpoint for client credentials exchange

oauth.grantType

Unknown

Supported OAuth grant type

oauth.tokenEndpointAuthMethod

Unknown

Authentication method at the token endpoint

oauth.scopeSeparator

Unknown

Separator to use when requesting multiple scopes

oauth.supportedScopes

Unknown

OAuth scopes provisioned for this technical access

technicalAccess.id

Unknown

Technical access id

technicalAccess.companyId

Unknown

Owning company id

technicalAccess.companyName

Unknown

Owning company display name

technicalAccess.name

Unknown

Technical access display name

technicalAccess.status

Unknown

Technical access status

technicalAccess.cognitoClientId

Unknown

Provisioned Cognito app client id

technicalAccess.allowedRoles

Unknown

Allowed roles for this technical access

technicalAccess.scopedTargets

Unknown

Target assignments grouped by technical role

technicalAccess.createdBy

Unknown

User who created the technical access

technicalAccess.createdByDisplay

Unknown

Display value for the technical access creator

technicalAccess.createdAt

Unknown

Technical access creation timestamp

technicalAccess.lastAuthenticatedAt

Unknown

Last successful client authentication timestamp

technicalAccess.lastRotatedAt

Unknown

Last secret rotation timestamp

technicalAccess.rotationInProgress

Unknown

Whether a staged secret rotation is currently in progress

technicalAccess.rotationStartedAt

Unknown

Timestamp when the current staged secret rotation was started

technicalAccess.disabledAt

Unknown

Disable timestamp

technicalAccess.deletedAt

Unknown

Delete timestamp

List technical access entries

Authentication: User authentication

Technical access entries are returned as a paged response and support the standard page, size, and sort query parameters. Allowed sort fields are name, status, and createdAt. Entries already deleted from the lifecycle are hidden from the default list.

GET /v1/technical-access?companyIds=00000000-0000-0000-0000-000000000001 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: 1454

{
  "content" : [ {
    "allowedRoles" : [ "ROLE_CUSTOMER_UPLOADER" ],
    "cognitoClientId" : "client-id-123",
    "companyId" : "00000000-0000-0000-0000-000000000001",
    "companyName" : "AI COM gmbh",
    "createdAt" : "2024-01-10T10:15:30Z",
    "createdBy" : "creator@profiforms.de",
    "createdByDisplay" : "creator@profiforms.de",
    "deletedAt" : null,
    "disabledAt" : null,
    "id" : "00000000-0000-0000-0000-000000000010",
    "lastAuthenticatedAt" : null,
    "lastRotatedAt" : null,
    "name" : "download integration",
    "rotationInProgress" : false,
    "rotationStartedAt" : null,
    "scopedTargets" : { },
    "status" : "ACTIVE"
  }, {
    "allowedRoles" : [ "ROLE_CUSTOMER_UPLOADER" ],
    "cognitoClientId" : "client-id-456",
    "companyId" : "00000000-0000-0000-0000-000000000001",
    "companyName" : "AI COM gmbh",
    "createdAt" : "2024-01-10T10:15:30Z",
    "createdBy" : "creator@profiforms.de",
    "createdByDisplay" : "creator@profiforms.de",
    "deletedAt" : null,
    "disabledAt" : null,
    "id" : "00000000-0000-0000-0000-000000000011",
    "lastAuthenticatedAt" : null,
    "lastRotatedAt" : null,
    "name" : "inactive access",
    "rotationInProgress" : false,
    "rotationStartedAt" : null,
    "scopedTargets" : { },
    "status" : "INACTIVE"
  } ],
  "totalElements" : 2,
  "totalPages" : 1,
  "last" : true,
  "first" : true,
  "numberOfElements" : 2,
  "size" : 35,
  "number" : 0,
  "sort" : [ ]
}

Response fields

Path Type Description

content[].id

Unknown

Technical access id

content[].companyId

Unknown

Owning company id

content[].companyName

Unknown

Owning company display name

content[].name

Unknown

Technical access display name

content[].status

Unknown

Technical access status

content[].cognitoClientId

Unknown

Provisioned Cognito app client id

content[].allowedRoles

Unknown

Allowed roles for this technical access

content[].scopedTargets

Unknown

Target assignments grouped by technical role

content[].createdBy

Unknown

User who created the technical access

content[].createdByDisplay

Unknown

Display value for the technical access creator

content[].createdAt

Unknown

Technical access creation timestamp

content[].lastAuthenticatedAt

Unknown

Last successful client authentication timestamp

content[].lastRotatedAt

Unknown

Last secret rotation timestamp

content[].rotationInProgress

Unknown

Whether a staged secret rotation is currently in progress

content[].rotationStartedAt

Unknown

Timestamp when the current staged secret rotation was started

content[].disabledAt

Unknown

Disable timestamp

content[].deletedAt

Unknown

Delete timestamp

totalElements

Unknown

Total amount of technical access entries

totalPages

Unknown

Total amount of result pages

last

Unknown

Whether this is the last page

first

Unknown

Whether this is the first page

numberOfElements

Unknown

Amount of returned entries in this page

size

Unknown

Configured page size

number

Unknown

Returned page number

sort

Unknown

Applied sort order

Get technical access details

Authentication: User authentication

Technical access details are resolved for a single visible entry. The endpoint follows the same visibility rules as the paged list and returns 404 when the entry is not visible in the caller’s technical-access scope.

GET /v1/technical-access/{technicalAccessId}
Parameter Description

technicalAccessId

Technical access id

Example request

GET /v1/technical-access/00000000-0000-0000-0000-000000000010 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: 605

{
  "allowedRoles" : [ "ROLE_CUSTOMER_UPLOADER" ],
  "cognitoClientId" : "client-id-123",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "AI COM gmbh",
  "createdAt" : "2024-01-10T10:15:30Z",
  "createdBy" : "creator@profiforms.de",
  "createdByDisplay" : "creator@profiforms.de",
  "deletedAt" : null,
  "disabledAt" : null,
  "id" : "00000000-0000-0000-0000-000000000010",
  "lastAuthenticatedAt" : null,
  "lastRotatedAt" : null,
  "name" : "download integration",
  "rotationInProgress" : false,
  "rotationStartedAt" : null,
  "scopedTargets" : { },
  "status" : "ACTIVE"
}

Response fields

Path Type Description

id

UUID

Technical access id

companyId

UUID

Owning company id

companyName

String

Owning company display name

name

String

Technical access display name

status

TechnicalAccessStatus

Technical access status

cognitoClientId

String

Provisioned Cognito app client id

allowedRoles

Set<PublicRole>

Allowed roles for this technical access

scopedTargets

Map<PublicRole, Set<UUID>>

Target assignments grouped by technical role

createdBy

String

User who created the technical access

createdByDisplay

String

Display value for the technical access creator

createdAt

Instant

Technical access creation timestamp

lastAuthenticatedAt

Instant

Last successful client authentication timestamp

lastRotatedAt

Instant

Last secret rotation timestamp

rotationInProgress

boolean

Whether a staged secret rotation is currently in progress

rotationStartedAt

Instant

Timestamp when the current staged secret rotation was started

disabledAt

Instant

Disable timestamp

deletedAt

Instant

Delete timestamp

Add targets to technical access

Authentication: User authentication

Target assignments are stored per technical role. Only a Customer Admin can change them, and every requested target must belong to both the owning company and the Customer Admin’s own target scope. PF Admin can manage the technical access at company level but cannot change its target assignments.

PUT /v1/technical-access/{technicalAccessId}/targets
Parameter Description

technicalAccessId

Technical access id

Example request

PUT /v1/technical-access/00000000-0000-0000-0000-000000000010/targets HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_ADMIN
Content-Length: 90
Host: localhost:8080

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

Request fields

Path Type Description Constraints

targetRole

PublicRole

Technical role that receives the target assignments

Must not be null

targets

Set<UUID>

Non-empty target ids to assign

Must not be empty

Example response

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

{
  "allowedRoles" : [ "ROLE_CUSTOMER_UPLOADER" ],
  "cognitoClientId" : "client-id-123",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "AI COM gmbh",
  "createdAt" : "2024-01-10T10:15:30Z",
  "createdBy" : "creator@profiforms.de",
  "createdByDisplay" : "creator@profiforms.de",
  "deletedAt" : null,
  "disabledAt" : null,
  "id" : "00000000-0000-0000-0000-000000000010",
  "lastAuthenticatedAt" : null,
  "lastRotatedAt" : null,
  "name" : "download integration",
  "rotationInProgress" : false,
  "rotationStartedAt" : null,
  "scopedTargets" : {
    "ROLE_CUSTOMER_UPLOADER" : [ "00000000-0000-0000-0000-000000000001" ]
  },
  "status" : "ACTIVE"
}

Response fields

Path Type Description

id

UUID

Technical access id

companyId

UUID

Owning company id

companyName

String

Owning company display name

name

String

Technical access display name

status

TechnicalAccessStatus

Technical access status

cognitoClientId

String

Provisioned Cognito app client id

allowedRoles

Set<PublicRole>

Allowed roles for this technical access

scopedTargets

Map<PublicRole, Set<UUID>>

Target assignments grouped by technical role

createdBy

String

User who created the technical access

createdByDisplay

String

Display value for the technical access creator

createdAt

Instant

Technical access creation timestamp

lastAuthenticatedAt

Instant

Last successful client authentication timestamp

lastRotatedAt

Instant

Last secret rotation timestamp

rotationInProgress

boolean

Whether a staged secret rotation is currently in progress

rotationStartedAt

Instant

Timestamp when the current staged secret rotation was started

disabledAt

Instant

Disable timestamp

deletedAt

Instant

Delete timestamp

Remove targets from technical access

Authentication: User authentication

Removing targets uses the same request shape as adding targets. Removing the final assignment is valid and leaves an empty scope; the client can still authenticate, but target-dependent operations are denied. Concurrent DynamoDB changes return HTTP 409, after which callers must reload the current assignments.

DELETE /v1/technical-access/{technicalAccessId}/targets
Parameter Description

technicalAccessId

Technical access id

Example request

DELETE /v1/technical-access/00000000-0000-0000-0000-000000000010/targets HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_ADMIN
Content-Length: 90
Host: localhost:8080

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

Request fields

Path Type Description Constraints

targetRole

PublicRole

Technical role from which target assignments are removed

Must not be null

targets

Set<UUID>

Non-empty target ids to remove

Must not be empty

Example response

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

{
  "allowedRoles" : [ "ROLE_CUSTOMER_UPLOADER" ],
  "cognitoClientId" : "client-id-123",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "AI COM gmbh",
  "createdAt" : "2024-01-10T10:15:30Z",
  "createdBy" : "creator@profiforms.de",
  "createdByDisplay" : "creator@profiforms.de",
  "deletedAt" : null,
  "disabledAt" : null,
  "id" : "00000000-0000-0000-0000-000000000010",
  "lastAuthenticatedAt" : null,
  "lastRotatedAt" : null,
  "name" : "download integration",
  "rotationInProgress" : false,
  "rotationStartedAt" : null,
  "scopedTargets" : {
    "ROLE_CUSTOMER_UPLOADER" : [ "00000000-0000-0000-0000-000000000002" ]
  },
  "status" : "ACTIVE"
}

Response fields

Path Type Description

id

UUID

Technical access id

companyId

UUID

Owning company id

companyName

String

Owning company display name

name

String

Technical access display name

status

TechnicalAccessStatus

Technical access status

cognitoClientId

String

Provisioned Cognito app client id

allowedRoles

Set<PublicRole>

Allowed roles for this technical access

scopedTargets

Map<PublicRole, Set<UUID>>

Target assignments grouped by technical role

createdBy

String

User who created the technical access

createdByDisplay

String

Display value for the technical access creator

createdAt

Instant

Technical access creation timestamp

lastAuthenticatedAt

Instant

Last successful client authentication timestamp

lastRotatedAt

Instant

Last secret rotation timestamp

rotationInProgress

boolean

Whether a staged secret rotation is currently in progress

rotationStartedAt

Instant

Timestamp when the current staged secret rotation was started

disabledAt

Instant

Disable timestamp

deletedAt

Instant

Delete timestamp

Update technical access state

Authentication: User authentication

Status updates are handled separately from other technical-access metadata. The current lifecycle allows switching between ACTIVE and INACTIVE.

PUT /v1/technical-access/{technicalAccessId}/state
Parameter Description

technicalAccessId

Technical access id

Example request

PUT /v1/technical-access/00000000-0000-0000-0000-000000000010/state HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-PF-DWC-Requester-Role: ROLE_CUSTOMER_ADMIN
Content-Length: 27
Host: localhost:8080

{
  "status": "INACTIVE"
}

Request fields

Path Type Description Constraints

status

TechnicalAccessStatus

Target technical access status. Supported values: ACTIVE, INACTIVE

Must not be null

Example response

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

{
  "allowedRoles" : [ "ROLE_CUSTOMER_UPLOADER" ],
  "cognitoClientId" : "client-id-123",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "AI COM gmbh",
  "createdAt" : "2024-01-10T10:15:30Z",
  "createdBy" : "creator@profiforms.de",
  "createdByDisplay" : "creator@profiforms.de",
  "deletedAt" : null,
  "disabledAt" : "2024-01-10T11:15:30Z",
  "id" : "00000000-0000-0000-0000-000000000010",
  "lastAuthenticatedAt" : null,
  "lastRotatedAt" : null,
  "name" : "download integration",
  "rotationInProgress" : false,
  "rotationStartedAt" : null,
  "scopedTargets" : { },
  "status" : "INACTIVE"
}

Response fields

Path Type Description

id

UUID

Technical access id

companyId

UUID

Owning company id

companyName

String

Owning company display name

name

String

Technical access display name

status

TechnicalAccessStatus

Technical access status

cognitoClientId

String

Provisioned Cognito app client id

allowedRoles

Set<PublicRole>

Allowed roles for this technical access

scopedTargets

Map<PublicRole, Set<UUID>>

Target assignments grouped by technical role

createdBy

String

User who created the technical access

createdByDisplay

String

Display value for the technical access creator

createdAt

Instant

Technical access creation timestamp

lastAuthenticatedAt

Instant

Last successful client authentication timestamp

lastRotatedAt

Instant

Last secret rotation timestamp

rotationInProgress

boolean

Whether a staged secret rotation is currently in progress

rotationStartedAt

Instant

Timestamp when the current staged secret rotation was started

disabledAt

Instant

Disable timestamp

deletedAt

Instant

Delete timestamp

Delete technical access

Authentication: User authentication

Deleting a technical access removes its Cognito app client and marks the DWC record as DELETED for audit and authorization purposes. Deleted entries stay persisted, but they are hidden from the normal list endpoint.

DELETE /v1/technical-access/{technicalAccessId}
Parameter Description

technicalAccessId

Technical access id

Example request

DELETE /v1/technical-access/00000000-0000-0000-0000-000000000010 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: 624

{
  "allowedRoles" : [ "ROLE_CUSTOMER_UPLOADER" ],
  "cognitoClientId" : "client-id-123",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "AI COM gmbh",
  "createdAt" : "2024-01-10T10:15:30Z",
  "createdBy" : "creator@profiforms.de",
  "createdByDisplay" : "creator@profiforms.de",
  "deletedAt" : "2024-01-10T11:15:30Z",
  "disabledAt" : null,
  "id" : "00000000-0000-0000-0000-000000000010",
  "lastAuthenticatedAt" : null,
  "lastRotatedAt" : null,
  "name" : "download integration",
  "rotationInProgress" : false,
  "rotationStartedAt" : null,
  "scopedTargets" : { },
  "status" : "DELETED"
}

Response fields

Path Type Description

id

UUID

Technical access id

companyId

UUID

Owning company id

companyName

String

Owning company display name

name

String

Technical access display name

status

TechnicalAccessStatus

Technical access status

cognitoClientId

String

Provisioned Cognito app client id

allowedRoles

Set<PublicRole>

Allowed roles for this technical access

scopedTargets

Map<PublicRole, Set<UUID>>

Target assignments grouped by technical role

createdBy

String

User who created the technical access

createdByDisplay

String

Display value for the technical access creator

createdAt

Instant

Technical access creation timestamp

lastAuthenticatedAt

Instant

Last successful client authentication timestamp

lastRotatedAt

Instant

Last secret rotation timestamp

rotationInProgress

boolean

Whether a staged secret rotation is currently in progress

rotationStartedAt

Instant

Timestamp when the current staged secret rotation was started

disabledAt

Instant

Disable timestamp

deletedAt

Instant

Delete timestamp

Start staged secret rotation

Authentication: User authentication

Starting a secret rotation creates a new client secret for the existing Cognito app client and keeps the old secret valid until the rotation is explicitly completed. The response contains the new one-time secret and marks the technical access as rotationInProgress=true.

POST /v1/technical-access/{technicalAccessId}/rotate-secret
Parameter Description

technicalAccessId

Technical access id

Example request

POST /v1/technical-access/00000000-0000-0000-0000-000000000010/rotate-secret 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: 1120

{
  "oauth" : {
    "clientId" : "client-id-123",
    "clientSecret" : "rotated-secret-456",
    "grantType" : "client_credentials",
    "issuer" : "https://cognito-idp.eu-central-1.amazonaws.com/eu-central-1_testPoolId",
    "scopeSeparator" : " ",
    "supportedScopes" : [ "tower/customer-uploader" ],
    "tokenEndpointAuthMethod" : "client_secret_basic",
    "tokenUrl" : "https://tower-auth.dev.profiforms-dev.de/oauth2/token"
  },
  "technicalAccess" : {
    "allowedRoles" : [ "ROLE_CUSTOMER_UPLOADER" ],
    "cognitoClientId" : "client-id-123",
    "companyId" : "00000000-0000-0000-0000-000000000001",
    "companyName" : "AI COM gmbh",
    "createdAt" : "2024-01-10T10:15:30Z",
    "createdBy" : "creator@profiforms.de",
    "createdByDisplay" : "creator@profiforms.de",
    "deletedAt" : null,
    "disabledAt" : null,
    "id" : "00000000-0000-0000-0000-000000000010",
    "lastAuthenticatedAt" : null,
    "lastRotatedAt" : null,
    "name" : "download integration",
    "rotationInProgress" : true,
    "rotationStartedAt" : "2024-01-10T11:15:30Z",
    "scopedTargets" : { },
    "status" : "ACTIVE"
  }
}

Response fields

Path Type Description

oauth.clientId

Unknown

Provisioned Cognito app client id

oauth.clientSecret

Unknown

One-time newly generated Cognito app client secret

oauth.issuer

Unknown

JWT issuer for the technical access token

oauth.tokenUrl

Unknown

OAuth token endpoint for client credentials exchange

oauth.grantType

Unknown

Supported OAuth grant type

oauth.tokenEndpointAuthMethod

Unknown

Authentication method at the token endpoint

oauth.scopeSeparator

Unknown

Separator to use when requesting multiple scopes

oauth.supportedScopes

Unknown

OAuth scopes provisioned for this technical access

technicalAccess.id

Unknown

Technical access id

technicalAccess.companyId

Unknown

Owning company id

technicalAccess.companyName

Unknown

Owning company display name

technicalAccess.name

Unknown

Technical access display name

technicalAccess.status

Unknown

Technical access status

technicalAccess.cognitoClientId

Unknown

Provisioned Cognito app client id

technicalAccess.allowedRoles

Unknown

Allowed roles for this technical access

technicalAccess.scopedTargets

Unknown

Target assignments grouped by technical role

technicalAccess.createdBy

Unknown

User who created the technical access

technicalAccess.createdByDisplay

Unknown

Display value for the technical access creator

technicalAccess.createdAt

Unknown

Technical access creation timestamp

technicalAccess.lastAuthenticatedAt

Unknown

Last successful client authentication timestamp

technicalAccess.lastRotatedAt

Unknown

Last completed secret rotation timestamp

technicalAccess.rotationInProgress

Unknown

Whether a staged secret rotation is currently in progress

technicalAccess.rotationStartedAt

Unknown

Timestamp when the current staged secret rotation was started

technicalAccess.disabledAt

Unknown

Disable timestamp

technicalAccess.deletedAt

Unknown

Delete timestamp

Complete staged secret rotation

Authentication: User authentication

Completing the staged rotation invalidates the previous secret and clears the pending rotation marker on the technical access. After this step the old secret can no longer be used for token exchange.

POST /v1/technical-access/{technicalAccessId}/rotate-secret/complete
Parameter Description

technicalAccessId

Technical access id

Example request

POST /v1/technical-access/00000000-0000-0000-0000-000000000010/rotate-secret/complete 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: 623

{
  "allowedRoles" : [ "ROLE_CUSTOMER_UPLOADER" ],
  "cognitoClientId" : "client-id-123",
  "companyId" : "00000000-0000-0000-0000-000000000001",
  "companyName" : "AI COM gmbh",
  "createdAt" : "2024-01-10T10:15:30Z",
  "createdBy" : "creator@profiforms.de",
  "createdByDisplay" : "creator@profiforms.de",
  "deletedAt" : null,
  "disabledAt" : null,
  "id" : "00000000-0000-0000-0000-000000000010",
  "lastAuthenticatedAt" : null,
  "lastRotatedAt" : "2024-01-10T12:15:30Z",
  "name" : "download integration",
  "rotationInProgress" : false,
  "rotationStartedAt" : null,
  "scopedTargets" : { },
  "status" : "ACTIVE"
}

Response fields

Path Type Description

id

UUID

Technical access id

companyId

UUID

Owning company id

companyName

String

Owning company display name

name

String

Technical access display name

status

TechnicalAccessStatus

Technical access status

cognitoClientId

String

Provisioned Cognito app client id

allowedRoles

Set<PublicRole>

Allowed roles for this technical access

scopedTargets

Map<PublicRole, Set<UUID>>

Target assignments grouped by technical role

createdBy

String

User who created the technical access

createdByDisplay

String

Display value for the technical access creator

createdAt

Instant

Technical access creation timestamp

lastAuthenticatedAt

Instant

Last successful client authentication timestamp

lastRotatedAt

Instant

Last secret rotation timestamp

rotationInProgress

boolean

Whether a staged secret rotation is currently in progress

rotationStartedAt

Instant

Timestamp when the current staged secret rotation was started

disabledAt

Instant

Disable timestamp

deletedAt

Instant

Delete timestamp

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.concurrent_modification

Resource was modified concurrently

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.targets_not_assigned

Targets are not assigned

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

Technical access limit exceeded

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

Technical access not exists exception

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

Technical access has not assigned requested role

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

Technical access role not supported

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

Technical access secret rotation already in progress

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

Technical access secret rotation not in progress

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

Technical access status not supported

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

Authentication: User authentication, Technical authentication

/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

targetId

UUID

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

Must not be null

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

metadata

Map<String, String>

Optional additional metadata as string key/value pairs. At most 20 entries; keys must match [A-Za-z0-9._-]+ (max 128 chars) and be unique ignoring case; values must be non-blank, free of control characters (max 1024 chars); the whole map is limited by the S3 user-metadata size of 2048 bytes

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
Content-Length: 1029
Host: localhost:8080

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

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
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: 2082

{
  "b64DataKey" : null,
  "b64Iv" : "LSy3GLifoC7NiX46LhpVuQ==",
  "b64encryptedDataKey" : "Wf3g36oyGNErkbo7i8XLQichSejA+X4SEe3dXdBi/qbFKKtv8BQUAuu5bKBSCAUOBiI1ac6aKhzlR/F23k7v4mYchBvpBDqryXNiztd1DinjHUntJa7FhfL4631BrXMBgXsh0TJP3O24n8h+Sfd9AoDxA0XjkxGPRaDfd3TbL0qxvUs1cX/nBqX/pvhx8bAwQCNO3cip3xw7quOVBRMp/fWpepHjfCaKw+3X5OFivDQipnXN+IGwP3pWq0KrPuI5UvOkcgv2mh7ZIg3bEHNLuNWAePewlWrjA9bdxLiRABFhtpuovp10+U8jjuK4wT39DvmY0wd4495ry8h+qf4EuQ==",
  "clientWrapKeyEncryptionAlg" : null,
  "dataEncryptionAlgorithm" : "AES/GCM/NoPadding",
  "headers" : { },
  "id" : "<generated-uuid>",
  "jobAlreadyExists" : false,
  "s3Key" : "5c636c12-53de-44cb-a1e1-a22233253e1etest.txt",
  "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" ]
}

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' \
    -d '{"b64ClientWrapKey":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsLPIMhdi5953f1pgE732rcDFBvoDOFG8F6XPH3JF/3WLueyTcD8Ox7WG1gVgSmvc/Jp/nuOyRPhpqHcxnzNbjdtk95wm5+b+UF3lWQVCvWVnCYXg+XqoFLGbxsP3agveHQCPWEdh8Yv3SVKXylQIjbLaEBDpg8G5A9C6NtsfppN3OWvtI4Ccg3kuO0MT0b5vysJVkYx803UO9m0OrO0+md2U3t/WKJpgmvXFt/3Z5ZLPfTSYXVzeW3EduUqFY/l/XMnfsYufUozdHiemYdAvte4Ik60HpFIc+hnE2tHENVdy/dvdBpDfJeUeylIOVGuS7xcs0cjsSu4sMN6/UO2MJwIDAQAB","clientWrapKeyEncryptionAlg":"RSA/ECB/OAEPWithSHA-256AndMGF1Padding","dataEncryptionAlgorithm":"AES/GCM/NoPadding","dataKeyProviderType":"DOCXWORLD","fileName":"test.txt","fileSize":100,"jobCustomerReference1":"custom ref 1","jobCustomerReference2":"custom ref 2","jobCustomerReference3":"custom ref 3","jobCustomerReference4":"custom ref 4","jobCustomerReference5":"custom ref 5","jobCustomerReference6":"custom ref 6","metadata":{"costCenter":"4711"},"priority":"NORMAL","referenceId":"2341234345","supportedUploadFeatures":["MULTIPART","CS_CONTENT_ENCRYPTION"],"targetId":"a84397c4-fadd-4fb7-9145-7d580646cc86"}'

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

Authentication: User authentication, Technical authentication

/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

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

Response fields

Path Type Description

message

String

The message about the successful completion

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: 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 '{"etags":{},"processId":"processId"}'

Getting upload

Authentication: User authentication

/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

metadata

Map<String, String>

Additional metadata provided when the upload was created

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, CANCELLED, EXPIRED]

approvalCancelable

boolean

True if the upload currently has at least one waiting approval step that can be cancelled

approverId

String

Id of the approver

approverName

String

Name of the approver

approverEmail

String

EMail of the approver

downloads

List<DownloadResponse>

List of downloads for this upload

downloadable

boolean

File downloadable?

expectedFileFormat

FileFormat

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

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
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: 1448

{
  "approvalCancelable" : false,
  "approvalState" : "NOT_REQUIRED",
  "approverEmail" : null,
  "approverId" : null,
  "approverName" : null,
  "companyId" : "00000000-0000-0000-0000-111111111111",
  "created" : "2007-12-03T10:15:30Z",
  "customerContract" : "customerContract",
  "customerNumber" : "customerNumber",
  "downloads" : [ {
    "id" : "processId-download-1",
    "type" : "RESULT",
    "created" : "2007-12-03T10:15:30Z",
    "downloaded" : "2007-12-03T11:15:30Z",
    "downloadedBy" : "downloadUser123",
    "downloadedByClient" : "TestClient/1.0",
    "downloadedReferenceId" : "ref-processId-download-1"
  } ],
  "events" : [ {
    "created" : "2007-12-03T10:15:30Z",
    "action" : "SCHEDULED"
  }, {
    "created" : "2007-12-03T10:15:30Z",
    "action" : "UPLOADED"
  } ],
  "fileName" : "fileName",
  "fileSize" : 100,
  "idInSpooler" : null,
  "jobCustomerReference1" : "jobCustomerReference1",
  "jobCustomerReference2" : "jobCustomerReference2",
  "jobCustomerReference3" : "jobCustomerReference3",
  "jobCustomerReference4" : "jobCustomerReference4",
  "jobCustomerReference5" : "jobCustomerReference5",
  "jobCustomerReference6" : "jobCustomerReference6",
  "metadata" : { },
  "processId" : "processId",
  "referenceId" : "referenceId",
  "targetAbbreviation" : "targetAbbreviation",
  "targetId" : "16e7769c-0ce5-3de7-a39b-179deed0c396",
  "targetName" : "targetName",
  "uploaderType" : "USER",
  "userId" : "userId"
}

CURL request

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

Cancelling upload

A PUT request is used to cancel the currently active approval step of an upload. This endpoint does not delete the upload itself and does not roll back previous workflow steps. It can only be called while the upload is still in the WAITING_APPROVAL state. If the approval was already decided, expired, cancelled before, or no approval task exists for the upload, the request is rejected.

Authentication: User authentication, Technical authentication

/v1/uploads/{id}/cancel

Request fields

Path Type Description Constraints

message

String

Optional cancel message for the approval task

Size must be between 0 and 255 inclusive

Example request

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

{"message":"cancel message"}

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

fileName

String

Filename

jobState

JobState

Job-State. 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, CANCELLED, EXPIRED]

approvalCancelable

boolean

True if the upload currently has at least one waiting approval step that can be cancelled

approverId

String

Id of the approver

approverName

String

Name of the approver

approverEmail

String

EMail of the approver

metadata

Map<String, String>

Additional metadata provided when the upload was created

pdfValidationState

PdfValidationState

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

expectedFileFormat

FileFormat

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

downloads

List<DownloadResponse>

List of downloads for this upload

downloadable

boolean

File downloadable?

approvalTaskMessage

Unknown

Latest approval-task message

hasApprovalTaskMessage

boolean

Approval-Task message provided?

downloads[].id

String

Download id

downloads[].type

String

Download type

downloads[].created

Instant

Download creation timestamp

downloads[].downloaded

Instant

Download timestamp

downloads[].downloadedBy

String

User who downloaded the file

downloads[].downloadedByClient

String

Client that downloaded the file

downloads[].downloadedReferenceId

String

Download reference id

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: 641

{
  "approvalCancelable" : false,
  "approvalState" : "CANCELLED",
  "approvalTaskMessage" : null,
  "approverEmail" : null,
  "approverId" : null,
  "approverName" : null,
  "created" : "2007-12-03T10:15:30Z",
  "downloadable" : false,
  "downloads" : [ ],
  "expectedFileFormat" : "UNKNOWN",
  "fileName" : "fileName",
  "hasApprovalTaskMessage" : false,
  "jobState" : "SCHEDULED",
  "metadata" : { },
  "pdfValidationState" : "NOT_REQUIRED",
  "processId" : "processId",
  "referenceId" : "referenceId",
  "targetAbbreviation" : "targetAbbreviation",
  "targetId" : "16e7769c-0ce5-3de7-a39b-179deed0c396",
  "targetName" : "targetName"
}

CURL request

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

Authentication: User authentication

/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
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: 65

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

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

Authentication: User authentication

/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

(Deprecated: use jobStates instead) Filter by job state. Allowed values [SCHEDULED, UPLOADED, TRANSFER_FAILED, TRANSFERRED, DUPLICATED, DELETED, WAITING_FOR_COLLECT, COLLECTED]

jobStates

Filter by multiple job states. Can be specified multiple times. Allowed values [SCHEDULED, UPLOADED, TRANSFER_FAILED, TRANSFERRED, DUPLICATED, DELETED, WAITING_FOR_COLLECT, COLLECTED]

approvalStates

Filter by multiple approval states. Can be specified multiple times. Allowed values [REQUIRED, NOT_REQUIRED, WAITING_APPROVAL, APPROVED, REJECTED, CANCELLED, EXPIRED]

freeSearch

Free-text search across file name, target name, target ID, and process ID

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&jobStates=SCHEDULED&jobStates=UPLOADED&approvalStates=APPROVED&approvalStates=REJECTED&freeSearch=test&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
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: 1840

{
  "content" : [ {
    "approvalCancelable" : false,
    "approvalState" : "NOT_REQUIRED",
    "approvalTaskMessage" : null,
    "approverEmail" : null,
    "approverId" : null,
    "approverName" : null,
    "created" : "2007-12-03T10:15:30Z",
    "downloadable" : false,
    "downloads" : [ {
      "id" : "jobId-download-1",
      "type" : "RESULT",
      "created" : "2007-12-03T10:15:30Z",
      "downloaded" : "2007-12-03T11:15:30Z",
      "downloadedBy" : "downloadUser123",
      "downloadedByClient" : "TestClient/1.0",
      "downloadedReferenceId" : "ref-jobId-download-1"
    } ],
    "expectedFileFormat" : "UNKNOWN",
    "fileName" : "fileName",
    "hasApprovalTaskMessage" : false,
    "jobState" : "DUPLICATED",
    "metadata" : { },
    "pdfValidationState" : "NOT_REQUIRED",
    "processId" : "jobId",
    "referenceId" : "referenceId",
    "targetAbbreviation" : "targetAbbreviation",
    "targetId" : "16e7769c-0ce5-3de7-a39b-179deed0c396",
    "targetName" : "targetName"
  }, {
    "approvalCancelable" : false,
    "approvalState" : "NOT_REQUIRED",
    "approvalTaskMessage" : null,
    "approverEmail" : null,
    "approverId" : null,
    "approverName" : null,
    "created" : "2007-12-03T10:15:30Z",
    "downloadable" : false,
    "downloads" : [ ],
    "expectedFileFormat" : "UNKNOWN",
    "fileName" : "fileName2",
    "hasApprovalTaskMessage" : false,
    "jobState" : "DUPLICATED",
    "metadata" : { },
    "pdfValidationState" : "NOT_REQUIRED",
    "processId" : "jobId2",
    "referenceId" : "referenceId2",
    "targetAbbreviation" : "targetAbbreviation",
    "targetId" : "16e7769c-0ce5-3de7-a39b-179deed0c396",
    "targetName" : "targetName"
  } ],
  "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, CANCELLED, EXPIRED]

content[].approvalCancelable

boolean

True if the upload currently has at least one waiting approval step that can be cancelled

content[].approverId

String

Id of the approver

content[].approverName

String

Name of the approver

content[].approverEmail

String

EMail of the approver

content[].metadata

Map<String, String>

Additional metadata provided when the upload was created

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[].downloads

List<DownloadResponse>

List of downloads for this upload

content[].downloadable

boolean

File downloadable?

content[].approvalTaskMessage

Unknown

Latest approval-task message

content[].hasApprovalTaskMessage

boolean

Approval-Task message provided?

content[].downloads[].id

String

Download id

content[].downloads[].type

String

Download type

content[].downloads[].created

Instant

Download creation timestamp

content[].downloads[].downloaded

Instant

Download timestamp

content[].downloads[].downloadedBy

String

User who downloaded the file

content[].downloads[].downloadedByClient

String

Client that downloaded the file

content[].downloads[].downloadedReferenceId

String

Download reference id

CURL request

$ curl 'http://localhost:8080/v1/uploads?sort=jobState%2CDESC&sort=customerContract&page=0&size=10&jobState=DUPLICATED&jobStates=SCHEDULED&jobStates=UPLOADED&approvalStates=APPROVED&approvalStates=REJECTED&freeSearch=test&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

Authentication: User authentication

/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, CANCELLED, EXPIRED]

freeSearch

Filter by free search of filename, uploaderName, processId, or upload metadata

uploadStartPeriod

Filter by upload date (from). Format: ISO-8601 instant (e.g., 2007-12-03T10:15:30Z)

uploadEndPeriod

Filter by upload date (to). Format: ISO-8601 instant (e.g., 2007-12-03T10:15:30Z)

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: 2084

{
  "content" : [ {
    "approvalState" : "WAITING_APPROVAL",
    "approverEmail" : "approverEmail",
    "approverId" : "approver",
    "approverName" : "approverFirstName approverLastName",
    "downloads" : [ {
      "id" : "processId1-download-1",
      "type" : "RESULT",
      "created" : "2007-12-03T10:15:30Z",
      "downloaded" : "2007-12-03T11:15:30Z",
      "downloadedBy" : "downloadUser123",
      "downloadedByClient" : "TestClient/1.0",
      "downloadedReferenceId" : "ref-processId1-download-1"
    } ],
    "fileName" : "fileName",
    "id" : "00000000-0000-0000-0000-000000000001",
    "message" : null,
    "metadata" : { },
    "processId" : "processId1",
    "targetId" : "16e7769c-0ce5-3de7-a39b-179deed0c396",
    "targetName" : "targetName",
    "uploadCreated" : "2007-12-03T10:15:30Z",
    "uploaderEmail" : "uploaderEmail",
    "uploaderId" : "uploader",
    "uploaderName" : "uploaderFirstName uploaderLastName",
    "uploaderType" : "USER"
  }, {
    "approvalState" : "WAITING_APPROVAL",
    "approverEmail" : "approverEmail",
    "approverId" : "approver",
    "approverName" : "approverFirstName approverLastName",
    "downloads" : [ {
      "id" : "processId2-download-1",
      "type" : "RESULT",
      "created" : "2007-12-03T10:15:30Z",
      "downloaded" : "2007-12-03T11:15:30Z",
      "downloadedBy" : "downloadUser123",
      "downloadedByClient" : "TestClient/1.0",
      "downloadedReferenceId" : "ref-processId2-download-1"
    } ],
    "fileName" : "fileName",
    "id" : "00000000-0000-0000-0000-000000000001",
    "message" : null,
    "metadata" : { },
    "processId" : "processId2",
    "targetId" : "16e7769c-0ce5-3de7-a39b-179deed0c396",
    "targetName" : "targetName",
    "uploadCreated" : "2007-12-03T10:15:30Z",
    "uploaderEmail" : "uploaderEmail",
    "uploaderId" : "uploader",
    "uploaderName" : "uploaderFirstName uploaderLastName",
    "uploaderType" : "USER"
  } ],
  "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[].uploaderType

String

Type of the uploader. Possible values [USER, TECHNICAL_ACCESS]

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, CANCELLED, EXPIRED]

content[].message

String

Approval message

content[].metadata

Unknown

Additional metadata provided for the upload

content[].downloads

Unknown

List of downloads associated with the job

content[].downloads[].id

Unknown

Download ID

content[].downloads[].type

Unknown

Download type

content[].downloads[].created

Unknown

Creation timestamp

content[].downloads[].downloaded

Unknown

Download timestamp

content[].downloads[].downloadedBy

Unknown

User who downloaded

content[].downloads[].downloadedByClient

Unknown

Client id used for download

content[].downloads[].downloadedReferenceId

Unknown

External reference ID

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'

Getting approval-task by id

Authentication: User authentication

/v1/approval-tasks/{id}

Path parameters

GET /v1/approval-tasks/{id}
Parameter Description

id

id of the approval task

Example request

GET /v1/approval-tasks/00000000-0000-0000-0000-000000000000 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: 611

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

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

uploaderType

String

Type of the uploader. Possible values [USER, TECHNICAL_ACCESS]

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, CANCELLED, EXPIRED]

message

String

Approval message

metadata

Unknown

Additional metadata provided for the upload

downloads

Unknown

List of downloads associated with the job

downloads[].id

Unknown

Download ID

downloads[].type

Unknown

Download type

downloads[].created

Unknown

Creation timestamp

downloads[].downloaded

Unknown

Download timestamp

downloads[].downloadedBy

Unknown

User who downloaded

downloads[].downloadedByClient

Unknown

Client used for download

downloads[].downloadedReferenceId

Unknown

External reference ID

CURL request

$ curl 'http://localhost:8080/v1/approval-tasks/00000000-0000-0000-0000-000000000000' -i -X GET \
    -H 'X-PF-DWC-Requester-Role: ROLE_CUSTOMER_APPROVER'

Approve approval-tasks

Authentication: User authentication

/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","emailOptions":"CC_APPROVER","message":"message"}
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--

Example response

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

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

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

uploaderType

String

Type of the uploader. Possible values [USER, TECHNICAL_ACCESS]

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, CANCELLED, EXPIRED]

message

String

Approval message

metadata

Unknown

Additional metadata provided for the upload

downloads

Unknown

List of downloads associated with the job

downloads[].id

Unknown

Download ID

downloads[].type

Unknown

Download type

downloads[].created

Unknown

Creation timestamp

downloads[].downloaded

Unknown

Download timestamp

downloads[].downloadedBy

Unknown

User who downloaded

downloads[].downloadedByClient

Unknown

Client used for download

downloads[].downloadedReferenceId

Unknown

External reference ID

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

de.profiforms.docxworld.upload.error.server.upload_not_cancellable

Upload not cancellable exception

Company

Get company by ID

Authentication: User authentication

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: 939

{
  "id" : "00000000-0000-0000-0000-000000000001",
  "version" : 0,
  "name" : "Company Name",
  "technicalAccessLimit" : 0,
  "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"
      } ],
      "isActive" : false,
      "approvable" : false,
      "collectable" : false,
      "outputType" : "DW24",
      "fileType" : "PDF",
      "uploadType" : "JOB"
    } ],
    "isActive" : false
  } ]
}

Read companies

Authentication: User authentication

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: 6062

{
  "content" : [ {
    "id" : "00000000-0000-0000-0000-000000000001",
    "version" : null,
    "name" : "Company Name",
    "technicalAccessLimit" : 0,
    "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"
        } ],
        "isActive" : false,
        "approvable" : false,
        "collectable" : false,
        "outputType" : "DW24",
        "fileType" : "PDF",
        "uploadType" : "JOB"
      }, {
        "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"
        } ],
        "isActive" : false,
        "approvable" : false,
        "collectable" : false,
        "outputType" : "DW24",
        "fileType" : "RAW",
        "uploadType" : "SINGLE"
      } ],
      "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"
        } ],
        "isActive" : false,
        "approvable" : false,
        "collectable" : false,
        "outputType" : "DW24",
        "fileType" : "PDF",
        "uploadType" : "JOB"
      }, {
        "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"
        } ],
        "isActive" : false,
        "approvable" : false,
        "collectable" : false,
        "outputType" : "DW24",
        "fileType" : "RAW",
        "uploadType" : "SINGLE"
      } ],
      "isActive" : false
    } ]
  }, {
    "id" : "00000000-0000-0000-0000-000000000001",
    "version" : null,
    "name" : "Company Name",
    "technicalAccessLimit" : 0,
    "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"
        } ],
        "isActive" : false,
        "approvable" : false,
        "collectable" : false,
        "outputType" : "DW24",
        "fileType" : "PDF",
        "uploadType" : "JOB"
      }, {
        "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"
        } ],
        "isActive" : false,
        "approvable" : false,
        "collectable" : false,
        "outputType" : "DW24",
        "fileType" : "RAW",
        "uploadType" : "SINGLE"
      } ],
      "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"
        } ],
        "isActive" : false,
        "approvable" : false,
        "collectable" : false,
        "outputType" : "DW24",
        "fileType" : "PDF",
        "uploadType" : "JOB"
      }, {
        "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"
        } ],
        "isActive" : false,
        "approvable" : false,
        "collectable" : false,
        "outputType" : "DW24",
        "fileType" : "RAW",
        "uploadType" : "SINGLE"
      } ],
      "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

Authentication: User authentication

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

{
  "name" : "Company Name",
  "technicalAccessLimit" : 0,
  "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" : "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"
    } ]
  } ]
}

Request fields

Path Type Description Constraints

name

String

Company name. Must be unique(case insensitive)

Must not be blank

technicalAccessLimit

Integer

Maximum number of technical accesses for this company. Defaults to 0

Must be at most 100. Must be positive or zero

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, EMAIL_OUTPUT]

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: 939

{
  "id" : "00000000-0000-0000-0000-000000000001",
  "version" : 0,
  "name" : "Company Name",
  "technicalAccessLimit" : 0,
  "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"
      } ],
      "isActive" : false,
      "approvable" : false,
      "collectable" : false,
      "outputType" : "DW24",
      "fileType" : "PDF",
      "uploadType" : "JOB"
    } ],
    "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

technicalAccessLimit

Integer

Maximum number of technical accesses for the company

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, EMAIL_OUTPUT]

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: 124
Host: localhost:8080

{
  "name" : "Profiforms",
  "technicalAccessLimit" : 0,
  "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: 368

{
  "id" : "00000000-0000-0000-0000-000000000001",
  "version" : 0,
  "name" : "Profiforms",
  "technicalAccessLimit" : 0,
  "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: 177
Host: localhost:8080

{
  "name" : "Profiforms",
  "technicalAccessLimit" : 0,
  "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: 366

{
  "id" : "00000000-0000-0000-0000-000000000001",
  "version" : 0,
  "name" : "Profiforms",
  "technicalAccessLimit" : 0,
  "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

Authentication: User authentication

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

Update company settings request

Authentication: User authentication

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

{
  "technicalAccessLimit" : 100
}

Request fields

Path Type Description Constraints

technicalAccessLimit

Integer

Maximum number of technical accesses for this company. Allowed values: 0 to 100

Must be at most 100. Must be positive or zero. Must not be null

Response

See Example response

Adding customer numbers

Authentication: User authentication

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" : "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"
  } ]
}, {
  "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" : "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"
  } ]
} ]

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, EMAIL_OUTPUT]

[].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

Authentication: User authentication

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

Authentication: User authentication

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

Authentication: User authentication

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

Authentication: User authentication

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

Authentication: User authentication

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" : "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"
}, {
  "number" : "customerContract-2",
  "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"
} ]

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, EMAIL_OUTPUT]

[].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

Authentication: User authentication

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

Authentication: User authentication

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

Authentication: User authentication

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

Authentication: User authentication

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.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_approvable

Workflow is not approvable

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.deadline_email_required

Deadline notification email is required when deadline is set

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

Authentication: User authentication

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"
    } ],
    "isActive" : false,
    "approvable" : false,
    "collectable" : false,
    "outputType" : "DW24",
    "fileType" : "PDF",
    "uploadType" : "JOB"
  }, {
    "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"
    } ],
    "isActive" : false,
    "approvable" : false,
    "collectable" : false,
    "outputType" : "DW24",
    "fileType" : "PDF",
    "uploadType" : "JOB"
  } ],
  "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

Authentication: User authentication

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

{
  "customerContract" : "customerContract-1-1",
  "name" : "workflow 1",
  "abbreviation" : "W1",
  "description" : "description workflow 1",
  "approvalNeeded" : false,
  "escalationDeadlineNotificationEmail" : null,
  "escalationNotificationDeadline" : 0,
  "approversNotificationDeadline" : 0,
  "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

escalationDeadlineNotificationEmail

String

Email for escalation notifications. Required if escalationNotificationDeadline > 0

Must be a well-formed email address

escalationNotificationDeadline

int

Escalation deadline in days (0-30). 0 means disabled

Must be at least 0. Must be at most 30

approversNotificationDeadline

int

Deadline in days (0-30) for approver notification. 0 means disabled

Must be at least 0. Must be at most 30

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: 568

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

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]

escalationDeadlineNotificationEmail

String

Email for escalation notifications

escalationNotificationDeadline

int

Escalation deadline in days (0-30). 0 means disabled

approversNotificationDeadline

int

Deadline in days (0-30) for approver notification. 0 means disabled

externalReceiver.url

String

External receiver url

Update workflow meta-data request

Authentication: User authentication

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

Authentication: User authentication

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: 156
Host: localhost:8080

{
  "approvalNeeded" : true,
  "escalationDeadlineNotificationEmail" : null,
  "escalationNotificationDeadline" : 0,
  "approversNotificationDeadline" : 0
}

Request fields

Path Type Description Constraints

approvalNeeded

boolean

Workflow setting, if approval is needed.

escalationDeadlineNotificationEmail

String

Email for deadline notifications. Required if escalationNotificationDeadline > 0.

Must be a well-formed email address

escalationNotificationDeadline

int

Deadline in days (0-30). 0 means disabled.

Must be at least 0. Must be at most 30

approversNotificationDeadline

int

Escalation deadline in days (0-30). 0 means disabled.

Must be at least 0. Must be at most 30

Update workflow status request

Authentication: User authentication

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

Authentication: User authentication

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: 568

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

List workflows request

Authentication: User authentication

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: 1388

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

Target

Get target by ID

Authentication: User authentication

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: 723

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

List targets request

Authentication: User authentication

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: 1712

{
  "content" : [ {
    "id" : "00000000-0000-0000-0000-000000000001",
    "targetType" : "DEFAULT",
    "version" : null,
    "workflow" : {
      "abbreviation" : "W1",
      "approvalNeeded" : false,
      "approversNotificationDeadline" : 0,
      "companyId" : "00000000-0000-0000-0000-000000000001",
      "customerContract" : "customerContract-1-1",
      "description" : "description workflow 1",
      "encryptionAllowed" : true,
      "escalationDeadlineNotificationEmail" : null,
      "escalationNotificationDeadline" : 0,
      "externalReceiver" : {
        "url" : "https://external-receiver-url"
      },
      "fileType" : null,
      "id" : "00000000-0000-0000-0000-000000000001",
      "name" : "workflow 1",
      "status" : "ACTIVE",
      "version" : null
    }
  }, {
    "id" : "00000000-0000-0000-0000-000000000001",
    "targetType" : "DEFAULT",
    "version" : null,
    "workflow" : {
      "abbreviation" : "W1",
      "approvalNeeded" : false,
      "approversNotificationDeadline" : 0,
      "companyId" : "00000000-0000-0000-0000-000000000001",
      "customerContract" : "customerContract-1-1",
      "description" : "description workflow 1",
      "encryptionAllowed" : true,
      "escalationDeadlineNotificationEmail" : null,
      "escalationNotificationDeadline" : 0,
      "externalReceiver" : {
        "url" : "https://external-receiver-url"
      },
      "fileType" : null,
      "id" : "00000000-0000-0000-0000-000000000001",
      "name" : "workflow 1",
      "status" : "ACTIVE",
      "version" : null
    }
  } ],
  "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.escalationDeadlineNotificationEmail

String

Email for deadline notifications

workflow.escalationNotificationDeadline

int

Deadline in days (0-30). 0 means disabled

workflow.approversNotificationDeadline

int

Escalation deadline in days (0-30). 0 means disabled

workflow.externalReceiver.url

String

External receiver url

Download

List downloads request

Authentication: User authentication

GET /v1/downloads
Parameter Description

targets

Filter and return downloads for given targets.

customerContract

Filter and return downloads for given customer contract.

companyId

Filter and return downloads for given company ID.

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 target-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&customerContract=customerContract&companyId=00000000-0000-0000-0000-000000000001&referenceId=referenceId1&referenceId=referenceId2 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: 1698

{
  "content" : [ {
    "approverEmail" : null,
    "approverId" : null,
    "created" : "2121-01-31T11:17:33.456Z",
    "customerContract" : "42",
    "downloadLinkGenerated" : false,
    "downloaded" : "2121-01-31T11:27:33.456Z",
    "downloadedBy" : "downloader_42",
    "downloadedByClient" : "client_42",
    "downloadedReferenceId" : "downloadedReferenceId_42",
    "downloaderEmail" : "downloaderEmail_42",
    "fileName" : "download1",
    "id" : "<generated-uuid>",
    "metadata" : {
      "anotherKey" : "anotherValue",
      "anyKey" : "anyValue"
    },
    "referenceId" : "42",
    "size" : 42,
    "targetId" : "00000000-0000-0000-0000-000000000001",
    "targetName" : "targetName_42",
    "type" : "RESULT",
    "uploaderEmail" : null,
    "uploaderId" : null
  }, {
    "approverEmail" : null,
    "approverId" : null,
    "created" : "2121-01-31T11:17:33.456Z",
    "customerContract" : "42",
    "downloadLinkGenerated" : false,
    "downloaded" : "2121-01-31T11:27:33.456Z",
    "downloadedBy" : "downloader_42",
    "downloadedByClient" : "client_42",
    "downloadedReferenceId" : "downloadedReferenceId_42",
    "downloaderEmail" : "downloaderEmail_42",
    "fileName" : "download2",
    "id" : "<generated-uuid>",
    "metadata" : {
      "anotherKey" : "anotherValue",
      "anyKey" : "anyValue"
    },
    "referenceId" : "42",
    "size" : 42,
    "targetId" : "00000000-0000-0000-0000-000000000001",
    "targetName" : "targetName_42",
    "type" : "RESULT",
    "uploaderEmail" : null,
    "uploaderId" : 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 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[].downloadedBy

String

User-ID who downloaded the file

content[].downloaderEmail

String

Email of the downloader

content[].downloadedByClient

String

Client-ID who downloaded the file

content[].downloadedReferenceId

String

Reference-ID provided during download

content[].size

Long

Size of the download

content[].type

DownloadType

Type of the download

content[].uploaderId

String

User-ID of the uploader

content[].uploaderEmail

String

Email of the uploader

content[].approverId

String

User-ID of the approver

content[].approverEmail

String

Email of the approver

content[].metadata

Map<String, String>

Metadata of the download as key-value pairs

Get download

Authentication: User authentication

Example request

GET /v1/downloads/00000000-0000-0000-0000-000000000001 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: 714

{
  "approverEmail" : null,
  "approverId" : null,
  "created" : "2121-01-31T11:17:33.456Z",
  "customerContract" : "42",
  "downloadLinkGenerated" : false,
  "downloaded" : "2121-01-31T11:27:33.456Z",
  "downloadedBy" : "downloader_42",
  "downloadedByClient" : "client_42",
  "downloadedReferenceId" : "downloadedReferenceId_42",
  "downloaderEmail" : "downloaderEmail_42",
  "fileName" : "download1",
  "id" : "<generated-uuid>",
  "metadata" : {
    "anotherKey" : "anotherValue",
    "anyKey" : "anyValue"
  },
  "referenceId" : "42",
  "size" : 42,
  "targetId" : "00000000-0000-0000-0000-000000000001",
  "targetName" : "targetName_42",
  "type" : "RESULT",
  "uploaderEmail" : null,
  "uploaderId" : null
}

Create technical download draft

Creates a new draft download and returns a presigned upload URL.

Authentication: Technical authentication

This endpoint is intended for technical access only:

  • it does not use X-PF-DWC-Requester-Role;

  • it creates the Download draft before the file is uploaded to S3.

When the file is later written to S3, the object-created handler finalizes the existing draft. If the uploaded object metadata does not match the draft metadata, the draft is marked as error and is not processed further.

Example request

POST /v1/downloads/ HTTP/1.1
Content-Type: application/json;charset=UTF8
Content-Length: 168
Host: localhost:8080

{"downloadType":"RESULT","fileName":"generated.xml","metadata":{"sourceSystem":"sap"},"referenceId":"external-ref-42","targetId":"00000000-0000-0000-0000-000000000001"}

Request fields

Path Type Description Constraints

targetId

UUID

Target identifier controlled by OPA.

Must not be null

fileName

String

Original filename for the created download.

Must not be blank

downloadType

DownloadType

Download type to be created.

Must not be null

referenceId

String

Caller-side reference id.

Must not be blank

metadata

Object

Additional metadata copied. Keys must match [A-Za-z0-9._-]+, remain unique ignoring case, and the base64 encoded metadata footprint must stay within 2 KB.

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: 218

{
  "headers" : {
    "x-amz-meta-x-v2-pf-736f7572636553797374656d" : "c2Fw",
    "x-amz-meta-contractnumber" : "contract-number-company2-1-1"
  },
  "id" : "<generated-uuid>",
  "uploadUrl" : "https://s3.aws/upload"
}

Response fields

Path Type Description

id

String

Identifier of the created draft download.

headers

Object

Headers that must be sent unchanged with the upload request. Additional metadata uses versioned, case-preserving S3 headers and Base64-encoded values.

uploadUrl

String

Presigned upload URL for the download payload.

Authentication: User authentication

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: 386

{
  "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",
  "id" : "<generated-uuid>"
}

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.

Authentication: User authentication

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: 714

{
  "approverEmail" : null,
  "approverId" : null,
  "created" : "2121-01-31T11:17:33.456Z",
  "customerContract" : "42",
  "downloadLinkGenerated" : false,
  "downloaded" : "2121-01-31T11:22:33.456Z",
  "downloadedBy" : "downloader_42",
  "downloadedByClient" : "client_42",
  "downloadedReferenceId" : "downloadedReferenceId_42",
  "downloaderEmail" : "downloaderEmail_42",
  "fileName" : "download1",
  "id" : "<generated-uuid>",
  "metadata" : {
    "anotherKey" : "anotherValue",
    "anyKey" : "anyValue"
  },
  "referenceId" : "42",
  "size" : 42,
  "targetId" : "00000000-0000-0000-0000-000000000001",
  "targetName" : "targetName_42",
  "type" : "RESULT",
  "uploaderEmail" : null,
  "uploaderId" : null
}

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: 466

{
  "debugMessages" : [ "Download with id '00000000-0000-0000-0000-000000000001' was already marked as acknowledged by client 'spooler_1'" ],
  "id" : "<generated-uuid>",
  "message" : "Download was marked as saved already",
  "messageCode" : "de.profiforms.docxworld.connect.download.error.client.download_already_saved",
  "path" : "/v1/downloads/00000000-0000-0000-0000-000000000001/acknowledge",
  "status" : "CONFLICT",
  "timestamp" : "<generated-timestamp>"
}

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.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.target_customer_contract_missing

Target customer contract missing

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

Download not available

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

Technical access required

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

Target not exists exception

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

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.validation

Validation error

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

Unexpected internal error

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

Client error