List Agreements
GET/agreements
Retrieves a paginated list of all agreements created by the authenticated client. From API client version 3.7.0 the list is paged with an opaque cursor and returns pagination { limit, has_more, next_cursor } without totals: pass next_cursor as cursor, with the same order_by and filters, until has_more is false. Sending page, an invalid cursor, or a cursor with a different order_by or filters returns a 400. Older API client versions page with page and get total_pages and total_results.
Request
Query Parameters
Default value: 50
The number of agreements to return. Max 100
The page to return. Default 1. Only for API client versions below 3.7.0, which page with cursor instead and reject page.
Requires API client version 3.7.0. The next_cursor of the previous page. Send the same order_by and filters as the request that returned it. Omit for the first page.
Possible values: [desc, asc]
The agreements are ordered by creation date in descending order by default.
Requires API client version 3.7.0. Free text matched case-insensitively against any part of the main document's filename and the lookup key, or exactly against the agreement ID. Must be at least 3 characters after trimming.
Possible values: [draft, pending, fulfilled, cancelled, generating, failed_to_generate, open, expired]
The status of the agreements to return.
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.
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.
The lookup key of the agreements to return
Possible values: [true, false]
Whether to include deleted agreements. Default is false. If true, the agreements will be included even if they are deleted or scheduled for deletion. Deleted agreements have anonymized data and any files will have been permanently deleted.
Responses
- 200
- 400
GET /agreements Successful response
- application/json
- Schema
- Example (from schema)
Schema
- Array [
- MOD1
- MOD2
- MOD3
- MOD1
- MOD2
- MOD3
- Array [
- ]
- MOD1
- MOD2
- MOD3
- Array [
- ]
- Array [
- ]
- MOD1
- MOD2
- MOD3
- Array [
- ]
- Array [
- MOD1
- 118cb3b11b8a1f3b6b1e60a89f96a8be9da32a0f
- MOD3
- Array [
- ]
- MOD1
- MOD3
- Array [
- ]
- ]
- MOD1
- MOD2
- MOD3
- MOD1
- MOD2
- MOD3
- Array [
- ]
- Array [
- MOD1
- MOD2
- ]
- MOD1
- MOD2
- MOD3
- Array [
- ]
- Array [
- ]
- Array [
- ]
- ]
- MOD1
- MOD2
Possible values: [1.0]
The version of the response schema
Possible values: [paginated_list]
A paginated list of the agreement resource.
Possible values: [agreement]
Data contains the agreement resource.
data object[]required
The resource data
The unique identifier of the agreement
Possible values: [agreement]
Indicates if the agreement is created using a development client
Possible values: [draft, pending, fulfilled, cancelled, generating, failed_to_generate, open, expired]
The status of the agreement
Possible values: [SES, AES, QES]
The minimum trust level for the signatures.
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
string
Possible values: [1.0]
The version of the response schema
Possible values: [single]
A single object of the theme resource.
Possible values: [theme]
Data contains the theme resource.
data objectrequired
The resource data.
The unique identifier of the theme
Possible values: [theme]
logo objectrequired
The logo of the theme. This is displayed to the user in all communication and touch points.
Possible values: [1.0]
The version of the response schema
Possible values: [single]
A single object of the file resource.
Possible values: [file]
Data contains the file resource.
data objectrequired
The resource data.
The unique identifier of the file
Possible values: [file]
Possible values: non-empty
The complete filename including the file extension
Possible values: non-empty
The mime type of the file
The signed read url of the file
metadata object
A provided lookup key provided by you to help you identify the file.
UTC datetime ISO string
UTC datetime ISO string
icon objectrequired
The icon of the theme. This is used for the favicon.
Possible values: [1.0]
The version of the response schema
Possible values: [single]
A single object of the file resource.
Possible values: [file]
Data contains the file resource.
data objectrequired
The resource data.
The unique identifier of the file
Possible values: [file]
Possible values: non-empty
The complete filename including the file extension
Possible values: non-empty
The mime type of the file
The signed read url of the file
metadata object
A provided lookup key provided by you to help you identify the file.
UTC datetime ISO string
UTC datetime ISO string
Default value: #000000
The primary color used to create the color palette in the signing room.
metadata object
A provided lookup key provided by you to help you identify the theme.
UTC datetime ISO string
UTC datetime ISO string
string
issuer objectrequired
The issuer of the agreement
The name of the issuer. Required if no email is provided.
The email of the issuer. Required if agreemnt is configured to send emails.
Possible values: [signer, approver, observer]
The role of the issuer in the agreement process.
If the issuer is a signer or approver this is the ID of the related participant.
The URL to the signing room for the issuer. Only available after the agreement has been finalized for signing.
signing_room_link objectnullable
The current Signing Room Link for the participant. Null before the agreement is finalized, or when no current link exists.
Possible values: [1.0]
The version of the response schema
Possible values: [single]
A single object of the signing_room_link resource.
Possible values: [signing_room_link]
Data contains the signing_room_link resource.
data objectrequired
The resource data.
The unique identifier of the Signing Room Link
Possible values: [signing_room_link]
The unique identifier of the agreement the link opens
The full signing room URL. It is a bearer credential: anyone with it can open the signing room for this participant.
Possible values: [active, expired, revoked]
Whether the link still grants access to the signing room. An expired link can be rotated; a revoked link cannot.
When the link stops granting access to the signing room
UTC datetime ISO string
UTC datetime ISO string
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
string
Possible values: [1.0]
The version of the response schema
Possible values: [list]
A non-paginated list of the participant resource.
Possible values: [participant]
Data contains the participant resource.
string
observers object
string
Possible values: [1.0]
The version of the response schema
Possible values: [list]
A non-paginated list of the observer resource.
Possible values: [observer]
Data contains the observer resource.
data object[]required
The unique identifier of the observer
Possible values: [observer]
The name of the observer. Required if no email is provided.
The email of the observer. Required if agreement is configured to send emails or if the observer_scope is 'cc'.
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.
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.
The unique identifier for the agreement this observer belongs to
The URL to the signing room for the observer. Only available after the agreement is not in draft.
signing_room_link objectnullable
The current Signing Room Link for the participant. Null before the agreement is finalized, or when no current link exists.
Possible values: [1.0]
The version of the response schema
Possible values: [single]
A single object of the signing_room_link resource.
Possible values: [signing_room_link]
Data contains the signing_room_link resource.
data objectrequired
The resource data.
The unique identifier of the Signing Room Link
Possible values: [signing_room_link]
The unique identifier of the agreement the link opens
The full signing room URL. It is a bearer credential: anyone with it can open the signing room for this participant.
Possible values: [active, expired, revoked]
Whether the link still grants access to the signing room. An expired link can be rotated; a revoked link cannot.
When the link stops granting access to the signing room
UTC datetime ISO string
UTC datetime ISO string
UTC datetime ISO string
UTC datetime ISO string
string
signing_groups object
string
Possible values: [1.0]
The version of the response schema
Possible values: [list]
A non-paginated list of the signing group resource.
Possible values: [signing_group]
Data contains the signing group resource.
data object[]required
The unique identifier of the signing group
Possible values: [signing_group]
The name of the signing group
Possible values: [draft, pending, fulfilled]
The status of the signing group
Possible values: >= 5e-324 and <= 1.7976931348623157e+308
The queue number of the signing group
participants object required
string
Possible values: [1.0]
The version of the response schema
Possible values: [single]
A single object of the signing_group resource.
Possible values: [signing_group]
Data contains the signing_group resource.
data objectrequired
The resource data.
The unique identifier of the signing group
Possible values: [signing_group]
The name of the signing group
Possible values: [draft, pending, fulfilled]
The status of the signing group
Possible values: >= 5e-324 and <= 1.7976931348623157e+308
The queue number of the signing group
participants object required
string
string
The unique identifier of the agreement this signing group belongs to
UTC datetime ISO string
UTC datetime ISO string
string
The unique identifier of the agreement this signing group belongs to
UTC datetime ISO string
UTC datetime ISO string
string
documents object
original_documents objectrequired
main object required
The main document which will be signed.
string
Possible values: [1.0]
The version of the response schema
Possible values: [single]
A single object of the file resource.
Possible values: [file]
Data contains the file resource.
data objectrequired
The resource data.
The unique identifier of the file
Possible values: [file]
Possible values: non-empty
The complete filename including the file extension
Possible values: non-empty
The mime type of the file
The signed read url of the file
metadata object
A provided lookup key provided by you to help you identify the file.
UTC datetime ISO string
UTC datetime ISO string
string
attachments object
string
Possible values: [1.0]
The version of the response schema
Possible values: [list]
A non-paginated list of the attachment resource.
Possible values: [attachment]
Data contains the attachment resource.
data object[]required
The unique identifier of the attachment
Possible values: [attachment]
The unique identifier of the agreement which this attachment belongs to
Possible values: <= 9007199254740991
The order of this attachment relative to the other attachments
file object required
string
Possible values: [1.0]
The version of the response schema
Possible values: [single]
A single object of the file resource.
Possible values: [file]
Data contains the file resource.
data objectrequired
The resource data.
The unique identifier of the file
Possible values: [file]
Possible values: non-empty
The complete filename including the file extension
Possible values: non-empty
The mime type of the file
The signed read url of the file
metadata object
A provided lookup key provided by you to help you identify the file.
UTC datetime ISO string
UTC datetime ISO string
UTC datetime ISO string
UTC datetime ISO string
string
signed_document object required
The finalized and signed document.
string
Possible values: [1.0]
The version of the response schema
Possible values: [single]
A single object of the file resource.
Possible values: [file]
Data contains the file resource.
data objectrequired
The resource data.
The unique identifier of the file
Possible values: [file]
Possible values: non-empty
The complete filename including the file extension
Possible values: non-empty
The mime type of the file
The signed read url of the file
metadata object
A provided lookup key provided by you to help you identify the file.
UTC datetime ISO string
UTC datetime ISO string
string
partially_signed_documents object[]
The unique identifier of the partially signed document
UTC datetime ISO string
UTC datetime ISO string
Possible values: [queued, current, stale, deprecated, failed]
Possible values: <= 9007199254740991
UTC datetime ISO string
UTC datetime ISO string
signing_order objectrequired
Possible values: [standard, guided]
Signing flow of this agreement. With standard, participants are presented with the main document and its attachments, but it is their responsibility to read them. With guided, each signer and approver must read and acknowledge the main document and each PDF attachment, in order, before they can sign or approve. Requires API client version 3.6.0.
communication objectrequired
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
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
Possible values: [1.0]
The version of the response schema
Possible values: [single]
A single object of the recipient_message resource.
Possible values: [recipient_message]
Data contains the recipient_message resource.
data objectrequired
The resource data.
The unique identifier of the recipient message
Possible values: [recipient_message]
message_templates objectrequired
Possible values: [1.0]
The version of the response schema
Possible values: [list]
A non-paginated list of the recipient message template resource.
Possible values: [recipient_message_template]
Data contains the recipient message template resource.
data object[]required
The unique identifier of the recipient message template
Possible values: [recipient_message_template]
Possible values: [sv-SE, en-US]
UTC datetime ISO string
UTC datetime ISO string
message_template_variables objectrequired
Possible values: [1.0]
The version of the response schema
Possible values: [list]
A non-paginated list of the recipient message template variable resource.
Possible values: [recipient_message_template_variable]
Data contains the recipient message template variable resource.
data object[]required
The unique identifier of the recipient message variable
Possible values: [recipient_message_template_variable]
UTC datetime ISO string
UTC datetime ISO string
UTC datetime ISO string
UTC datetime ISO string
metadata object
Default value: true
Whether to mask PII visually on the signed document. Default is true. Note that this only affects the visual representation of the PII, the actual PII is still present in the evidence package or certificate.
A provided lookup key provided by you to help you identify the agreement.
A provided callback url to refer the participants back to post successful action.
UTC datetime ISO string
The timestamp when deletion is scheduled to occur. Null if not scheduled.
The timestamp when the agreement was deleted. Null if not deleted.
Whether the agreement has been deleted. Returns true if either scheduled for deletion or if already deleted.
UTC datetime ISO string
UTC datetime ISO string
pagination object required
Contains the pagination meta data. From API client version 3.7.0 lists are paged with a cursor and have no totals.
Possible values: <= 9007199254740991
The maximum number of items per page
Possible values: <= 9007199254740991
The total number of pages
Possible values: <= 9007199254740991
The current page number
Possible values: <= 9007199254740991
The total number of results
Possible values: <= 9007199254740991
The requested limit, or the number of items on this page when it is non-empty and holds fewer items than requested
Whether there are more items after this page
Pass as cursor, with the same order_by and filters, to get the next page. Null when there are no more items.
{
"version": "1.0",
"result_type": "paginated_list",
"resource_type": "agreement",
"data": [
{
"id": "c3om2uovzfm0ahxm7yuexample",
"resource_type": "agreement",
"test_mode": true,
"status": "draft",
"trust_level": "SES",
"cancellation_reason": null,
"theme": "csxqz5xik9r7aayiyvvexample",
"issuer": {
"name": "John Doe",
"email": "example@example.com",
"role": "signer",
"participant_id": "cn103j3kybjiqokq0ytexample",
"signing_room_url": "https://www.zigned.se/sign/ckvxkvifauwbv5d8pzbexample/cctxaqdk9q6b3m3knnpexample",
"signing_room_link": {
"version": "1.0",
"result_type": "single",
"resource_type": "signing_room_link",
"data": {
"id": "cfbsvexzrxdiutehsi7example",
"resource_type": "signing_room_link",
"agreement_id": "cgqyyxtdopufdtcsdxpexample",
"url": "https://www.zigned.se/sign/ckvxkvifauwbv5d8pzbexample/cctxaqdk9q6b3m3knnpexample",
"status": "active",
"expires_at": "2024-01-01T00:00:00.000Z",
"created_at": "2024-01-01T00:00:00.000Z",
"updated_at": "2024-01-01T00:00:00.000Z"
}
},
"locale": "sv-SE"
},
"participants": [
"cmarspamclskum33d3eexample",
"cj4hbqynsphsm3fvya5example",
"c5xwti33uqyy3klzrbhexample"
],
"observers": [
"cmarspamclskum33d3eexample",
"cj4hbqynsphsm3fvya5example",
"c5xwti33uqyy3klzrbhexample"
],
"signing_groups": [
"cmarspamclskum33d3eexample",
"cj4hbqynsphsm3fvya5example",
"c5xwti33uqyy3klzrbhexample"
],
"documents": {
"original_documents": {
"main": "cgtitpa1kpc29qx7413example",
"attachments": [
"cmarspamclskum33d3eexample",
"cj4hbqynsphsm3fvya5example",
"c5xwti33uqyy3klzrbhexample"
]
},
"signed_document": "cxflskb8wqgrohhz7jfexample",
"partially_signed_documents": [
{
"id": "c4q77w01nazaysppqzmexample",
"created_at": "2024-01-01T00:00:00.000Z",
"updated_at": "2024-01-01T00:00:00.000Z",
"status": "queued",
"revision": 0,
"delete_scheduled_at": "2024-01-01T00:00:00.000Z",
"deleted_at": "2024-01-01T00:00:00.000Z"
}
]
},
"signing_order": {
"enabled": true,
"grouped": true
},
"signing_flow": "standard",
"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": "cfb9y799c6dxjnnycnxexample",
"resource_type": "recipient_message",
"message_templates": {
"version": "1.0",
"result_type": "list",
"resource_type": "recipient_message_template",
"data": [
{
"id": "cvb8utxcgbnbsht9pqzexample",
"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": "cib8xafdl0q1pewqwkoexample",
"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": {
"mask_pii": true,
"lookup_key": "your_internal_customer_id",
"success_callback_url": "https://yourdomain.com/sign-complete"
},
"expires_at": "2024-01-01T00:00:00.000Z",
"delete_scheduled_at": "2024-01-01T00:00:00.000Z",
"deleted_at": "2024-01-01T00:00:00.000Z",
"deleted": true,
"updated_at": "2024-01-01T00:00:00.000Z",
"created_at": "2024-01-01T00:00:00.000Z"
}
],
"pagination": {}
}
GET /agreements Error response
- application/json
- Schema
- Example (from schema)
Schema
Possible values: [error]
error objectrequired
Possible values: [input_validation_error, bad_request, authorization_error, forbidden_error, not_found_error, conflict_error, internal_server_error]
input_validation_error (400): the request input is invalid. bad_request (400): the request cannot be processed. authorization_error (401): the access token is missing or invalid. forbidden_error (403): the client is not allowed to perform the request. not_found_error (404): the resource does not exist. conflict_error (409): a concurrent change made the request invalid, e.g. the agreement stopped being editable while the request was processed. Re-fetch the resource before retrying. internal_server_error (500): an unexpected error occurred.
Possible values: >= 400 and <= 599
{
"status": "error",
"error": {
"type": "input_validation_error",
"code": 0,
"message": "string",
"request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
}