Overview

This document describes the RESTful Contracts and resources provided by Signom. RESTful Contracts is intended for developers who wish to integrate Signom Signature Service into their application.

RESTful Contracts provides access to resources via URI paths. To use RESTful Contracts, your application will make HTTP requests to RESTful Contracts' URIs. The request and response payload content type is in most cases application/json.

URLs

Test environment: https://www.signom.com/test-api/rest/

Production environment: https://www.signom.com/api/rest/

Contract Statuses

All the possible contract statuses are listed below.

UNINITIALIZED

First creation status before any contract information has been set
INACTIVE

Created but not activated
OPEN

Open, missing signatures
CLOSED

All participants have closed
DELETED

Deleted without activation
TERMINATED

Opened and then terminated by user
REJECTED

Opened and then rejected by a signing participant
CANCELLED

Closed contract cancelled by all signing participants

HTTP Verbs

RESTful Contracts tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

GET

Used to retrieve a resource
POST

Used to create a new resource
PUT

Used to update an existing resource
DELETE

Used to delete an existing resource

HTTP Status Codes

RESTful Contracts 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.

404 Not Found

The requested resource did not exist.

500 Internal Server Error

Unexpected condition that could not be handled by the application.

Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem (see below for example payloads). Examples of possible error cases include:

  • Client permissions rights are not sufficient, e.g. incorrect contractId in getStatus query.

  • User permissions are not sufficient, e.g. person tries to sign without Signom side signing right.

  • Mandatory information is missing.

  • Information is in incorrect format, e.g. email address is invalid.

  • REST client tries to send non-pdf file.

400 Bad Request

Validation Errors

Validation errors occur when request payload can be successfully mapped from JSON, but is semantically wrong.

Example: validation error with empty template tag and company bic with incorrect format
POST /api/rest/contracts HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: www.signom.com
Content-Length: 201

{
  "templateTag" : "",
  "name" : "Leasing Contract 927493",
  "type" : "DEFAULT",
  "localizationSuffix" : "DEFAULT",
  "language" : "en_US",
  "companyBic" : "invalid bic",
  "keyValuePairs" : [ ]
}
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 310

{
  "status" : "BAD_REQUEST",
  "message" : "Invalid data",
  "error" : "javax.validation.ConstraintViolationException",
  "validationErrors" : [ {
    "type" : "NotBlank",
    "path" : "templateTag",
    "message" : "may not be empty",
    "arguments" : { }
  } ],
  "timestamp" : "2019-08-07T19:59:23.864Z"
}
Example: validation error with message parameters (too long name)
POST /api/rest/contracts HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: www.signom.com
Content-Length: 541

{
  "templateTag" : "signom.process.84302",
  "name" : "Leasing Contract 927493Leasing Contract 927493Leasing Contract 927493Leasing Contract 927493Leasing Contract 927493Leasing Contract 927493Leasing Contract 927493Leasing Contract 927493Leasing Contract 927493Leasing Contract 927493Leasing Contract 927493Leasing Contract 927493Leasing Contract 927493Leasing Contract 927493Leasing Contract 927493",
  "type" : "DEFAULT",
  "localizationSuffix" : "DEFAULT",
  "language" : "en_US",
  "companyBic" : "2220746-7",
  "keyValuePairs" : [ ]
}
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 352

{
  "status" : "BAD_REQUEST",
  "message" : "Invalid data",
  "error" : "javax.validation.ConstraintViolationException",
  "validationErrors" : [ {
    "type" : "Size",
    "path" : "name",
    "message" : "size must be between 0 and 255",
    "arguments" : {
      "min" : 0,
      "max" : 255
    }
  } ],
  "timestamp" : "2019-08-07T19:59:22.901Z"
}
JSON Mapping Errors

JSON mapping errors occur when request payload cannot be mapped due to type mismatch, e.g. an enumerated value cannot be created from the given input.

