List Agreements

GET 
/agreements

Retrieves a paginated list of all agreements created by the authenticated client

Request

Query Parameters

limit string

Default value: 50

The number of agreements to return. Max 100

page string

Default value: 1

The page of agreements to return. Default 1

order_by string

Possible values: [desc, asc]

The agreements are ordered by date in descending order by default.

status string

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

The status of the agreements to return.

start_date date-time

Possible values: Value must match regular expression ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?)?Z?$

The earliest creation date of the agreements to return.

end_date date-time

Possible values: Value must match regular expression ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?)?Z?$

The latest creation date of the agreements to return.

lookup_key string

The lookup key of the agreements to return

Responses

200

GET /agreements Successful response

application/json

Schema

Schema

version stringrequired

Possible values: [1.0]

The version of the response schema

result_type stringrequired

Possible values: [paginated_list]

A paginated list of the agreement resource.

resource_type stringrequired

Possible values: [agreement]

Data contains the agreement resource.

data object[]required
The resource data
Array [
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
]
pagination objectrequired

Contains the pagination meta data

limit int64required

Possible values: <= 9007199254740991

The maximum number of items per page

total_pages int64required

Possible values: <= 9007199254740991

The total number of pages

page int64required

Possible values: <= 9007199254740991

The current page number

total_results int64required

Possible values: <= 9007199254740991

The total number of results

Example (from schema)

{
  "version": "1.0",
  "result_type": "paginated_list",
  "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"
    }
  ],
  "pagination": {
    "limit": 100,
    "total_pages": 10,
    "page": 1,
    "total_results": 1000
  }
}

400

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