Automation API
Overview
The Automation API is a REST-based HTTP API that exposes the following functions for an api consumer, such as an external application:
- Create a signing order
- Read a signing order
- Get the status of a signing order
- Download a signed document
A technical documentation of the Automation API can be found here: https://app.swaggerhub.com/apis-docs/PhenixID/swf-automation-api
The API is disabled by default. Refer to configuration documentation for instructions on how to enable it.
Important: the Automation API endpoint is not authenticated in any way. Before enabling the Automation API, please make sure that endpoint is secured externally.
PhenixID recommends to use a load balancer or proxy in front of the API. The LB/proxy should accommodate SSL termination and mutual TLS (SSL client certificate authentication). The LB/proxy should then forward the traffic to the API endpoint.
The CURL examples below are targeted to an endpoint without authentication. To add SSL Client certificate authentication, the examples must be changed to target a https-endpoint and with two additional parameters, key
(private key) and cert
(certificate).
Example extract:
POST https://signing.phenixid.net/orders \
--key /path/to/private.key \
--cert /path/to/public.crt \
.
.
.
Create a signing order
To create a signing order, a POST
request is sent to /orders
with the following form-data parameters:
-
title
- The title of the signing order. (text) -
description
- The description of the signing order (text) -
dueDate
- The deadline of the signing order (text in format YYYY-MM-DDThh:mm:ss) -
upload
- The pdf document to be signed (file/binary) -
solicitor
- Who will be the creator/owner of the signing order. (text/json object) -
signers
- The requested signer(s) of the document. (text/json object)
The json object used for solicitor and signers contains these properties:
- source - INTERNAL or EXTERNAL.
INTERNAL -> Employees, consultants or other users present in the organization user directory, such as AD.
EXTERNAL -> Users not present in the organization, such as citizens or business partners. - identifier - Key to identify a signed.
For external users, this should be the ssid (personal number) only.
For internal users, this should include a matching attribute (attribute=userid, for example sAMAccountName=cborgstrom). Consult your Signing workflow administrator for the correct attribute and userid-string to use. - attributes - json array with additional attributes about the signer. Attributes in the request will be used only if the user lookup does not yield any result for that attribute.
Example:
{"source":"EXTERNAL","identifier":"198603052385","attributes":{"mail":{"value":"[email protected]"},"mobile":{"value":"+46700000000"}}}
This is an example of how to create a signing order using cURL:
curl --location -vvv --request POST 'http://3.121.160.99:8081/api/document_signing/orders' \
-F 'title="A new signing order"' \
-F 'description="This order was automatically generated"' \
-F 'upload=@"/Users/me/Documents/signthisplease.pdf"' \
-F 'dueDate="2021-05-01T00:00:00"' \
-F 'solicitor="{\"source\":\"INTERNAL\",\"identifier\":\"sAMAccountName=cborgstrom\",\"attributes\":{}}"' \
-F 'signers="{\"source\":\"INTERNAL\",\"identifier\":\"sAMAccountName=cborgstrom\",\"attributes\":{}}"' \
-F 'signers="{\"source\":\"EXTERNAL\",\"identifier\":\"198603052385\",\"attributes\":{\"mail\":{\"value\":\"[email protected]\"},\"mobile\":{\"value\":\"+46700000000\"}}}"'
The Signing Workflow Server will do a user lookup based on identifier and source, and fill in the order request with attributes from the lookup result.
In the case of external users, it is possible to provide attributes in the request, as can be seen in the above example. Attributes in the request will be used to fill in the order only if the user lookup does not yield any result for that attribute.
The response to a successful CreateOrder request is a GUID that identifies the order, and can be used to query order status and download the signed document.
Example: 5d7c2010-f461-4ceb-b66c-d6ef2a9a2802
Read signing order
Perform a GET
request targeted at /orders/{orderId}
to retrieve all the information about a signing order.
Example:
curl --location --request GET 'http://3.121.160.99:8081/api/document_signing/orders/9ed6dd41-d33c-4fd1-b69e-b74d61480945'
The response is a json object with all the information about the signing order.
Get the status of a signing order
Perform a GET
request targeted at /orders/{orderId}/state
to retrieve the status of a signing order.
curl --location --request GET 'http://3.121.160.99:8081/api/document_signing/orders/9ed6dd41-d33c-4fd1-b69e-b74d61480945/state'
The response to a successful request is one of the following:
-
PENDING
: the order is pending signatures -
ACCEPTED
: all requested signers have signed the order -
REJECTED
: one of the signers have refused to sign the order -
CANCELLED
: the order solicitor has cancelled the order -
EXPIRED
: the order has not been signed by all signers within the due date
Download a signed document
Perform a GET
request targeted at /orders/{orderId}/document
to download a signed document.
curl --location --request GET 'http://3.121.160.99:8081/api/document_signing/orders/9ed6dd41-d33c-4fd1-b69e-b74d61480945/document'
The response to a successful request is the signed PDF document as a binary download.
This request should only be performed when the order has reached a status of ACCEPTED,
otherwise an unsigned or unfinished document will be downloaded.