JSON mapping errors are also considered validation errors. But due to not being able to map the request payload, any further semantic analysis of the payload is not done. This means that if the payload contains both JSON mapping errors and normal semantic validation errors, only JSON mapping errors are reported until the payload mapping succeeds.
Example: JSON mapping error with invalid language
POST /api/rest/contracts HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: www.signom.com
Content-Length: 222

{
  "templateTag" : "signom.process.84302",
  "name" : "Leasing Contract 927493",
  "type" : "DEFAULT",
  "localizationSuffix" : "DEFAULT",
  "language" : "language",
  "companyBic" : "2220746-7",
  "keyValuePairs" : [ ]
}
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 688

{
  "status" : "BAD_REQUEST",
  "message" : "Invalid input",
  "error" : "org.springframework.http.converter.HttpMessageNotReadableException",
  "validationErrors" : [ {
    "type" : "TypeMismatch",
    "path" : "language",
    "message" : "Can not deserialize value of type com.signom.signatureapi.adapter.primary.rest.domain.ContractLanguage from String \"language\": value not one of declared Enum instance names: [en, fi, en_US, sv]\n at [Source: java.io.PushbackInputStream@4b2d5e1a; line: 1, column: 131] (through reference chain: com.signom.signatureapi.adapter.primary.rest.domain.Contract[\"language\"])",
    "arguments" : { }
  } ],
  "timestamp" : "2019-08-07T19:59:23.228Z"
}

404 Not Found

This is used both for non-existing resources and situations where the user does not have sufficient permissions to execute the operation.

Example: not found
HTTP/1.1 404 Not Found

General Features

Authentication

RESTful Contracts requires client to authenticate using HTTP basic auth.

Example: curl request with basic authentication
$ curl 'https://www.signom.com/api/rest/contracts/status?contractId=42' -i -u 'external-servicename:apikey'
Example: http request with basic authentication
GET /api/rest/contracts/status?contractId=42 HTTP/1.1
Authorization: Basic ZXh0ZXJuYWwtc2VydmljZW5hbWU6YXBpa2V5
Host: www.signom.com

Requests without proper Authorization header will result in 401 Unauthorized response without payload.

Example: http response for unauthorized request
HTTP/1.1 401 Unauthorized

Use Cases

Use Case 1: Create and activate contract with 2 signers

First one company employee, second one customer as person, 1 signable file.

  1. Rest client creates contract

    POST /api/rest/contracts HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: www.signom.com
Content-Length: 218

{
  "templateTag" : "signom.template.739",
  "name" : "Leasing Contract 927493",
  "type" : "DEFAULT",
  "localizationSuffix" : "DEFAULT",
  "language" : "en_US",
  "companyBic" : "2220746-7",
  "keyValuePairs" : [ ]
}
    HTTP/1.1 201 Created
Location: https://www.signom.com/api/rest/contracts/793427
Content-Type: application/json;charset=UTF-8
Content-Length: 243

{
  "contractId" : 793427,
  "templateTag" : "signom.template.739",
  "name" : "Leasing Contract 927493",
  "type" : "DEFAULT",
  "localizationSuffix" : "DEFAULT",
  "language" : "en_US",
  "companyBic" : "2220746-7",
  "keyValuePairs" : [ ]
}

  2. Rest client adds first participant

    POST /api/rest/contracts/793427/participants HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: www.signom.com
Content-Length: 297

{
  "templateTag" : "signom.common.2794392",
  "signatory" : true,
  "company" : {
    "name" : "Signom Oy",
    "requireAuthorizedCompanySignature" : true,
    "companyBic" : "2220746-7",
    "personalRoleAllowed" : false
  },
  "email" : "timo.toimihenkilo@signom.com",
  "keyValuePairs" : [ ]
}
    HTTP/1.1 201 Created
Location: https://www.signom.com/api/rest/contracts/793427/participants/8032802
Content-Type: application/json;charset=UTF-8
Content-Length: 351

