Create dossier

post https://api.cm.com/sign/v1/dossiers

Create a new dossier to sign. For the webhook callback structure see the Callbacks tab.

Body Params

You need to provide one or more file id's you've uploaded previously and add the invitees and fields for the persons that need to sign or review the document(s).

A dossier owner can be specified, but this is optional.

name

string

required

length ≤ 255

human readable name for this dossier

locale

string

Defaults to en-US

Locale of the language to be used in the dossier

prepare

boolean | null

Place fields using the web interface

prepareReturnUrl

string | null

Optionally redirect the user to your website after the fields are placed. The url must begin with https://

timezone

string | null

The identifier of a time zone in the IANA database. This will change the time zone of dates used in communication to the recipient and dossier owner. By default Etc/UTC is used when no value is set.

expiresIn

number

60 to 7776000

Defaults to 2592000

The expiry in seconds since the dossier was created

reminderIn

number | null

86400 to 7776000

The time in seconds after the invite was sent to an invitee, after which an automatic reminder will be sent. Reminders only work if the invite emails were sent by Sign. To cancel all reminders for an existing dossier set value to null

archive

boolean

Defaults to false

This determines if the dossier needs to be archived.

files

array of objects

required

files*

attachments

array of objects

attachments

owners

array of objects

owners

invitees

array of objects

invitees

template

uuid | null

Defaults to null

Create a dossier from a template. This means that files and field positions are automatically copied from the template. You can find the template ID in the dashboard.

templateLabelValues

object

Key-value pairs for template labels. The key must match the exact value of the predefined label in the template. It will then be overwritten by the value in the request.

Responses

Response body

object

uuid

Id of the dossier

name

string

required

length ≤ 255

human readable name for this dossier

state

string

required

Every dossier is initialized with the draft state. When the dossier is pending, it will have sent out any invitations for signing. From this point, the dossier is mostly no longer editable. Once the everyone has signed, the state becomes completed and the signed dossier will be ready for retrieval. If any invitee declines the state of the dossier will become delinced. After the dossier expiry time has passed, a dossier will always enter the expired state. In the expired state a dossier can no longer be completed or declined. Once the state is deleted the signed contracts are no longer downloadable and all contracts and sensitive information are removed from the system.

draft pending completed declined expired deleted

locale

string

required

Defaults to en-US

Locale of the language to be used in the dossier

de-DE en-US es-ES fr-FR hu-HU it-IT ja-JP nl-NL pl-PL pt-PT ro-RO sk-SK

completed

boolean

required

If the dossier is marked as complete

prepare

boolean | null

Place fields using the web interface

prepareReturnUrl

string | null

Optionally redirect the user to your website after the fields are placed. The url must begin with https://

prepareUrl

string

The URL to the web interface to place fields. The URL is only valid for 60 minutes. Only available when dossier has been created with prepare: true

timezone

string | null

The identifier of a time zone in the IANA database. This will change the time zone of dates used in communication to the recipient and dossier owner. By default Etc/UTC is used when no value is set.

expiresIn

number

60 to 7776000

Defaults to 2592000

The expiry in seconds since the dossier was created

reminderIn

number | null

86400 to 7776000

expiresAt

date-time

The date the dossier expires

createdAt

date-time

The date the dossier was created

owners

array of objects

owners

object

uuid

required

Unique Id of the person who created and manages the dossier

name

string

required

length ≤ 255

Name of the person who created the dossier

string

required

length ≤ 255

A valid email address

boolean

Defaults to false

When set to true the owner will be added to the cc field in email communication.

notifications

array of strings or null

notifications

files

array of objects

required

files*

object

uuid

required

A unique reference number for this file.

name

string

required

length ≤ 255

Original name of the file without extension

hash

string

required

length ≤ 64

A sha256 hash of the document

uploadDateTime

date-time

required

The time at which the file was uploaded

size

integer

The size of the file in bytes

contentType

string

required

The content type identifying the type of file

attachments

array of objects

attachments

object

uuid

required

A unique reference number for this file.

name

string

length ≤ 255

Original name of the attachment without extension

hash

string

length ≤ 64

A sha256 hash of the attachment

uploadDateTime

date-time

The time at which the attachment was uploaded

contentType

string

The content type identifying the type of attachment

invitees

array of objects

required

invitees*

object

uuid

required

Optional. Indicates that only a particular invitee is allowed/required to use a field.

name

string

required

length ≤ 255

Name of the person invited to read and/or sign the document

string

length ≤ 255

A valid email address

locale

string | null

Defaults to en-US

Locale of the language to be used in invitations.

de-DE en-US es-ES fr-FR hu-HU it-IT ja-JP nl-NL pl-PL pt-PT ro-RO sk-SK

position

integer

Set the order of signing. For example if there are two invitees set position 1 for the first invitee and position 2 for the second invitee. It is possible to set multiple invitees on the same position. Make sure there is no gap between the positions.

authenticationMethods

array of strings

authenticationMethods

identificationMethod

string

deprecated

Additional user identification is required. When you select qualified it cannot be used with other identification methods. Please note that this is only available when configured for your account.

idin iban otp_sms otp_email otp_whatsapp otp_voice qualified

identificationMethods

array of strings

identificationMethods

notifications

array of strings or null

notifications

payments

array of objects

Additional payment is required. Please note that this is only available when configured for your account.

payments

object

amount

integer

required

≥ 1

The payment amount in cents

currency

string

required

The payment currency

EUR

phoneNumber

string

The phone number of the invitee in E.164 format. Required when identificationMethod is otp.

reference

string

length ≤ 255

A reference to an external identifier of your invitee.

readOnly

boolean

Defaults to false

Indicates that this invitee needs to review the dossier, instead of signing it

state

string

The invitee has approved or declined the dossier

approved declined

stateComment

string | null

Defaults to null

When the invitee declined the dossier this field may contain the reason for declining.

stateChanged

date-time | null

Defaults to null

The date the invitee state has changed

redirectUrl

url | null

Defaults to null

URL to redirect the invitee to after signing, approving or declining the dossier. If not set, the default confirmation page will be shown.

fields

array of objects

fields

object

uuid

required

Unique Id of a field

type

string

required

The type of field for the invitee.

signature signatureDate initials text textarea label checkbox radio stamp

required

boolean

Indicates if the field is required and must be filled in by the user. When required is true and type is checkbox the field must be checked.

file

uuid

required

A unique reference number for this file.

tag

string

length ≤ 64

The tag acts as a placeholder; the range and locations of the field are automatically determined based on the location(s) of the tag in the document. Add the tag to every page the field should include in case of initials. The tag should be hidden, for example by making it white.

tagRequired

boolean

Defaults to true

Indicates if the tag must be present in the document. When this is set to false and the tag is not found in the document it will skip this field.

locations

array of objects

locations

object

range

string

length ≤ 64

The page number within the PDF that this field occupies (e.g. 1), or range for a initials field (e.g. 1-3).

float

X position of the field in points.

float

Y position of the field in points.

width

float

Width of the field in points.

height

float

Height of the field in points.

invitee

uuid

Optional. Indicates that only a particular invitee is allowed/required to use a field.

Callback

Language

Credentials

Bearer

JWT

URL


xxxxxxxxxx
12
1
curl --request POST \
2
     --url https://api.cm.com/sign/v1/dossiers \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json' \
5
     --data '
6
{
7
  "locale": "en-US",
8
  "expiresIn": 2592000,
9
  "archive": false,
10
  "template": null
11
}
12
'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

201The newly created dossier. Will return your dossierId

401Unauthorized

404The specified resource was not found