Retrieve an Agreement

GET 
/agreements/:agreement_id

Retrieves a single agreement created by the authenticated client.

Request

Path Parameters

agreement_id cuidrequired

The ID of the agreement to retrieve

Responses

200

GET /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]

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

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

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 string

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

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": "cyyhjkiotswbtvsjhrrexample",
    "resource_type": "agreement",
    "test_mode": true,
    "status": "draft",
    "trust_level": "SES",
    "cancellation_reason": null,
    "theme": "c1nuxzydjqu8oc8hearexample",
    "issuer": {
      "name": "John Doe",
      "email": "example@example.com",
      "role": "signer",
      "participant_id": "c5zyhjdt1jo00awepiyexample",
      "signing_room_url": "https://www.zigned.se/sign/cjxkxz2rkpwgp2p9jrdexample/ci9dzwg6pdmxxz3bwojexample"
    },
    "participants": [
      "c9odsel5jygpfxist20example",
      "c4ux4gtw3dpgdeubz6jexample",
      "cst0d4xnkmd3zvftvh1example"
    ],
    "observers": [
      "c9odsel5jygpfxist20example",
      "c4ux4gtw3dpgdeubz6jexample",
      "cst0d4xnkmd3zvftvh1example"
    ],
    "signing_groups": [
      "c9odsel5jygpfxist20example",
      "c4ux4gtw3dpgdeubz6jexample",
      "cst0d4xnkmd3zvftvh1example"
    ],
    "documents": {
      "original_documents": {
        "main": "cu8deytgwvbpkg1zdjeexample",
        "attachments": [
          "c9odsel5jygpfxist20example",
          "c4ux4gtw3dpgdeubz6jexample",
          "cst0d4xnkmd3zvftvh1example"
        ]
      },
      "signed_document": "c97twillq5zughlog0uexample"
    },
    "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

GET /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...