{
  "contractId" : 793427,
  "participantId" : 8032802,
  "templateTag" : "signom.common.2794392",
  "signatory" : true,
  "company" : {
    "name" : "Signom Oy",
    "requireAuthorizedCompanySignature" : true,
    "companyBic" : "2220746-7",
    "personalRoleAllowed" : false
  },
  "email" : "timo.toimihenkilo@signom.com",
  "keyValuePairs" : [ ]
}

  3. Rest client adds second participant

    POST /api/rest/contracts/793427/participants HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: www.signom.com
Content-Length: 228

{
  "templateTag" : "signom.common.2794392",
  "signatory" : true,
  "person" : {
    "name" : "Antti Asiakas",
    "ssn" : "250596-973A"
  },
  "email" : "antti.asiakas@gmail.com",
  "actionStage" : 1,
  "keyValuePairs" : [ ]
}
    HTTP/1.1 201 Created
Location: https://www.signom.com/api/rest/contracts/793427/participants/8032803
Content-Type: application/json;charset=UTF-8
Content-Length: 282

{
  "contractId" : 793427,
  "participantId" : 8032803,
  "templateTag" : "signom.common.2794392",
  "signatory" : true,
  "person" : {
    "name" : "Antti Asiakas",
    "ssn" : "250596-973A"
  },
  "email" : "antti.asiakas@gmail.com",
  "actionStage" : 1,
  "keyValuePairs" : [ ]
}

  4. Rest client adds file

    POST /api/rest/contracts/793427/files HTTP/1.1
Content-Type: multipart/mixed; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Host: www.signom.com

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=metadata
Content-Type: application/json;charset=UTF-8

{"filename":"Leasing sopimus 439.pdf","documentsDeleted":false,"signable":true}
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=file
Content-Type: text/plain

This represents the contents of the uploaded file: for documentation purposes it is not feasible to use a binary
file and thus this plain text file is used. Typically contract files are PDFs with Content-Type of
application/octet-stream.
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--
    HTTP/1.1 201 Created
Location: https://www.signom.com/api/rest/contracts/793427/files/42
Content-Type: application/json;charset=UTF-8
Content-Length: 137

{
  "contractId" : 793427,
  "fileId" : 42,
  "filename" : "Leasing sopimus 439.pdf",
  "documentsDeleted" : false,
  "signable" : true
}

  5. Rest client calls activates contract

    Signom activates the contract and sends signature invitation by email to first participant with email address "timo.toimihenkilo@signom.com".

  6. Rest client starts scheduled polling

    Signom returns status OPEN and timer continues from the previous step. When both participants have signed the contract and status is CLOSED, polling stops and process continues to the next step.

  7. Rest client fetches files

    Signom returns the signed PDF file and process is complete.

Use Case 2: Create and sign contract

This use case is otherwise identical with Use Case 1, but instead of activating contract in step 5, the company participant signs the contract. Signing the contract automatically activates the contract.

Use Case 3: One of the participants rejects the contract

This use case is otherwise identical with Use Case 1, but in step 6, the client receives status REJECTED and stops polling. There is no need to fetch the files (step 7), but only to flag the contract as REJECTED in the client-side.

Resources

Contracts

Create

Example: curl request
$ curl 'https://www.signom.com/api/rest/contracts' -i -X POST -H 'Content-Type: application/json;charset=UTF-8' -d '{
  "templateTag" : "signom.process.84302",
  "name" : "Leasing Contract 927493",
  "type" : "DEFAULT",
  "localizationSuffix" : "DEFAULT",
  "language" : "fi",
  "companyBic" : "2220746-7",
  "departmentTag" : "department.tag",
  "initialWorkQueueOptionTag" : "workQueue.tag",
  "keyValuePairs" : [ {
    "key" : "someKey",
    "value" : "someValue"
  } ]
}'
Example: http request
POST /api/rest/contracts HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: www.signom.com
Content-Length: 358

