| Table of Contents |
|---|
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.
|
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:
...
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.
| ||
page | positive integer | Number of page with contracts. Defaults to 1.
| ||
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.
| |||
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
...
| Note |
|---|
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" | |
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" |