Create an Agreement

POST 
/agreements

Creates a new agreement in draft status. Use the agreement ID in subsequent requests.

Request

application/json

Body

POST /agreements request body

issuer object

The issuer of the agreement. If not provided, the authenticated client will be used.

name string

The name of the issuer

email email

The email of the issuer. Will be used for communication if email communication is enabled for the agreement.

role string

Possible values: [observer, signer, approver]

Default value: observer

The role of the issuer within the signing process.

send_emails boolean

Default value: true

Enables email communication in the agreement process. If not provided, the default value is true. If disabled, you will be responsible for handling all communication.

trust_level string

Possible values: [SES, AES]

Default value: SES

The minimum trust level used for all signatures in accordance with the eIDAS regulation. If not provided, the default value is SES.

signing_order boolean

Default value: false

Enables signing order for the agreement process. If not provided, the default value is false. If enabled, the signers will be required to sign in the order in which they are defined.

theme_id cuid

The ID of the theme to use for the agreement.

default_locale object

The default locale of the signing process. Can be overridden by individual participants, but the default locale determines the primary language used in all communication and UI.

oneOf

MOD1

string

MOD2

string

lookup_key string

Arbitrary string used to identify the agreement. This ID will be returned in the metadata field of the agreement resource.

success_callback_url url

An optional callback url to refer the participants back to post taking action.

Responses

200

POST /agreements Successful response

application/json

Schema

Schema

version stringrequired

Possible values: [1.0]

The version of the response schema

result_type stringrequired

Possible values: [single]

A single object of the agreement resource.

resource_type stringrequired

Possible values: [agreement]

Data contains the agreement resource.

data objectrequired

The resource data.

id cuidrequired

The unique identifier of the agreement

resource_type stringrequired

Possible values: [agreement]

test_mode booleanrequired

Indicates if the agreement is created using a development client

status stringrequired

Possible values: [draft, pending, fulfilled, cancelled, generating, failed_to_generate, open]

The status of the agreement

cancellation_reason stringnullablerequired

If the agreement is in a cancelled state, this will be a short description on the reason why, otherwise it will be null.

theme object required

oneOf

MOD1

string

MOD2

version stringrequired

Possible values: [1.0]

The version of the response schema

result_type stringrequired

Possible values: [single]

A single object of the theme resource.

resource_type stringrequired

Possible values: [theme]

Data contains the theme resource.

data objectrequired

The resource data.

id cuidrequired

The unique identifier of the theme

resource_type stringrequired

Possible values: [theme]

logo objectrequired

The logo of the theme. This is displayed to the user in all communication and touch points.

version stringrequired

Possible values: [1.0]

The version of the response schema

result_type stringrequired

Possible values: [single]

A single object of the file resource.

resource_type stringrequired

Possible values: [file]

Data contains the file resource.

data objectrequired

The resource data.

id cuidrequired

The unique identifier of the file

resource_type stringrequired

Possible values: [file]

filename stringrequired

Possible values: non-empty

The complete filename including the file extension

mime_type stringrequired

Possible values: non-empty

The mime type of the file

url url

The signed read url of the file

metadata object

lookup_key stringrequired

A provided lookup key provided by you to help you identify the file.

created_at stringrequired

UTC datetime ISO string

updated_at stringrequired

UTC datetime ISO string

icon objectrequired

The icon of the theme. This is used for the favicon.

version stringrequired

Possible values: [1.0]

The version of the response schema

result_type stringrequired

Possible values: [single]

A single object of the file resource.

resource_type stringrequired

Possible values: [file]

Data contains the file resource.

data objectrequired

The resource data.

id cuidrequired

The unique identifier of the file

resource_type stringrequired

Possible values: [file]

filename stringrequired

Possible values: non-empty

The complete filename including the file extension

mime_type stringrequired

Possible values: non-empty

The mime type of the file

url url

The signed read url of the file

metadata object

lookup_key stringrequired

A provided lookup key provided by you to help you identify the file.

created_at stringrequired

UTC datetime ISO string

updated_at stringrequired

UTC datetime ISO string

primary_color string

Default value: #000000

The primary color used to create the color palette in the signing room.

metadata object

lookup_key stringrequired

A provided lookup key provided by you to help you identify the theme.

created_at stringrequired

UTC datetime ISO string

updated_at stringrequired

