Automation API specification
V2 - /api/v2
openapi: 3.0.3
info:
title: SWF Automation API - v2
description: Issue requests for file signing.
contact:
name: PhenixID Support
url: https://www.phenixid.se/support/
email: [email protected]
version: 3.0.0
servers:
- url: /api/v2
description: Base path
- url: http://localhost:8081/api/v2
description: Local development server
paths:
/tasks:
post:
summary: Create a task
description: Create a new task
operationId: createTask
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
responses:
200:
description: The created task
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
400:
description: Bad input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/tasks/:taskId:
get:
summary: Fetch a task
operationId: fetchTask
responses:
200:
description: The task
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
400:
description: Bad input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
put:
summary: Update a task
operationId: updateTask
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
responses:
200:
description: The updated task
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
400:
description: Bad input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
responses:
200:
description: Deletion was completed
content:
text/plain:
schema:
type: string
example: deleted
400:
description: Bad input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/files:
post:
summary: Create file
operationId: createFile
responses:
200:
description: The file that was created
content:
application/json:
schema:
$ref: '#/components/schemas/Validation'
400:
description: Bad input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/tasks/:taskId/files:
get:
summary: Get task file IDs
operationId: getFileIds
responses:
200:
description: The active file IDs
content:
application/json:
schema:
properties:
fileIds:
type: array
description: An array of the active file IDs
example: [7a65e252-fb12-4e10-998e-fd413c565723]
400:
description: Bad input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/tasks/:taskId/file/:fileId:
get:
summary: Get specific file
operationId: getFile
responses:
200:
description: Get a specific file
content:
application/octet-stream:
schema:
description: PDF file
type: string
format: binary
400:
description: Bad input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/tasks/:taskId/files/zip:
get:
summary: Get zip file with all active files
operationId: getZip
responses:
200:
description: Get zip file
content:
application/octet-stream:
schema:
description: Zip file
type: string
format: binary
400:
description: Bad input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Task:
type: object
properties:
title:
type: string
description: The title of the task
example: Task title
dueDate:
type: string
description: Due date of the task. Needs to be the current day and onward
example: 2025-12-12
creator:
$ref: '#/components/schemas/User'
files:
type: object
properties:
id:
type: string
description: The ID of the file
example: 17e76e5b-3c26-4654-b212-eb7b6275677f
toBeSigned:
type: boolean
description: If it should be signed or not
example: true
signers:
type: array
items:
$ref: '#/components/schemas/User'
User:
type: object
properties:
identifier:
type: string
description: The identifier from PAS. Will be used as identifier for logins
example: uid=john.doe
firstName:
type: string
description: The first name of the user
example: John
lastName:
type: string
description: The last name of the user
example: Doe
email:
type: string
description: The email of the user
example: [email protected]
source:
type: string
description: The source of the user. INTERNAL/EXTERNAL
example: INTERNAL
Validation:
type: array
items:
$ref: '#/components/schemas/ValidationResult'
ValidationResult:
type: object
properties:
fileName:
type: string
description: The name of the file
example: my-file.pdf
validationResult:
type: object
properties:
id:
type: string
description: The ID of the file
example: b96b54d1-ac10-4b0f-a573-3256d07eae5b
status:
type: integer
description: The validation status
example: 0
message:
type: string
description: Validation message
example: The file does not have the required format
Error:
type: object
properties:
error:
type: object
description: An error wrapper object
properties:
localizationKey:
type: string
description: The localization key
example: noFile
Click to copy
V1 - /api/document_signing
openapi: 3.0.3
info:
title: SWF Automation API
description: Issue requests for document signing.
contact:
name: PhenixID Support
url: https://www.phenixid.se/support/
email: [email protected]
version: 3.0.0
servers:
- url: /api/document_signing
description: Base path
- url: http://localhost:8081/api/document_signing
description: Local development server
paths:
/orders:
post:
summary: Create a signing order.
description: |
Issue a new signing order
operationId: addSigningOrder
requestBody:
content:
multipart/form-data:
encoding:
signers:
style: form
explode: true
schema:
required:
- dueDate
- signer
- solicitor
- title
properties:
document:
type: string
description: >-
PDF document to be signed. This parameter is incompatible
with `fileId`.
format: binary
fileId:
type: string
format: uuid
description: >-
Id of a document. This parameter is incompatible with
`document`.
title:
type: string
description: Order title
description:
type: string
description: Order description
dueDate:
type: string
description: Due date for signers to sign the document
format: date
linkType:
type: integer
enum:
- 0
- 1
description: Where to send signers. 0 Workflow service or 1 Signing Service.
inviteUrlTarget:
type: string
enum:
- SWF
- SIGN_SERVICE
description: Same as linkType
convertNonValidDocuments:
type: boolean
description: An option to convert non-valid documents to PDF/A. Use with caution since the file conversion service might not always produce satisfactory file conversions.
completionNextTarget:
type: string
description: Option to redirect users with `inviteUrlTarget` set to `SIGN_SERVICE` to a specific URL.
solicitor:
$ref: '#/components/schemas/PersonIdentifier'
signer:
$ref: '#/components/schemas/PersonIdentifier'
tags:
type: array
description: Can only be defined using one form property
example: '[{"name":"tagName","displayText":"displayText","type":"boolean","value":"true"}]'
items:
$ref: '#/components/schemas/Tag'
option:
$ref: '#/components/schemas/Option'
required: true
responses:
'200':
description: The id of the created order
content:
text/plain:
schema:
$ref: '#/components/schemas/SigningOrderId'
'400':
description: Bad input
content:
text/plain:
schema:
type: string
example: "Illegal Argument: <details>"
/orders/{orderId}:
get:
summary: Get signing order.
description: Get a document signing order by ID.
operationId: getSigningOrder
parameters:
- name: orderId
in: path
description: Signing order ID
required: true
schema:
$ref: '#/components/schemas/SigningOrderId'
responses:
'200':
description: Search results matching criteria
content:
application/json:
schema:
$ref: '#/components/schemas/SigningOrder'
'400':
description: bad input
content:
text/plain:
schema:
type: string
example: "Illegal Argument: <details>"
'404':
description: order not found
content:
text/plain:
schema:
type: string
example: "Not Found: <details>"
delete:
summary: Delete signing order.
description: Delete a signing order with an orderId.
operationId: deleteSigningOrder
parameters:
- name: orderId
in: path
description: Signing order ID
required: true
schema:
$ref: '#/components/schemas/SigningOrderId'
responses:
'202':
description: Delete operation accepted. The order has been deleted. And the document has been scheduled to be deleted
content:
text/plain:
schema:
$ref: '#/components/schemas/SigningOrderId'
'400':
description: bad input
content:
text/plain:
schema:
type: string
example: "Invalid UUID string"
'404':
description: order not found
content:
text/plain:
schema:
type: string
example: "Not Found: <details>"
/orders/{orderId}/state:
get:
summary: Get order state.
description: Get the current state of a document signing order, by ID.
operationId: getOrderState
parameters:
- name: orderId
in: path
description: Signing order ID
required: true
schema:
$ref: '#/components/schemas/SigningOrderId'
responses:
'200':
description: success
content:
text/plain:
schema:
$ref: '#/components/schemas/SigningOrderStatus'
'400':
description: Bad input
content:
text/plain:
schema:
type: string
example: "Illegal Argument: <details>"
'404':
description: Signing order not found
content:
text/plain:
schema:
type: string
example: "Not Found: <details>"
put:
summary: Cancel order
description: Cancel order
operationId: cancelOrder
parameters:
- name: orderId
in: path
description: Signing order ID
required: true
schema:
$ref: '#/components/schemas/SigningOrderId'
responses:
'200':
description: Order is cancelled
'400':
description: Bad input
content:
text/plain:
schema:
type: string
example: "Illegal Argument: <details>"
'404':
description: Signing order not found
content:
text/plain:
schema:
type: string
example: "Not Found: <details>"
/orders/{orderId}/dueDate:
put:
summary: Update due date
description: Update due date
operationId: updateDueDate
parameters:
- name: orderId
in: path
description: Signing order ID
required: true
schema:
$ref: '#/components/schemas/SigningOrderId'
- name: dueDate
in: query
description: Due date for signers to sign the document
required: true
schema:
type: string
format: date
responses:
'200':
description: Order due date updated
'400':
description: Bad input
content:
text/plain:
schema:
type: string
example: "Illegal Argument: <details>"
'404':
description: Signing order not found
content:
text/plain:
schema:
type: string
example: "Not Found: <details>"
/orders/{orderId}/description:
put:
summary: Update description
description: Update description
operationId: updateDescription
parameters:
- name: orderId
in: path
description: Signing order ID
required: true
schema:
$ref: '#/components/schemas/SigningOrderId'
requestBody:
content:
multipart/form-data:
schema:
required:
- description
properties:
description:
type: string
description: New order description.
responses:
'200':
description: Order description updated
'400':
description: Bad input
content:
text/plain:
schema:
type: string
example: "Illegal Argument: <details>"
'404':
description: Signing order not found
content:
text/plain:
schema:
type: string
example: "Not Found: <details>"
/orders/{orderId}/remind:
put:
summary: Notify all pending signers
description: Notify all pending signers. They will all be reminded about the pending signing order.
operationId: remind
parameters:
- name: orderId
in: path
description: Signing order ID
required: true
schema:
$ref: '#/components/schemas/SigningOrderId'
responses:
'200':
description: Notifications are sent.
'400':
description: Bad input or illegal signing order state
content:
text/plain:
schema:
type: string
example: "Illegal Argument: <details>"
'404':
description: Signing order not found
content:
text/plain:
schema:
type: string
example: "Not Found: <details>"
/orders/{orderId}/signers:
put:
summary: Update signers
description: Add or remove signers from order
operationId: updateSigners
parameters:
- name: orderId
in: path
description: Signing order ID
required: true
schema:
$ref: '#/components/schemas/SigningOrderId'
requestBody:
content:
multipart/form-data:
encoding:
signers:
style: form
explode: true
schema:
required:
- signer
properties:
signer:
type: array
items:
$ref: '#/components/schemas/PersonIdentifier'
option:
type: object
items:
$ref: '#/components/schemas/Option'
required: true
responses:
'200':
description: Order signers updated
'400':
description: Bad input or illegal order state
content:
text/plain:
schema:
type: string
example: "Illegal Argument: <details>"
'404':
description: Signing order or signers not found
content:
text/plain:
schema:
type: string
example: "Not Found: <details>"
/orders/{orderId}/document:
get:
summary: Get order document
description: Get the current document as PDF, by order ID. If multiple documents, the endpoint will throw an error. Use below endpoints instead
deprecated: true
operationId: getOrderDocument
parameters:
- name: orderId
in: path
description: Signing order ID
required: true
schema:
$ref: '#/components/schemas/SigningOrderId'
responses:
'200':
description: Document downloaded
content:
application/octet-stream:
schema:
description: PDF file
type: string
format: binary
'400':
description: Bad input
content:
text/plain:
schema:
type: string
example: "Illegal Argument: <details>"
'404':
description: Signing order not found
content:
text/plain:
schema:
type: string
example: "Not Found: <details>"
/orders/{orderId}/documents:
get:
summary: Get document IDs
description: Get active document IDs for the order.
operationId: getOrderDocumentIds
parameters:
- name: orderId
in: path
description: Signing order ID
required: true
schema:
$ref: '#/components/schemas/SigningOrderId'
responses:
'200':
description: Document IDs
content:
application/json:
schema:
type: object
properties:
documentIds:
description: List of document IDs
type: array<uuid>
'400':
description: Bad input
content:
text/plain:
schema:
type: string
example: "Illegal Argument: <details>"
'404':
description: Signing order not found
content:
text/plain:
schema:
type: string
example: "Not Found: <details>"
/orders/{orderId}/document/{documentId}:
get:
summary: Get document
description: Get active document
operationId: getOrderDocumentById
parameters:
- name: orderId
in: path
description: Signing order ID
required: true
schema:
$ref: '#/components/schemas/SigningOrderId'
- name: documentId
in: path
description: Document ID
required: true
schema:
type: string
format: uuid
example: e157033e-3d4d-457e-8b5c-fec79cc6ceb3
responses:
'200':
description: Document downloaded
content:
application/octet-stream:
schema:
description: PDF file
type: string
format: binary
'400':
description: Bad input
content:
text/plain:
schema:
type: string
example: "Illegal Argument: <details>"
'404':
description: Signing order not found
content:
text/plain:
schema:
type: string
example: "Not Found: <details>"
/orders/{orderId}/documents/zip:
get:
summary: Get document zip file
description: Get active document in zip file
operationId: getOrderDocumentZip
parameters:
- name: orderId
in: path
description: Signing order ID
required: true
schema:
$ref: '#/components/schemas/SigningOrderId'
responses:
'200':
description: Zip file downloaded
content:
application/octet-stream:
schema:
description: Zip file
type: string
format: binary
'400':
description: Bad input
content:
text/plain:
schema:
type: string
example: "Illegal Argument: <details>"
'404':
description: Signing order not found
content:
text/plain:
schema:
type: string
example: "Not Found: <details>"
post:
summary: Update order document.
description: Update the current document pertaining to a document signing order, by ID.
operationId: updateOrderDocument
parameters:
- name: orderId
in: path
description: Signing order ID
required: true
schema:
$ref: '#/components/schemas/SigningOrderId'
requestBody:
content:
multipart/form-data:
schema:
required:
- document
properties:
document:
type: string
description: New order document.
format: binary
required: true
responses:
'200':
description: Document uploaded
'400':
description: Bad input
content:
text/plain:
schema:
type: string
example: "Illegal Argument: <details>"
'404':
description: Signing order not found
content:
text/plain:
schema:
type: string
example: "Not Found: <details>"
/documents:
post:
summary: Create document
description: Create document and validate it. The endpoint supports adding multiple documents
operationId: createDocument
requestBody:
content:
multipart/form-data:
schema:
required:
- document
properties:
document:
type: string
description: The document
format: binary
responses:
'200':
description: Document uploaded and validated
content:
application/json:
schema:
type: array
items:
properties:
fileName:
type: string
description: The name of the file
example: contract.pdf
validationResult:
$ref: '#/components/schemas/ValidationResult'
/anonymize:
post:
summary: Anonymize User
description: >-
Anonymize user in the database.
Choose one of the properties to identify the user; `internalId`, `externalId` or `ldapSearch`
operationId: anonymizeUser
requestBody:
content:
multipart/form-data:
schema:
properties:
internalId:
type: string
description: User internal id which is an UUID. E.g. "256FEDCB-CC59-435B-B45B-D915F7C7A04A"
externalId:
type: string
description: User external id. E.g. "INTERNAL:jane.doe" or "EXTERNAL:200001011907", etc.
ldapSearch:
$ref: '#/components/schemas/PersonIdentifier'
required: true
responses:
'200':
description: User has been anonymized
'400':
description: Bad input or User has pending orders
content:
text/plain:
schema:
type: string
example: "Illegal Argument: <details> or Illegal Query"
'404':
description: User was not found
content:
text/plain:
schema:
type: string
example: "Not Found: <details>"
/validate/{orderId}:
get:
summary: Validate signatures. Requires configuration in both SWF and PAS
description: It validates signatures by forwarding the document in the specified order to PAS, which subsequently employs the PDFSignatureStatusValve. Requires configuration in both SWF and PAS.
operationId: validateSignatures
parameters:
- name: orderId
in: path
description: Signing order ID
required: true
schema:
$ref: '#/components/schemas/SigningOrderId'
responses:
'200':
description: Signature validity.
content:
application/json:
schema:
$ref: '#/components/schemas/SignaturesReport'
'400':
description: Bad input or Validation is not configured for SWF
content:
text/plain:
schema:
type: string
example: "Illegal Argument: <details>"
'404':
description: Signing order not found
content:
text/plain:
schema:
type: string
example: "Not Found: <details>"
/documents/{documentId}/convert:
post:
summary: Converts document. Requires file conversion service
description: Endpoint utilizing a file conversion service. This generates a converted file but for the document to be connected to the order the document conversion has to be approved, using the convert approve endpoint. For more information, read the documentation on File Conversion
operationId: convertEndpoint
parameters:
- name: documentId
in: path
description: ID of the document that needs to be converted
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Document was converted
content:
application/json:
schema:
type: object
properties:
fileName:
type: string
description: The file name of the document
example: contract.pdf
file:
type: object
format: byte array
description: The converted file, base64 encoded
validationResult:
$ref: '#/components/schemas/ValidationResult'
/documents/{documentId}/convert/approve:
post:
summary: Converts document. Requires file conversion service
description: Conversion approval endpoint. Will set file conversion status to APPROVED
operationId: approvalEndpoint
parameters:
- name: documentId
in: path
description: ID of the document that needs to be converted
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Document was converted
content:
application/json:
schema:
type: object
properties:
fileName:
type: string
description: The file name of the document
example: contract.pdf
file:
type: object
format: byte array
description: The converted file, base64 encoded
validationResult:
$ref: '#/components/schemas/ValidationResult'
/nextTarget/test:
post:
summary: Test redirect URLs
description: An endpoint for testing what completionNextTargets can be used
operationId: nextTargetTest
parameters:
- name: nextTarget
in: query
description: The domain to test
required: true
schema:
type: string
example: https://www.phenixid.se/
responses:
'200':
description: The matcher result. If true, the URL matches the configured `completionNextTarget`.
content:
text/plain:
schema:
type: string
example: "Result: true"
components:
schemas:
SigningOrder:
type: object
properties:
type:
type: string
description: Will always have the same value
example: signing_order
fileName:
type: string
description: Document file name. If multiple document, file names are separated by a comma and space (", "). Deprecated, use `fileNames`
example: contract.pdf / contract.pdf, appendix.pdf
fileNames:
type: string
description: Document file name. If multiple document, file names are separated by a comma and space (", ")
example: contract.pdf / contract.pdf, appendix.pdf
documentType:
type: string
description: Always PDF
example: PDF
documentId:
type: string
format: uuid
description: Document ID. If multiple documents, this is only the first document ID. Deprecated, use `documentIds`
example: 49a9ff61-811e-40a4-9f4f-81defd283ae0
documentIds:
type: string
description: All document IDs, separated by a comma
example: 49a9ff61-811e-40a4-9f4f-81defd283ae0
linkType:
type: integer
description: Sign link will point to noapp(1). Deprecated, use `inviteUrlTarget`
example: 1
inviteUrlTarget:
type: string
description: Where the invite URL should direct. Possible values are `SWF` and `SIGN_SERVICE`
example: SWF
id:
type: string
format: uuid
description: The order ID
example: d290f1ee-6c54-4b01-90e6-d701748f0851
categories:
type: array
example:
- CreateApplicationAccess
items:
type: string
solicitor:
$ref: '#/components/schemas/Person'
title:
type: string
description: Title of order
example: Employment Contract
description:
type: string
description: Description of order
example: An employment contract for Ben Bitdiddle
created:
type: integer
format: int64
description: When the order was created. Expressed in epoch milliseconds
example: 1631609625460
dueDate:
type: integer
format: int64
description: The due date of the order
example: 1631836800000
requestedSigners:
type: array
description: The signers that are requested to sign the document(s)
items:
$ref: '#/components/schemas/Person'
actions:
type: array
description: The actions (signatures, rejects etc) of the order
items:
$ref: '#/components/schemas/Action'
contentType:
type: string
description: Always PDF
example: PDF
status:
$ref: '#/components/schemas/SigningOrderStatus'
cancelMessage:
type: string
example: Removed invalid order
tags:
type: array
description: Order categories. Check documentation for more information
items:
$ref: '#/components/schemas/Tag'
Action:
required:
- type
- user
type: object
properties:
user:
$ref: '#/components/schemas/Person'
created:
type: string
nullable: true
description: Local date time for the action
example: '2019-10-02T20:26:49'
type:
type: string
example: REJECTED
enum:
- PENDING
- SIGNED
- REJECTED
- CREATED
- QUEUED
message:
type: string
nullable: true
example: Order was rejected
Person:
required:
- id
- mail
type: object
properties:
id:
type: string
format: uuid
example: d290f1ee-6c54-4b01-90e6-d701748f0851
firstName:
type: string
example: Ben
lastName:
type: string
example: Bitdiddle
name:
type: string
example: Ben Bitdiddle
mail:
type: string
example: [email protected]
mobile:
type: string
example: +46700000000
priorityGroup:
type: integer
example: 3
source:
type: string
example: INTERNAL
action:
type: string
example: PENDING
role:
type: string
enum:
- SIGNER
- SIGNER_DOWNLOADER
- SOLICITOR
PersonIdentifier:
type: object
properties:
source:
type: string
description: >-
Will be passed to the backend query service, for looking up the
corresponding user.
example: INTERNAL
enum:
- INTERNAL
- EXTERNAL
- EMAIL
identifier:
type: string
description: >-
Will be passed to the backend query service, for looking up the
corresponding user.
example: sAMAccountName=ben,dc=example,dc=org
priorityGroup:
type: integer
example: 3
attributes:
$ref: '#/components/schemas/PersonAttributes'
PersonAttributes:
type: object
properties:
firstName:
type: object
properties:
name:
type: string
value:
type: string
lastName:
type: object
properties:
name:
type: string
value:
type: string
mail:
type: object
properties:
name:
type: string
value:
type: string
mobile:
type: object
properties:
name:
type: string
value:
type: string
description: >-
User attributes, e.g. email, mobile etc. These attributes might override
looked up attributes, or might be ignored. For example, a provided email
is used if the backend lookup does not provide any email, and ignored if
the lookup do provide an email.
Tag:
type: object
required:
- name
- displayText
- type
- value
properties:
name:
type: string
description: Name of the tag.
displayText:
type: string
description: the screen label. Optionally using a translation identifier.
type:
type: string
pattern: '^(enum|boolean)$'
description: Must be one of "enum" or "boolean"
value:
type: string
description: the words "true" or "false" if the type is boolean. Any string if type is enum.
description:
type: string
description: will set the description text as a tooltip
Option:
type: object
description: |
Can be set multiple times in a multipart/form-data.
Example: name: notifyAllSigners, value: true. This will notify all signers when the errand is signed by everybody.
required:
- name
- value
properties:
name:
type: string
description: option name, E.g. notifyAllSigners
value:
type: boolean
description: state of the option. E.g. true
SignaturesReport:
type: object
description: Signature validity report
properties:
orderId:
type: string
description: The ID of the order
documents:
type: array
description: An array of documents
items:
properties:
changedaftersigning:
type: boolean
description: Flag indicating if the PDF was changed after signing
signatures:
type: array
description: An array of signatures.
items:
properties:
who:
type: string
description: Signer subject CN
when:
type: string
format: date-time
description: Signing date-time in ISO 8601 format
intact:
type: boolean
description: Signing intact, i.e., correct
trusted:
type: boolean
description: Certificate used for signing issued from a trusted CA
SigningOrderStatus:
type: string
example: ACCEPTED
enum:
- PENDING
- ACCEPTED
- REJECTED
- CANCELLED
- EXPIRED
- QUEUED
SigningOrderId:
type: string
format: uuid
example: dcfdb952-b592-4866-81b3-5806bf25b45f
ValidationResult:
type: object
description: The validation result of the new converted file
properties:
id:
type: string
format: uuid
description: The ID of the document
status:
type: integer
description: File status. 0 = valid, 1 = warning, 2 = error
message:
type: string
description: If the file is non valid, the reason will be presented here
Click to copy