Update an Agreement

PUT 
/agreements/:agreement_id

Updates an agreement. The agreement must be in draft or open status.

Request

Path Parameters

agreement_id cuidrequired

PUT /agreements/:agreement_id parameter

application/json

Body

PUT /agreements/:agreement_id 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 string

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]

The role of the issuer within the signing process.

locale string

Possible values: [sv-SE, en-US]

Default value: sv-SE

Optional. The locale for the issuer of the signing process. Can be overridden in the signing room, but the locale provided by you will serve as the default in initial communication. If not specified, the default locale for the agreement will be used.

send_emails boolean

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, QES]

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

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 object

oneOf

MOD1

id cuidrequired

The ID of the theme to use for the agreement.

MOD2

disconnect booleanrequired

Possible values: [true]

Disconnects the theme from the agreement.

success_callback_url object

oneOf

MOD1

string

MOD2

remove booleanrequired

Possible values: [true]

default_locale string

Possible values: [sv-SE, en-US]

Default value: sv-SE

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.

lookup_key object

oneOf

MOD1

string

MOD2

remove booleanrequired

Possible values: [true]

automatic_reminders object

Enables automatic reminders for all participants. Disabled by default. If disabled, you can still manually send reminders via the /reminders endpoint or via the signing room.

oneOf

MOD1

string

MOD2

remove booleanrequired

Possible values: [true]

expires_at object

oneOf

MOD1

string

MOD2

remove booleanrequired

Possible values: [true]

Responses

200

PUT /agreements/:agreement_id 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, expired]

The status of the agreement

trust_level string

Possible values: [SES, AES, QES]

The minimum trust level for the signatures.

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.

locale stringnullable

Possible values: [sv-SE, en-US]

The locale for the issuer. Can be overridden from the signing room, but this value serves as the default if nothing else is specified. If omitted, the default_locale of the agreement is used.

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

observers 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 observer resource.

resource_type stringrequired

Possible values: [observer]

Data contains the observer resource.

data object[]required

Array [

id cuidrequired

The unique identifier of the observer

resource_type stringrequired

Possible values: [observer]

name stringnullablerequired

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

email stringnullablerequired

The email of the observer. Required if agreement is configured to send emails or if the observer_scope is 'cc'.

locale stringnullable

Possible values: [sv-SE, en-US]

The locale for the observer. Can be overridden from the signing room (if the observer_scope is 'viewer'), but this value serves as the default if nothing else is specified.

observer_scope stringrequired

Possible values: [cc, viewer]

The scope of the observer. If specified as viewer, they will gain access to the signing room to follow the process. Otherwise, they will only receive the final, signed document.

agreement cuidrequired

The unique identifier for the agreement this observer belongs to

signing_room_url urlnullablerequired

The URL to the signing room for the observer. Only available after the agreement is not in draft.

created_at stringrequired

UTC datetime ISO string

updated_at stringrequired

UTC datetime ISO string

]

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 stringnullable

Possible values: [sv-SE, en-US]

The default locale for the agreement. Can be overridden by individual participants/observers from the signing room, but this value serves as the default if nothing else is specified.

automatic_reminders object

enabled booleanrequired

intensity stringnullablerequired

Possible values: [intense, normal]

The intensity of the reminders. The reminders are scheduled with an exponential fall off, but the intensity regulates the base interval. If expiration date is set for the agreement, the reminders become more intense at the end.

recipient_messages objectnullable

version stringrequired

Possible values: [1.0]

The version of the response schema

result_type stringrequired

Possible values: [single]

A single object of the recipient_message resource.

resource_type stringrequired

Possible values: [recipient_message]

Data contains the recipient_message resource.

data objectrequired

The resource data.

id cuidrequired

The unique identifier of the recipient message

resource_type stringrequired

Possible values: [recipient_message]

message_templates objectrequired

version stringrequired

Possible values: [1.0]

The version of the response schema

result_type stringrequired

Possible values: [list]

A non-paginated list of the recipient message template resource.

resource_type stringrequired

Possible values: [recipient_message_template]

Data contains the recipient message template resource.

data object[]required