{
  "templateTag" : "signom.process.84302",
  "name" : "Leasing Contract 927493",
  "type" : "DEFAULT",
  "localizationSuffix" : "DEFAULT",
  "language" : "fi",
  "companyBic" : "2220746-7",
  "departmentTag" : "department.tag",
  "initialWorkQueueOptionTag" : "workQueue.tag",
  "keyValuePairs" : [ {
    "key" : "someKey",
    "value" : "someValue"
  } ]
}
Table 1. Request payload description
Path Type Description Constraints

templateTag

String

Signom process identifier, that is given to customer by Signom during the project. Customer and process specific identifier allows Signom to match the contract level signature process to predefined process configurations. This enables later process changes by Signom, without the need to change client requests.

Must not be blank. Size must be between 0 and 255 inclusive

name

String

Descriptive name for the contract. Show the end-users e.g. as page-title when they proceed to sign the contract and used in emails that are sent to participants.

Must not be blank. Size must be between 0 and 255 inclusive

type

class kotlin.String

Contract type which may affect the mail templates used within the process. Default value is 'DEFAULT'.

localizationSuffix

class kotlin.String

Contract localization suffix which may affect localization of the mail templates used within the process. Default value is 'DEFAULT'.

language

String

Default localization language for end-user email messages, GUI and PDF files. In principle everything goes OK, if the value matches the language of the pdf files that are to be signed. Supported values are 'fi', 'sv' and 'en_US'.

companyBic

String

Business identification code of the owner company. This links the contract to Signom company database, which enables company employees to access the contract via Signom GUI (if main user has granted them the required permissions).

departmentTag

class kotlin.String

).

initialWorkQueueOptionTag

class kotlin.String

).

keyValuePairs

Array

Key value pairs

keyValuePairs.key

class kotlin.String

Key

Must not be blank

keyValuePairs.value

class kotlin.String

Value

Must not be blank

  • Client should be aware that INACTIVE contracts are deleted from Signom automatically after a certain period of time, if the contract creation process doesn’t reach a conclusion.
Example: http response
HTTP/1.1 201 Created
Location: https://www.signom.com/api/rest/contracts/793427
Content-Type: application/json;charset=UTF-8
Content-Length: 383

{
  "contractId" : 793427,
  "templateTag" : "signom.process.84302",
  "name" : "Leasing Contract 927493",
  "type" : "DEFAULT",
  "localizationSuffix" : "DEFAULT",
  "language" : "fi",
  "companyBic" : "2220746-7",
  "departmentTag" : "department.tag",
  "initialWorkQueueOptionTag" : "workQueue.tag",
  "keyValuePairs" : [ {
    "key" : "someKey",
    "value" : "someValue"
  } ]
}
Table 2. Response payload description
Path Type Description

contractId

Number

ID of the created contract

Status

Allows client to query contract status. The client should start calling this function with a predefined timer, after the contract has been activated.

Example: curl request
$ curl 'https://www.signom.com/api/rest/contracts/status?contractId=1,2,3' -i
Example: http request
GET /api/rest/contracts/status?contractId=1,2,3 HTTP/1.1
Host: www.signom.com
Table 3. Request parameters description
Parameter Description

contractId

Comma separated list of contract IDs.
Example: http response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 384

[ {
  "contractId" : 1,
  "name" : "Contract 1234",
  "status" : "OPEN",
  "processStage" : 0,
  "documentsDeleted" : false
}, {
  "contractId" : 2,
  "name" : "Contract 1234",
  "status" : "CLOSED",
  "processStage" : 0,
  "documentsDeleted" : false
}, {
  "contractId" : 3,
  "name" : "Contract 1234",
  "status" : "CANCELLED",
  "processStage" : 0,
  "documentsDeleted" : false
} ]
Table 4. Response payload description
Path Type Description

