Interfaces Summary

key privilege	HTTP method	URL	description
get	GET	/webapi/contracts/{id}	Gets specified contract details including signers data. Personal data such as full name, email address, phone number or IP address are returned from this interface. Using this interface requires implementation of a personal data protection regulations such us GDPR, CCPA, LGPD or alike.
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 meet 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 a 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.

Personal data such as full name, email address, phone number or IP address are returned from this interface. Using this interface requires implementation of a personal data protection regulations such us GDPR, CCPA, LGPD or alike.

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" "sent" "ongoing" "rejected" "signed" "expired" "sent\|ongoing" "rejected\|signed\|expired" or any other combination	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" "stacked" "archived"	Searches for contracts from specified place only. Default to "stacked".
date-range	iso8601date iso8601date~ ~iso8601date iso8601date~iso8601date	Searches for contracts created: `iso8601date` - on the specified date `iso8601date~` - on or after the specified date `~iso8601date` - before or on the specified date `iso8601date~iso8601date` - between specified dates inclusive 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 `date-range` parameter is interpreted.
order	"random" "creation-date-asc" "creation-date-desc" "name-asc" "name-desc" "creator-id-asc" "creator-id-desc"	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 `order` parameter is not set as it defaults to "random".
page-size	positive integer	Number of contracts per page. Defaults to 10. Allowed maximum is 100.

Response

field name	format / presence	description / value example
totalCount	non negative integer	Number of all contracts matching the search parameters.
totalCount	always	0
contracts	array of Contract Objects	Not present when selected page has no contracts. Does not contain signers' data.
contracts	optional

Create Contract Interface

POST https://contract-signatures.com/webapi/contracts

Request

field name	format / presence	description / value example
templateId	printable US-ASCII string	Confluence page or Jira issue identifier from which a contract will be created.
templateId	required	"1234567"
name	printable Unicode string	Name of a contract.
name	required	"NDA"
sequentialSigning	boolean	Will the invitation email be sent after a previous signer decision ? Defaults to false.
sequentialSigning	optional	true
signers	array of Signer Creation Objects	At least one signer is required. No more then 26 signers are allowed.
signers	required

Signer Creation Object

field name	format / presence	description / value example
fullName	printable Unicode string	Full name of a signer.
fullName	required	“Richard Roe”
accessKind	"email" or "url"	How the signer will access the sign page ?
accessKind	required	"email"
email	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".
email	conditional	"richard.roe@company.com"
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.
phone	optional	"+49 172-9973185"
appendSignatureMacro	boolean	Should signature macro for this signer be appended at the end of the contract ? Defaults to false.
appendSignatureMacro	optional	true
receivesCompletedContract	boolean	Should signer receive completed contract on her/his email ? Defaults to true.
receivesCompletedContract	optional	false

Watcher Object

field name	format / presence	description / value example
name	printable Unicode string	Watcher's name.
name	required	“Richard Roe”
email	email	An email address on which notifications will come.
email	required	"richard.roe@company.com"
notificationKinds	"created" "opened" "signed" "rejected" "completed" ”completed-contract” "signed\|rejected\|completed" or any other combination	Defines notification kinds to be send. Kinds may be combined with a vertical bar character `\|`.
notificationKinds	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 / presence	description / value example
id	UUID	This contract identifier.
id	always	15f5b906-1076-4539-a9ac-0be80bdef973
templateId	printable US-ASCII string	Confluence page or Jira issue identifier.
templateId	always	"654321"
collectionId	printable US-ASCII string	Confluence space or Jira project identifier.
collectionId	always	"123456"
name	printable Unicode string	This contract name.
name	always	"NDA"
createdById	printable US-ASCII string	Atlassian user identifier of this contract creator.
createdById	always	"123456:b84aeffd-32e5-4b4b-a012-89bf06cae06e"
creationTimestamp	ISO 8601	Time at which this contract creation has been requested.
creationTimestamp	always	"2022-09-16T13:28:37.4951Z"
expirationTimestamp	ISO 8601	Time at which this contract become expired.
expirationTimestamp	always	"2022-09-23T13:28:37.4951Z"
sequentialSigning	boolean	Is an invitation email sent after a previous signer decision ?
sequentialSigning	always	false
archivalTimestamp	ISO 8601	Time at which this contract has been move to the archive.
archivalTimestamp	conditional	"2022-09-30T13:28:37.932523Z"
status	"sent" or "ongoing" or "rejected" or "signed" or "expired"	This contract status: "sent" - URLs to signing page are available but no signature or rejection has been made. "ongoing" - at least one signature is collected "rejected" - one of the signers rejected the contract "signed" - all signatures have been collected "expired" - not all signatures have been collected before expiration timestamp
status	always	"signed"
signers	array of Signer Objects	Present only in the `GET /webapi/contracts/{contract-id}` responses.
signers	conditional
finalizedPdf	Attachment Object	Present if there is an attachment in the Confluence/Jira containing PDF with the final version of the contract.
finalizedPdf	conditional
certificatePdf	Attachment Object	Present if there is an attachment in the Confluence/Jira containing PDF certificate for the final version of the contract.
certificatePdf	conditional

Signer Object

field name	format / presence	description / value example
fullName	printable Unicode string	Full name of a signer provided by a contract creator.
fullName	always	"Janie Doe"
accessKind	"email" or "url"	The way a signer may access to a signing page.
accessKind	always	"email"
email	email address	Email address of a signer provided by a contract creator. Required when "accessKind" is "email". Optional otherwise.
email	conditional	"janie.doe@hotmail.com"
phone	E.164	International mobile phone number of a signer provided by a contract creator.
phone	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".
accessUrl	conditional	"https://contract-signatures.com/sign/6a39cfb4-0cf8-4adf-a0fd-8a20052562eb/NDA?s=YouXiRodTgCZKHgJ5H3DkfkL6akHcDH3wnHEH9ZHR46C&no-otp&mode=sign&active=Person%20A "
decision	"signed" or "rejected"	Is present only when a signer already signed/rejected this contract.
decision	conditional	"signed"
decisionTimestamp	ISO 8601	Is present only when a signer already signed/rejected this contract.
decisionTimestamp	conditional	"2022-09-16T13:36:34.971644Z"
decisionIp	IP address	IPv4 or IPv6 address from which signing/rejecting request has come.
decisionIp	conditional	"198.51.100.123"

Attachment Object

field name	format / presence	description / value example
id	printable US-ASCII string	Confluence or Jira attachment identifier.
id	always	"att87654321"
version	positive integer	Present only in the Confluence application.
version	conditional	1
creationTimestamp	ISO 8601	Time of the request which lead to a creation of this attachment.
creationTimestamp	always	"2022-09-16T13:36:34.971644Z"
sha3	128 hexadecimals	SHA3-512 value of the attachment file.
sha3	always	"a69f73cca23a9ac5c8b567dc185a756e97c982164fe25859e0d1dcc1475c80a615b2123af1f5f94c11e3e9402c3ac558f500199d95b6d3e301758586281dcd26"