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://bitbucket.org/phenixidentity/openapi/src/master/

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.