[].contractId

Number
Unique id of the contract, e.g. "843020". The URL may contain a list of comma separated ID values, if the client queries multiple contract statuses at the same time.

[].name

String
Contract name

[].status

String
Status of the contract. Possible values: * UNINITIALIZED * INACTIVE * OPEN * CLOSED * CANCELLED * REJECTED * DELETED * TERMINATED Different statuses should be handled in client side as defined in document "api client side processing of different contract statuses". In short the processing rules are following: * UNINITIALIZED and INACTIVE : the client side polling should not have started yet. * OPEN : continue client side polling. * CLOSED : fetch the files and stop polling. * CANCELLED, REJECTED, DELETED, TERMINATED : flag the contract in client side with related status and stop polling. Do not fetch files.

[].processStage

Number
TBD

[].documentsDeleted

Boolean
Boolean value that indicates, whether the contract documents are deleted or not.

  • If query contains contracts to which the credentials have no permissions to access, error is returned.

  • The response will always contain an array, also in the case where status is queried for a single contract.

Activate

Activates contract and sends signature invitations to signing parties via email.

Calling activate for a contract that is not in INACTIVE state is an error.
Example: curl request
$ curl 'https://www.signom.com/api/rest/contracts/793427/activate' -i -X PUT
Example: http request
PUT /api/rest/contracts/793427/activate HTTP/1.1
Host: www.signom.com
Table 5. /api/rest/contracts/{contractId}/activate
Parameter Description

contractId

Contract ID
Example: http response
HTTP/1.1 204 No Content

Delete

Deletes contract with INACTIVE status.

Calling delete for a contract that is not in INACTIVE state is an error.
Example: curl request
$ curl 'https://www.signom.com/api/rest/contracts/793427' -i -X DELETE
Example: http request
DELETE /api/rest/contracts/793427 HTTP/1.1
Host: www.signom.com
Table 6. /api/rest/contracts/{contractId}
Parameter Description

contractId

Contract ID
Example: http response
HTTP/1.1 204 No Content

Terminate

Terminates contract with OPEN status.

Calling terminate for a contract that is not in OPEN state is an error.
Example: curl request
$ curl 'https://www.signom.com/api/rest/contracts/793427/terminate' -i -X PUT
Example: http request
PUT /api/rest/contracts/793427/terminate HTTP/1.1
Host: www.signom.com
Table 7. /api/rest/contracts/{contractId}/terminate
Parameter Description

contractId

Contract ID
Example: http response
HTTP/1.1 204 No Content

Participants

Add

Adds new participant to contract and returns the unique id of the added participant as response payload. Limit for participants is 256 per contract.

Company Participant
Example: curl request
$ curl 'https://www.signom.com/api/rest/contracts/793427/participants' -i -X POST -H 'Content-Type: application/json;charset=UTF-8' -d '{
  "templateTag" : "signom.common.2794392",
  "signatory" : true,
  "company" : {
    "name" : "Signom Oy",
    "requireAuthorizedCompanySignature" : true,
    "companyBic" : "2220746-7",
    "personalRoleAllowed" : false
  },
  "email" : "timo.toimihenkilo@signom.com",
  "keyValuePairs" : [ ]
}'
Example: http request
POST /api/rest/contracts/793427/participants HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: www.signom.com
Content-Length: 297

{
  "templateTag" : "signom.common.2794392",
  "signatory" : true,
  "company" : {
    "name" : "Signom Oy",
    "requireAuthorizedCompanySignature" : true,
    "companyBic" : "2220746-7",
    "personalRoleAllowed" : false
  },
  "email" : "timo.toimihenkilo@signom.com",
  "keyValuePairs" : [ ]
}
Table 8. /api/rest/contracts/{contractId}/participants
Parameter Description

contractId

Contract ID
Table 9. Request payload description
Path Type Description Constraints

templateTag

String