UTC datetime ISO string

MOD3

string

issuer objectrequired

The issuer of the agreement

name stringnullablerequired

The name of the issuer. Required if no email is provided.

email stringnullablerequired

The email of the issuer. Required if agreemnt is configured to send emails.

role stringrequired

Possible values: [signer, approver, observer]

The role of the issuer in the agreement process.

participant_id cuid

If the issuer is a signer or approver this is the ID of the related participant.

signing_room_url urlnullablerequired

The URL to the signing room for the issuer. Only available after the agreement has been finalized for signing.

participants object required

oneOf

MOD1

Array [

string

]

MOD2

version stringrequired

Possible values: [1.0]

The version of the response schema

result_type stringrequired

Possible values: [list]

A non-paginated list of the participant resource.

resource_type stringrequired

Possible values: [participant]

Data contains the participant resource.

data object[]required

MOD3

string

signing_groups object

oneOf

MOD1

Array [

string

]

MOD2

version stringrequired

Possible values: [1.0]

The version of the response schema

result_type stringrequired

Possible values: [list]

A non-paginated list of the signing group resource.

resource_type stringrequired

Possible values: [signing_group]

Data contains the signing group resource.

data object[]required

Array [

id cuidrequired

The unique identifier of the signing group

resource_type stringrequired

Possible values: [signing_group]

name stringrequired

The name of the signing group

status stringrequired

Possible values: [draft, pending, fulfilled]

The status of the signing group

order doublerequired

Possible values: >= 5e-324 and <= 1.7976931348623157e+308

The queue number of the signing group

participants object required

oneOf

MOD1

Array [

string

]

118cb3b11b8a1f3b6b1e60a89f96a8be9da32a0f

version stringrequired

Possible values: [1.0]

The version of the response schema

result_type stringrequired

Possible values: [single]

A single object of the signing_group resource.

resource_type stringrequired

Possible values: [signing_group]

Data contains the signing_group resource.

data objectrequired

The resource data.

id cuidrequired

The unique identifier of the signing group

resource_type stringrequired

Possible values: [signing_group]

name stringrequired

The name of the signing group

status stringrequired

Possible values: [draft, pending, fulfilled]

The status of the signing group

order doublerequired

Possible values: >= 5e-324 and <= 1.7976931348623157e+308

The queue number of the signing group

participants object required

oneOf

MOD1

Array [

string

]

MOD3

string

agreement cuidrequired

The unique identifier of the agreement this signing group belongs to

created_at stringrequired

UTC datetime ISO string

updated_at stringrequired

UTC datetime ISO string

MOD3

string

agreement cuidrequired

The unique identifier of the agreement this signing group belongs to

created_at stringrequired

UTC datetime ISO string

updated_at stringrequired

UTC datetime ISO string

]

MOD3

string

documents object

original_documents objectrequired

main object required

The main document which will be signed.

oneOf

MOD1

string

MOD2

version stringrequired

Possible values: [1.0]

The version of the response schema

result_type stringrequired

Possible values: [single]

A single object of the file resource.

resource_type stringrequired

Possible values: [file]

Data contains the file resource.

data objectrequired

The resource data.

id cuidrequired

The unique identifier of the file

resource_type stringrequired

Possible values: [file]

filename stringrequired

Possible values: non-empty

The complete filename including the file extension

mime_type stringrequired

Possible values: non-empty

The mime type of the file

url url

The signed read url of the file

metadata object

lookup_key stringrequired

A provided lookup key provided by you to help you identify the file.

created_at stringrequired

UTC datetime ISO string

updated_at stringrequired

UTC datetime ISO string

MOD3

string

attachments object

oneOf

MOD1

Array [

string

]

MOD2

version stringrequired

Possible values: [1.0]

The version of the response schema

result_type stringrequired

Possible values: [list]

A non-paginated list of the attachment resource.

resource_type stringrequired

Possible values: [attachment]

Data contains the attachment resource.

data object[]required

