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 and delete a signing order
  • Read a signing order
  • Get the status of a signing order
  • Download a signed document
  • Anonymize user
  • Update order

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 the 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 the endpoint is secured externally.
PhenixID recommends using 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:

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). Add multiple times for multiple signers.
  • tags - Tag this order (text/json object)
  • linkType - Set link type (integer)
  • option - Add additional options. (text/json object) E.g. notifyAllSigners { "name": "notifyAllSigners", "value": true }

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 JSON for solicitor or signer:

{
  "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="2024-12-24T00: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.

Anonymize User

You can anonymize a user in the SQL database by calling the anonymized endpoint.

Only users without pending orders can be anonymized. You have to delete or cancel any pending orders before calling this endpoint.

The following information will be anonymized for the user in the database;

  • First name
  • Last name
  • Phone number
  • E-mail address
  • A new random UUID replaces the internal UUID.

The following will not be anonymized;

  • The signatures in the documents will not be anonymized.
  • Logs in the database table events will not be anonymized.
  • Logs in log files will not be anonymized.

Note that if the creator of the order is anonymized, it will no longer have access to its created orders.

Perform a POST request at /anonymize

You can choose between the following three parameters

  • internalId - UUID used in the database column logins.internal_id. E.g. "256FEDCB-CC59-435B-B45B-D915F7C7A04A"
  • externalId -  E.g. "INTERNAL:jane.doe" or "EXTERNAL:200001011907", etc.
  • ldapSearch - Same JSON object as when creating an order with the endpoint POST /orders

Update order

There are two endpoints for updating orders. More information can be found here:

Order handling