Array [

id cuidrequired

The unique identifier of the recipient message template

template_string stringrequired

resource_type stringrequired

Possible values: [recipient_message_template]

locale stringrequired

Possible values: [sv-SE, en-US]

created_at stringrequired

UTC datetime ISO string

updated_at stringrequired

UTC datetime ISO string

]

message_template_variables objectrequired

version stringrequired

Possible values: [1.0]

The version of the response schema

result_type stringrequired

Possible values: [list]

A non-paginated list of the recipient message template variable resource.

resource_type stringrequired

Possible values: [recipient_message_template_variable]

Data contains the recipient message template variable resource.

data object[]required

Array [

id cuidrequired

The unique identifier of the recipient message variable

resource_type stringrequired

Possible values: [recipient_message_template_variable]

variable_name stringrequired

variable_value stringrequired

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

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.

expires_at stringnullable

UTC datetime ISO string

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": "c17fwrsbnekjsk974tfexample",
    "resource_type": "agreement",
    "test_mode": true,
    "status": "draft",
    "trust_level": "SES",
    "cancellation_reason": null,
    "theme": "cca9wh5xfsq3htd0xvsexample",
    "issuer": {
      "name": "John Doe",
      "email": "example@example.com",
      "role": "signer",
      "participant_id": "cvszsywqgi6a3jr3v0vexample",
      "signing_room_url": "https://www.zigned.se/sign/cvoppq9maacmsg0uh5nexample/c5keltbncihl7floagsexample",
      "locale": "sv-SE"
    },
    "participants": [
      "celxhjlh7jfsa57bcx7example",
      "ckfahkrcuwyrrhny1dmexample",
      "cbjza2fekvj8bfhylxnexample"
    ],
    "observers": [
      "celxhjlh7jfsa57bcx7example",
      "ckfahkrcuwyrrhny1dmexample",
      "cbjza2fekvj8bfhylxnexample"
    ],
    "signing_groups": [
      "celxhjlh7jfsa57bcx7example",
      "ckfahkrcuwyrrhny1dmexample",
      "cbjza2fekvj8bfhylxnexample"
    ],
    "documents": {
      "original_documents": {
        "main": "cgwespty2ne1de3gbixexample",
        "attachments": [
          "celxhjlh7jfsa57bcx7example",
          "ckfahkrcuwyrrhny1dmexample",
          "cbjza2fekvj8bfhylxnexample"
        ]
      },
      "signed_document": "cc6wrzobsl1wrg32r1vexample"
    },
    "signing_order": {
      "enabled": true,
      "grouped": true
    },
    "communication": {
      "send_emails": true,
      "default_locale": "sv-SE",
      "automatic_reminders": {
        "enabled": true,
        "intensity": "intense"
      },
      "recipient_messages": {
        "version": "1.0",
        "result_type": "single",
        "resource_type": "recipient_message",
        "data": {
          "id": "cexfmnhnknefinudyzjexample",
          "resource_type": "recipient_message",
          "message_templates": {
            "version": "1.0",
            "result_type": "list",
            "resource_type": "recipient_message_template",
            "data": [
              {
                "id": "cy80mik8iwxn0jom970example",
                "template_string": "string",
                "resource_type": "recipient_message_template",
                "locale": "sv-SE",
                "created_at": "2024-01-01T00:00:00.000Z",
                "updated_at": "2024-01-01T00:00:00.000Z"
              }
            ]
          },
          "message_template_variables": {
            "version": "1.0",
            "result_type": "list",
            "resource_type": "recipient_message_template_variable",
            "data": [
              {
                "id": "cutvu1wh0v5nshh7u4mexample",
                "resource_type": "recipient_message_template_variable",
                "variable_name": "string",
                "variable_value": "string",
                "created_at": "2024-01-01T00:00:00.000Z",
                "updated_at": "2024-01-01T00:00:00.000Z"
              }
            ]
          },
          "created_at": "2024-01-01T00:00:00.000Z",
          "updated_at": "2024-01-01T00:00:00.000Z"
        }
      }
    },
    "metadata": {
      "lookup_key": "your_internal_customer_id",
      "success_callback_url": "https://yourdomain.com/sign-complete"
    },
    "expires_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-01T00:00:00.000Z",
    "created_at": "2024-01-01T00:00:00.000Z"
  }
}

400

PUT /agreements/:agreement_id 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...