Array [

id cuidrequired

The unique identifier of the attachment

resource_type stringrequired

Possible values: [attachment]

agreement cuidrequired

The unique identifier of the agreement which this attachment belongs to

order int64required

Possible values: <= 9007199254740991

The order of this attachment relative to the other attachments

file object required

oneOf

MOD1

string

MOD2

version stringrequired

Possible values: [1.0]

The version of the response schema

result_type stringrequired

Possible values: [single]

A single object of the file resource.

resource_type stringrequired

Possible values: [file]

Data contains the file resource.

data objectrequired

The resource data.

id cuidrequired

The unique identifier of the file

resource_type stringrequired

Possible values: [file]

filename stringrequired

Possible values: non-empty

The complete filename including the file extension

mime_type stringrequired

Possible values: non-empty

The mime type of the file

url url

The signed read url of the file

metadata object

lookup_key stringrequired

A provided lookup key provided by you to help you identify the file.

created_at stringrequired

UTC datetime ISO string

updated_at stringrequired

UTC datetime ISO string

created_at stringrequired

UTC datetime ISO string

updated_at stringrequired

UTC datetime ISO string

]

MOD3

string

signed_document object required

The finalized and signed document.

oneOf

MOD1

string

MOD2

version stringrequired

Possible values: [1.0]

The version of the response schema

result_type stringrequired

Possible values: [single]

A single object of the file resource.

resource_type stringrequired

Possible values: [file]

Data contains the file resource.

data objectrequired

The resource data.

id cuidrequired

The unique identifier of the file

resource_type stringrequired

Possible values: [file]

filename stringrequired

Possible values: non-empty

The complete filename including the file extension

mime_type stringrequired

Possible values: non-empty

The mime type of the file

url url

The signed read url of the file

metadata object

lookup_key stringrequired

A provided lookup key provided by you to help you identify the file.

created_at stringrequired

UTC datetime ISO string

updated_at stringrequired

UTC datetime ISO string

MOD3

string

signing_order objectrequired

enabled booleanrequired

grouped booleanrequired

communication objectrequired

send_emails booleanrequired

default_locale object

oneOf

MOD1

string

MOD2

string

metadata object

lookup_key string

A provided lookup key provided by you to help you identify the agreement.

success_callback_url url

A provided callback url to refer the participants back to post successful action.

updated_at stringrequired

UTC datetime ISO string

created_at stringrequired

UTC datetime ISO string

Example (from schema)

{
  "version": "1.0",
  "result_type": "single",
  "resource_type": "agreement",
  "data": {
    "id": "chuomjzeryjrykz19kxexample",
    "resource_type": "agreement",
    "test_mode": true,
    "status": "draft",
    "cancellation_reason": null,
    "theme": "cjr768bcnwcjsgjovhbexample",
    "issuer": {
      "name": "John Doe",
      "email": "example@example.com",
      "role": "signer",
      "participant_id": "ckajizcomtti5knjgkqexample",
      "signing_room_url": "https://www.zigned.se/sign/ck4fvrdtc9wbvstwndfexample/cu9jfj1qvddazgdoravexample"
    },
    "participants": [
      "clgldkzqvu7j2zcogijexample",
      "cnyrzjxs6i8ywxjxmr3example",
      "ct1vbnyzh08mryo9ny5example"
    ],
    "signing_groups": [
      "clgldkzqvu7j2zcogijexample",
      "cnyrzjxs6i8ywxjxmr3example",
      "ct1vbnyzh08mryo9ny5example"
    ],
    "documents": {
      "original_documents": {
        "main": "ca7ubnojngtlbjyu2k4example",
        "attachments": [
          "clgldkzqvu7j2zcogijexample",
          "cnyrzjxs6i8ywxjxmr3example",
          "ct1vbnyzh08mryo9ny5example"
        ]
      },
      "signed_document": "ca0ajnnsyyy4jkvu7zzexample"
    },
    "signing_order": {
      "enabled": true,
      "grouped": true
    },
    "communication": {
      "send_emails": true,
      "default_locale": "sv-SE"
    },
    "metadata": {
      "lookup_key": "your_internal_customer_id",
      "success_callback_url": "https://yourdomain.com/sign-complete"
    },
    "updated_at": "2024-05-10T12:45:39.352Z",
    "created_at": "2024-05-10T12:45:39.352Z"
  }
}

400

POST /agreements Error response

application/json

Schema

Schema

status stringrequired

Possible values: [error]

error objectrequired
code int64required
Possible values: >= 400 and <= 599
message stringrequired
request_id uuidrequired

Example (from schema)

{
  "status": "error",
  "error": {
    "code": 0,
    "message": "string",
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Loading...