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 |
---|---|
|
The request completed successfully. |
|
A new resource has been created successfully. The resource’s URI is available from the response’s
|
|
An update to an existing resource has been applied successfully. |
|
The request was malformed. The response body will include an error providing further information. |
|
The requested resource did not exist. |
|
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.
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: 520
{
"status" : "BAD_REQUEST",
"message" : "Invalid data",
"error" : "javax.validation.ConstraintViolationException",
"validationErrors" : [ {
"type" : "Pattern",
"path" : "companyBic",
"message" : "must match \"\\A[0-9]{7}[\\-]?[0-9]\\z\"",
"arguments" : {
"flags" : [ ],
"regexp" : "\\A[0-9]{7}[\\-]?[0-9]\\z"
}
}, {
"type" : "NotBlank",
"path" : "templateTag",
"message" : "may not be empty",
"arguments" : { }
} ],
"timestamp" : "2019-02-14T18:45:03.559Z"
}
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-02-14T18:45:02.523Z"
}
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. |
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@68c02972; line: 1, column: 131] (through reference chain: com.signom.signatureapi.adapter.primary.rest.domain.Contract[\"language\"])",
"arguments" : { }
} ],
"timestamp" : "2019-02-14T18:45:02.904Z"
}
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.
HTTP/1.1 404 Not Found
General Features
Authentication
RESTful Contracts requires client to authenticate using HTTP basic auth.
$ curl 'https://www.signom.com/api/rest/contracts/status?contractId=42' -i -u 'external-servicename:apikey'
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.
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.
-
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" : [ ] }
-
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" : [ ] }
-
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" : [ ] }
-
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 }
-
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".
-
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 isCLOSED
, polling stops and process continues to the next step. -
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
$ 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",
"keyValuePairs" : [ {
"key" : "someKey",
"value" : "someValue"
} ]
}'
POST /api/rest/contracts HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: www.signom.com
Content-Length: 271
{
"templateTag" : "signom.process.84302",
"name" : "Leasing Contract 927493",
"type" : "DEFAULT",
"localizationSuffix" : "DEFAULT",
"language" : "fi",
"companyBic" : "2220746-7",
"keyValuePairs" : [ {
"key" : "someKey",
"value" : "someValue"
} ]
}
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). |
Seven digits, a dash (optional) and a control digit, for example 1234567-8 |
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 |
|
HTTP/1.1 201 Created
Location: https://www.signom.com/api/rest/contracts/793427
Content-Type: application/json;charset=UTF-8
Content-Length: 296
{
"contractId" : 793427,
"templateTag" : "signom.process.84302",
"name" : "Leasing Contract 927493",
"type" : "DEFAULT",
"localizationSuffix" : "DEFAULT",
"language" : "fi",
"companyBic" : "2220746-7",
"keyValuePairs" : [ {
"key" : "someKey",
"value" : "someValue"
} ]
}
Path | Type | Description |
---|---|---|
|
|
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.
$ curl 'https://www.signom.com/api/rest/contracts/status?contractId=1,2,3' -i
GET /api/rest/contracts/status?contractId=1,2,3 HTTP/1.1
Host: www.signom.com
Parameter | Description |
---|---|
|
Comma separated list of contract IDs. |
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 300
[ {
"contractId" : 1,
"status" : "OPEN",
"processStage" : 0,
"documentsDeleted" : false
}, {
"contractId" : 2,
"status" : "CLOSED",
"processStage" : 0,
"documentsDeleted" : false
}, {
"contractId" : 3,
"status" : "CANCELLED",
"processStage" : 0,
"documentsDeleted" : false
} ]
Path | Type | Description |
---|---|---|
|
|
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. |
|
|
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. |
|
|
TBD |
|
|
Boolean value that indicates, whether the contract documents are deleted or not. |
|
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.
|
$ curl 'https://www.signom.com/api/rest/contracts/793427/activate' -i -X PUT
PUT /api/rest/contracts/793427/activate HTTP/1.1
Host: www.signom.com
Parameter | Description |
---|---|
|
Contract ID |
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.
|
$ curl 'https://www.signom.com/api/rest/contracts/793427' -i -X DELETE
DELETE /api/rest/contracts/793427 HTTP/1.1
Host: www.signom.com
Parameter | Description |
---|---|
|
Contract ID |
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.
|
$ curl 'https://www.signom.com/api/rest/contracts/793427/terminate' -i -X PUT
PUT /api/rest/contracts/793427/terminate HTTP/1.1
Host: www.signom.com
Parameter | Description |
---|---|
|
Contract ID |
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
$ 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" : [ ]
}'
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" : [ ]
}
Parameter | Description |
---|---|
|
Contract ID |
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). |
|
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. |
Seven digits, a dash (optional) and a control digit, for example 1234567-8 |
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. |
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
$ 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" : [ ]
}'
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" : [ ]
}
Parameter | Description |
---|---|
|
Contract ID |
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). |
|
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. |
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.
|
$ curl 'https://www.signom.com/api/rest/contracts/793427/participants/8032803' -i -X DELETE
DELETE /api/rest/contracts/793427/participants/8032803 HTTP/1.1
Host: www.signom.com
Parameter | Description |
---|---|
|
Contract ID |
|
Participant ID |
HTTP/1.1 204 No Content
Sign
$ 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-"
}
}'
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-"
}
}
Parameter | Description |
---|---|
|
Contract ID |
|
Participant ID |
HTTP/1.1 204 No Content
Files
File resources for a contract are returned in application/hal+json
format.
$ curl 'https://www.signom.com/api/rest/contracts/793427/files' -i
GET /api/rest/contracts/793427/files HTTP/1.1
Host: www.signom.com
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.
$ 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'
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--
Parameter | Description |
---|---|
|
Contract ID |
Part | Description |
---|---|
|
JSON metadata, see response fields for details. |
|
File data to upload. |
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
}
Path | Type | Description |
---|---|---|
|
|
ID of the contract to which the file was added. |
|
|
ID of the added file. |
|
|
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. |
|
|
Name shown in Signom GUI for the file. |
|
|
Boolean value that indicates, whether the contract documents are deleted or not. |
|
|
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. |
$ curl 'https://www.signom.com/api/rest/contracts/793427/files/42' -i -X DELETE
DELETE /api/rest/contracts/793427/files/42 HTTP/1.1
Host: www.signom.com
Parameter | Description |
---|---|
|
Contract ID |
|
File ID |
HTTP/1.1 204 No Content
Download
In principle should be called only when the contract status is CLOSED .
|
$ curl 'https://www.signom.com/api/rest/contracts/793427/files/42' -i
GET /api/rest/contracts/793427/files/42 HTTP/1.1
Host: www.signom.com
Parameter | Description |
---|---|
|
Contract ID |
|
File ID |
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.