API

Interfaces Summary

key privilege

HTTP method

URL

description

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.

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

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.

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 /
presence

description /
value example

field name

format /
presence

description /
value example

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 /
presence

description /
value example

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.

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 /
presence

description /
value example

field name

format /
presence

description /
value example

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

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"

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 /
presence

description /
value example

field name

format /
presence

description /
value example

name

printable Unicode string

Watcher's name.

required

“Richard Roe”

email

email

An email address on which notifications will come.

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 charact

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.

Contract Object

field name

format /
presence

description /
value example

field name

format /
presence

description /
value example

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
"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

always

"signed"

signers

array of Signer Objects

Present only in the GET /webapi/contracts/{contract-id} responses.

conditional

 

finalizedPdf

Attachment Object

Present if there is an attachment in the Confluence/Jira containing PDF with the final version of the contract.

conditional

 

certificatePdf

Attachment Object

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 /
presence

description /
value example

field name

format /
presence

description /
value example

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

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

"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.

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 /
presence

description /
value example

field name

format /
presence

description /
value example

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"