API
Interfaces Summary
key privilege |
HTTP method |
URL |
description |
---|---|---|---|
get |
GET |
/webapi/contracts/{id} |
Gets specified contract details including signers data. |
search |
GET |
/webapi/contracts?{search-params} |
Searches for contracts fulfilling search-params criteria. Returns contract list without signers data. |
create |
POST |
/webapi/contracts |
Creates new contract. |
archive |
PATCH |
/webapi/contracts/{id} |
Puts contract into archive. |
delete |
DELETE |
/webapi/contracts/{id} |
Deletes contract. PDF attachments containing signed contracts are deleted by this interface. |
Keys
Every call to the Web API interfaces require HTTP Authorization
header with a Bearer
authentication scheme: Authorization: Bearer BgV57K7vCwGE2vXex7BcgahRMeYoBQgdSJWhcQoJXhF4
. Authorization tokens for this header can be obtained by an administrator from Web API Keys
tab in the Contract Signatures Apps page. Every key is associated with the following security attributes which define its:
Privileges - to which interfaces the key may be used
Not valid before - from when the key may be used
Not valid after - till when the key may be used
Allowed IPs - from what IPs (ranges) the key may be used
When any of the above criteria is not met 401 Unauthorized
or 403 Forbidden
HTTP status codes are returned.
As restricted criteria as possible should be set to minimize unauthorized misuse.
Every authorized use of a key is registered as it would be the owner of the key doing the action.
Ensure your HTTP client verifies server's certificate. Otherwise you may send your key secret to an impersonated entity.
Key secret tokens should be placed in files on destination instances only with maximally restricted file access attributes and loaded into the application on a start. Even better would be to use some secret management utility sometimes provided by cloud operators.
Key secret tokens should not be stored in environment variables. They are available to child processes and may be dumped to some unencrypted log files on application crash, debugs or restarts.
Key secret tokens should not be passed via program arguments as they may be exposed to all operating system users.
Key secret tokens should never be placed in the application source code, even in private repositories as not every developer, tester, copywriter, technical operator and so on should have access to it.
Key secret tokens should never be stored in the database unencrypted as they may leak with the database backups or migrations.
Get Contract Interface
GET https://contract-signatures.com/webapi/contracts/{contract-id}
Returns Contract Object with signers' personal data or 404 Not Found HTTP status.
Search Contracts Interface
GET https://contract-signatures.com/webapi/contracts?{search-parameters}
Search Parameters
name |
value format |
description |
---|---|---|
template-id |
printable US-ASCII string |
Confluence page or Jira issue identifier. |
statuses |
"any" |
Searches for contracts with the specified statuses only. Defaults to "any". |
substring |
nonempty Unicode string |
Searches for contracts with a specified substring in a contract name or in a signer name or email. Case insensitive operation. |
creator-id |
Atlassian user id |
Searches for contracts created by a specified Atlassian user only. |
placement |
"any" |
Searches for contracts from specified place only. Default to "stacked". |
date-range |
iso8601date |
Searches for contracts created:
Example: "2022-10-01~2022-10-31" |
time-zone |
time zone identifier |
A time-zone identifier, such as "Europe/Paris", "Z", "UTC" or "UTC+01:00". Defaults to "UTC". Defines time zone in which |
order |
"random" |
Defines the order in which contracts are returned. Defaults to "random". |
page |
positive integer |
Number of page with contracts. Defaults to 1. Has no meaning when |
page-size |
positive integer |
Number of contracts per page. Defaults to 10. Allowed maximum is 100. |
Response
field name |
format / |
description / |
---|---|---|
totalCount |
non negative integer |
Number of all contracts matching the search parameters. |
always |
0 |
|
contracts |
array of Contract Objects |
Not present when selected page has no contracts. Does not contain signers' data. |
optional |
|
Create Contract Interface
POST https://contract-signatures.com/webapi/contracts
Request
field name |
format / |
description / |
---|---|---|
templateId |
printable US-ASCII string |
Confluence page or Jira issue identifier from which a contract will be created. |
required |
"1234567" |
|
name |
printable Unicode string |
Name of a contract. |
required |
"NDA" |
|
sequentialSigning |
boolean |
Will the invitation email be sent after a previous signer decision ? Defaults to false. |
optional |
true |
|
signers |
array of Signer Creation Objects |
At least one signer is required. No more then 26 signers are allowed. |
required |
|
Signer Creation Object
field name |
format / |
description / |
|
---|---|---|---|
fullName |
printable Unicode string |
Full name of a signer. |
|
required |
“Richard Roe” |
|
|
accessKind |
"email" or "url" |
How the signer will access the sign page ? |
|
required |
"email" |
|
|
Email address on which the signer will receive an URL to the signing page. An OTP will also be sent here if "phone" is not set. Required for "accessKind" set to "email" and optional for "accessKind" set to "url". |
|
||
conditional |
"richard.roe@company.com" |
|
|
otpMethod |
“email” or “sms” or “none” |
A way of obtaining a one-time password that the user will receive, which is required to sign the contract. By default, if this field is not set and the phone number is present, the password will be sent via SMS. If not, the password will be sent to the email. If neither phone nor email are set, no password will be sent. |
|
optional |
“sms” |
|
|
signerSigningMethods |
“upload” and/or “render” and/or “draw” |
This field specifies the available methods for signing the contract.
|
|
optional |
["upload"], ["upload", "render"], ["render", "draw"], or any combination of these methods |
|
|
phone |
E.164 |
Mobile phone number in the international format on which OTP will be sent. SMS Shipper Config must be filled with valid credential for this to work. |
|
optional |
"+49 172-9973185" |
|
|
appendSignatureMacro |
boolean |
Should signature macro for this signer be appended at the end of the contract ? Defaults to false. |
|
optional |
true |
|
|
receivesCompletedContract |
boolean |
Should signer receive completed contract on her/his email ? Defaults to true. |
|
optional |
false |
|
Watcher Object
field name |
format / |
description / |
---|---|---|
name |
printable Unicode string |
Watcher's name. |
required |
“Richard Roe” |
|
An email address on which notifications will come. |
||
required |
||
notificationKinds |
"created" |
Defines notification kinds to be send. Kinds may be combined with a vertical bar character |
required |
"created|signed|rejected|completed-contract" |
Archive Contract Interface
PATCH https://contract-signatures.com/webapi/contracts/{contract-id}
Calling this interface will move the contract into archive. No body is expected. Returns with HTTP 204 No Content status.
Delete Contract Interface
DELETE https://contract-signatures.com/webapi/contracts/{contract-id}
Deletes the specified contract. Returns with HTTP 204 No Content status.
PDF attachments containing signed contracts are deleted by this interface.
Contract Object
field name |
format / |
description / |
---|---|---|
id |
UUID |
This contract identifier. |
always |
15f5b906-1076-4539-a9ac-0be80bdef973 |
|
templateId |
printable US-ASCII string |
Confluence page or Jira issue identifier. |
always |
"654321" |
|
collectionId |
printable US-ASCII string |
Confluence space or Jira project identifier. |
always |
"123456" |
|
name |
printable Unicode string |
This contract name. |
always |
"NDA" |
|
createdById |
printable US-ASCII string |
Atlassian user identifier of this contract creator. |
always |
"123456:b84aeffd-32e5-4b4b-a012-89bf06cae06e" |
|
creationTimestamp |
ISO 8601 |
Time at which this contract creation has been requested. |
always |
"2022-09-16T13:28:37.4951Z" |
|
expirationTimestamp |
ISO 8601 |
Time at which this contract become expired. |
always |
"2022-09-23T13:28:37.4951Z" |
|
sequentialSigning |
boolean |
Is an invitation email sent after a previous signer decision ? |
always |
false |
|
archivalTimestamp |
ISO 8601 |
Time at which this contract has been move to the archive. |
conditional |
"2022-09-30T13:28:37.932523Z" |
|
status |
"sent" or |
This contract status:
|
always |
"signed" |
|
signers |
array of Signer Objects |
Present only in the |
conditional |
|
|
finalizedPdf |
Present if there is an attachment in the Confluence/Jira containing PDF with the final version of the contract. |
|
conditional |
|
|
certificatePdf |
Present if there is an attachment in the Confluence/Jira containing PDF certificate for the final version of the contract. |
|
conditional |
|
Signer Object
field name |
format / |
description / |
---|---|---|
fullName |
printable Unicode string |
Full name of a signer provided by a contract creator. |
always |
"Janie Doe" |
|
accessKind |
"email" or "url" |
The way a signer may access to a signing page. |
always |
"email" |
|
otpMethod |
“email” or “sms” or “none” |
The way a signer may obtain one time password required for signing the contract. |
always |
“sms” |
|
email address |
Email address of a signer provided by a contract creator. Required when "accessKind" is "email". Optional otherwise. |
|
conditional |
"janie.doe@hotmail.com" |
|
phone |
E.164 |
International mobile phone number of a signer provided by a contract creator. |
optional |
"+33639987654" |
|
accessUrl |
URL |
Personal URL (with a secret) to the page on which the signer may sign/reject this contract. Present only when a web API key owner is the same as the contractor creator and "accessKind" is set to "url". |
conditional |
||
decision |
"signed" or "rejected" |
Is present only when a signer already signed/rejected this contract. |
conditional |
"signed" |
|
decisionTimestamp |
ISO 8601 |
Is present only when a signer already signed/rejected this contract. |
conditional |
"2022-09-16T13:36:34.971644Z" |
|
decisionIp |
IP address |
IPv4 or IPv6 address from which signing/rejecting request has come. |
conditional |
"198.51.100.123" |
Attachment Object
field name |
format / |
description / |
---|---|---|
id |
printable US-ASCII string |
Confluence or Jira attachment identifier. |
always |
"att87654321" |
|
version |
positive integer |
Present only in the Confluence application. |
conditional |
1 |
|
creationTimestamp |
ISO 8601 |
Time of the request which lead to a creation of this attachment. |
always |
"2022-09-16T13:36:34.971644Z" |
|
sha3 |
128 hexadecimals |
SHA3-512 value of the attachment file. |
always |
"a69f73cca23a9ac5c8b567dc185a756e97c982164fe25859e0d1dcc1475c80a615b2123af1f5f94c11e3e9402c3ac558f500199d95b6d3e301758586281dcd26" |