Signom process identifier, that is given to customer by Signom during the project. Customer and process specific identifier allows Signom to match the participant level signature process to predefined process configurations. This enables later process changes by Signom, without the need to change client requests.

Must not be blank. Size must be between 0 and 64 inclusive

signatory

Boolean

Boolean value that indicates whether the participant is signing the contract or just receiving notifications when something in the signature process proceeds. Generally all non-signing participants receive notifications of all contract level actions, if they are not suppressed with Signom generated rules (custom process according the participant.templateTag).

email

String

Email address of the signatory

Must be a well-formed email address

suppressAllEmails

class kotlin.Boolean

Suppress all emails that would be sent to the participant

actionStage

class kotlin.Int

Stage when the system asks the participant to perform action / starts sending notifications about contract events. Integer value starting from ZERO. E.g. If two participants are added with first one having actionStage 0 and second one actionState 1, the second one gets signature invitation only when the first one has signed.

signatureDeadline

class java.time.ZonedDateTime

Datetime value, when the signature should be completed. If the deadline passes and the participant hasn’t signed the contract, it is autoterminated.

Must be in the future

keyValuePairs

Array

Key value pairs

keyValuePairs.key

class kotlin.String

Key

Must not be blank

keyValuePairs.value

class kotlin.String

Value

Must not be blank

company

Object

Root element for company data.

company.name

String

Name of the company

company.requireAuthorizedCompanySignature

Boolean

Boolean value that indicates whether Signom verifies the signing clause of the company. E.g. if company signer has only shared signing permission, she has to ask another signer (with matching shared signing right in trade register) to complete the company signature.

company.companyBic

String

Business identification code of the company.

company.personalRoleAllowed

Boolean

Boolean value that indicates whether Signom allows signature, if the user isn’t automatically identified as authorized company signatory from the trade register.
Example: http response
HTTP/1.1 201 Created
Location: https://www.signom.com/api/rest/contracts/793427/participants/8032802
Content-Type: application/json;charset=UTF-8
Content-Length: 351

{
  "contractId" : 793427,
  "participantId" : 8032802,
  "templateTag" : "signom.common.2794392",
  "signatory" : true,
  "company" : {
    "name" : "Signom Oy",
    "requireAuthorizedCompanySignature" : true,
    "companyBic" : "2220746-7",
    "personalRoleAllowed" : false
  },
  "email" : "timo.toimihenkilo@signom.com",
  "keyValuePairs" : [ ]
}
Person Participant
Example: curl request
$ curl 'https://www.signom.com/api/rest/contracts/793427/participants' -i -X POST -H 'Content-Type: application/json;charset=UTF-8' -d '{
  "templateTag" : "signom.common.2794392",
  "signatory" : true,
  "person" : {
    "name" : "Antti Asiakas",
    "ssn" : "250596-973A"
  },
  "email" : "antti.asiakas@gmail.com",
  "actionStage" : 1,
  "keyValuePairs" : [ ]
}'
Example: http request
POST /api/rest/contracts/793427/participants HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: www.signom.com
Content-Length: 228

{
  "templateTag" : "signom.common.2794392",
  "signatory" : true,
  "person" : {
    "name" : "Antti Asiakas",
    "ssn" : "250596-973A"
  },
  "email" : "antti.asiakas@gmail.com",
  "actionStage" : 1,
  "keyValuePairs" : [ ]
}
Table 10. /api/rest/contracts/{contractId}/participants
Parameter Description

contractId

Contract ID
Table 11. Request payload description
Path Type Description Constraints

templateTag

String

Signom process identifier, that is given to customer by Signom during the project. Customer and process specific identifier allows Signom to match the participant level signature process to predefined process configurations. This enables later process changes by Signom, without the need to change client requests.

Must not be blank. Size must be between 0 and 64 inclusive

signatory

Boolean

