Update Lifecycle State

POST 
/agreements/:agreement_id/lifecycle

Update the lifecycle status of an agreement: pending, open or cancelled.

Pending: When an agreement is switched to Pending, it is finalized for signing by validating all inputs and, if communication is enabled, sends out all or the first batch of invitations. A Pending agreement can be either cancelled or opened.

Open: If the agreement is opened, the signing process is paused and reset to allow making any changes you would like to do.

Cancelled: If you cancel the agreement, it is moved into an end state where no more changes are allowed. If communication is enabled and the agreement is cancelled, notifications will be sent to all participants.

Request

Path Parameters

agreement_id cuidrequired

POST /agreements/:agreement_id/lifecycle parameter

application/json

Body

POST /agreements/:agreement_id/lifecycle request body

lifecycle_state object required

The lifecycle state of the agreement

oneOf

MOD1

status stringrequired

Possible values: [cancelled]

input object required

oneOf

MOD1

cancellation_type stringrequired

Possible values: [invalid_document, invalid_participant, invalid_email]

MOD2

cancellation_type stringrequired

Possible values: [custom]

reason stringrequired

Possible values: >= 10 characters and <= 255 characters

MOD2

status stringrequired

Possible values: [open]

MOD3

status stringrequired

Possible values: [pending]

Responses

200

POST /agreements/:agreement_id/lifecycle 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

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.

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": "c4y1fah0gtlwm42gbuyexample",
    "resource_type": "agreement",
    "test_mode": true,
    "status": "draft",
    "trust_level": "SES",
    "cancellation_reason": null,
    "theme": "cceciv9dj6gv4xjdkohexample",
    "issuer": {
      "name": "John Doe",
      "email": "example@example.com",
      "role": "signer",
      "participant_id": "c0we2fkh6u4okalpjifexample",
      "signing_room_url": "https://www.zigned.se/sign/cqxfd5wjc9gdgwul3cdexample/cchz66ltlex1jjudwrbexample"
    },
    "participants": [
      "cbe1nayfmye0qndiapaexample",
      "c21htxwpjaybwlqzljcexample",
      "c0jysx87bd3o7ikfbjgexample"
    ],
    "signing_groups": [
      "cbe1nayfmye0qndiapaexample",
      "c21htxwpjaybwlqzljcexample",
      "c0jysx87bd3o7ikfbjgexample"
    ],
    "documents": {
      "original_documents": {
        "main": "c9tv7aw3wqlhje6xle6example",
        "attachments": [
          "cbe1nayfmye0qndiapaexample",
          "c21htxwpjaybwlqzljcexample",
          "c0jysx87bd3o7ikfbjgexample"
        ]
      },
      "signed_document": "cm7wscybpkdc1lsuv1lexample"
    },
    "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-01-01T00:00:00.000Z",
    "created_at": "2024-01-01T00:00:00.000Z"
  }
}

400

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