Boolean value that indicates whether the participant is signing the contract or just receiving notifications when something in the signature process proceeds. Generally all non-signing participants receive notifications of all contract level actions, if they are not suppressed with Signom generated rules (custom process according the participant.templateTag).

email

String

Email address of the signatory

Must be a well-formed email address

suppressAllEmails

class kotlin.Boolean

Suppress all emails that would be sent to the participant

actionStage

class kotlin.Int

Stage when the system asks the participant to perform action / starts sending notifications about contract events. Integer value starting from ZERO. E.g. If two participants are added with first one having actionStage 0 and second one actionState 1, the second one gets signature invitation only when the first one has signed.

signatureDeadline

class java.time.ZonedDateTime

Datetime value, when the signature should be completed. If the deadline passes and the participant hasn’t signed the contract, it is autoterminated.

Must be in the future

keyValuePairs

Array

Key value pairs

keyValuePairs.key

class kotlin.String

Key

Must not be blank

keyValuePairs.value

class kotlin.String

Value

Must not be blank

person

Object

Root element for person data.

person.name

String

Name of the person.

Must not be blank. Size must be between 0 and 255 inclusive

person.ssn

String

Social security number of the person.
Example: http response
HTTP/1.1 201 Created
Location: https://www.signom.com/api/rest/contracts/793427/participants/8032803
Content-Type: application/json;charset=UTF-8
Content-Length: 282

{
  "contractId" : 793427,
  "participantId" : 8032803,
  "templateTag" : "signom.common.2794392",
  "signatory" : true,
  "person" : {
    "name" : "Antti Asiakas",
    "ssn" : "250596-973A"
  },
  "email" : "antti.asiakas@gmail.com",
  "actionStage" : 1,
  "keyValuePairs" : [ ]
}

Delete

Deletes participant from an INACTIVE contract.

Calling 'delete participant' for a contract that is not in INACTIVE state is an error.
Example: curl request
$ curl 'https://www.signom.com/api/rest/contracts/793427/participants/8032803' -i -X DELETE
Example: http request
DELETE /api/rest/contracts/793427/participants/8032803 HTTP/1.1
Host: www.signom.com
Table 12. /api/rest/contracts/{contractId}/participants/{participantId}
Parameter Description

contractId

Contract ID

participantId

Participant ID
Example: http response
HTTP/1.1 204 No Content

Sign

Example: curl request
$ curl 'https://www.signom.com/api/rest/contracts/793427/participants/8032803/sign' -i -X PUT -H 'Content-Type: application/json;charset=UTF-8' -d '{
  "credentials" : {
    "email" : "antti.asiakas@gmail.com",
    "password" : "1W4lo_b6(AN-"
  }
}'
Example: http request
PUT /api/rest/contracts/793427/participants/8032803/sign HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: www.signom.com
Content-Length: 100

{
  "credentials" : {
    "email" : "antti.asiakas@gmail.com",
    "password" : "1W4lo_b6(AN-"
  }
}
Table 13. /api/rest/contracts/{contractId}/participants/{participantId}/sign
Parameter Description

contractId

Contract ID

participantId

Participant ID
Example: http response
HTTP/1.1 204 No Content

Files

File resources for a contract are returned in application/hal+json format.

Example: curl request
$ curl 'https://www.signom.com/api/rest/contracts/793427/files' -i
Example: http request
GET /api/rest/contracts/793427/files HTTP/1.1
Host: www.signom.com
Example: http response
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 741

{
  "_embedded" : {
    "fileResources" : [ {
      "contractId" : 793427,
      "fileId" : 42,
      "resourceId" : null,
      "templateTag" : "foo",
      "filename" : "Contract.pdf",
      "documentsDeleted" : false,
      "signable" : true,
      "_links" : {
        "self" : {
          "href" : "https://www.signom.com/api/rest/contracts/793427/files/42"
        }
      }
    }, {
      "contractId" : 793427,
      "fileId" : 43,
      "resourceId" : null,
      "templateTag" : "foo",
      "filename" : "Attachment.txt",
      "documentsDeleted" : false,
      "signable" : false,
      "_links" : {
        "self" : {
          "href" : "https://www.signom.com/api/rest/contracts/793427/files/43"
        }
      }
    } ]
  }
}

Add

Limit for files is 256 per contract.

Example: curl request
$ curl 'https://www.signom.com/api/rest/contracts/793427/files' -i -X POST -H 'Content-Type: multipart/form-data' -F 'metadata={"templateTag":"example.file","filename":"README.md","documentsDeleted":false,"signable":false};type=application/json;charset=UTF-8' -F 'file=This represents the contents of the uploaded file: for documentation purposes it is not feasible to use a binary
file and thus this plain text file is used. Typically contract files are PDFs with Content-Type of
application/octet-stream.;type=text/plain'
Example: http request
POST /api/rest/contracts/793427/files HTTP/1.1
Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Host: www.signom.com

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=metadata
Content-Type: application/json;charset=UTF-8

{"templateTag":"example.file","filename":"README.md","documentsDeleted":false,"signable":false}
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=file
Content-Type: text/plain

This represents the contents of the uploaded file: for documentation purposes it is not feasible to use a binary
file and thus this plain text file is used. Typically contract files are PDFs with Content-Type of
application/octet-stream.
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--
Table 14. /api/rest/contracts/{contractId}/files
Parameter Description

contractId

Contract ID
Table 15. Request payload description
Part Description

metadata

JSON metadata, see response fields for details.

file

File data to upload.
Example: http response
HTTP/1.1 201 Created
Location: https://www.signom.com/api/rest/contracts/793427/files/42
Content-Type: application/json;charset=UTF-8
Content-Length: 158

{
  "contractId" : 793427,
  "fileId" : 42,
  "templateTag" : "example.file",
  "filename" : "README.md",
  "documentsDeleted" : false,
  "signable" : false
}
Table 16. Response payload description
Path Type Description

contractId

Number

ID of the contract to which the file was added.

fileId

Number

ID of the added file.

templateTag

String

Signom process identifier, that is given to customer by Signom during the project. Customer and process specific identifier allows Signom to match the document to predefined process configurations. This enables later process changes by Signom, without the need to change client requests.

filename

String

Name shown in Signom GUI for the file.

documentsDeleted

Boolean

Boolean value that indicates, whether the contract documents are deleted or not.

signable

Boolean

Boolean value that indicates, whether the file is signable (with signature page) or appendix (without signature page).

Delete

Deletes file from an INACTIVE contract.

Calling 'delete file' for a contract that is not in INACTIVE state is an error.
Example: curl request
$ curl 'https://www.signom.com/api/rest/contracts/793427/files/42' -i -X DELETE
Example: http request
DELETE /api/rest/contracts/793427/files/42 HTTP/1.1
Host: www.signom.com
Table 17. /api/rest/contracts/{contractId}/files/{fileId}
Parameter Description

contractId

Contract ID

fileId

File ID
Example: http response
HTTP/1.1 204 No Content

Download

In principle should be called only when the contract status is CLOSED.
Example: curl request
$ curl 'https://www.signom.com/api/rest/contracts/793427/files/42' -i
Example: http request
GET /api/rest/contracts/793427/files/42 HTTP/1.1
Host: www.signom.com
Table 18. /api/rest/contracts/{contractId}/files/{fileId}
Parameter Description

contractId

Contract ID

fileId

File ID
Example: http response
HTTP/1.1 200 OK
Cache-Control: max-age=86400, must-revalidate, public
Content-Length: 238
Content-Type: text/plain
Content-Disposition: inline; filename=contract_file_download.txt

This represents the contents of a downloaded contract file: for documentation purposes it is not feasible to use a
binary file and thus this plain text file is used. Typically contract files are PDFs with Content-Type of
application/pdf.