Skip to main content

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

    limit string

    Default value: 50

    The number of agreements to return. Max 100

    page string

    The page to return. Default 1. Only for API client versions below 3.7.0, which page with cursor instead and reject page.

    cursor string

    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.

    order_by string

    Possible values: [desc, asc]

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

    search string

    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.

    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

    include_deleted string

    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​

GET /agreements Successful response

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

    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.

    signing_room_link objectnullable

    The current Signing Room Link for the participant. Null before the agreement is finalized, or when no current link exists.

    version stringrequired

    Possible values: [1.0]

    The version of the response schema

    result_type stringrequired

    Possible values: [single]

    A single object of the signing_room_link resource.

    resource_type stringrequired

    Possible values: [signing_room_link]

    Data contains the signing_room_link resource.

    data objectrequired

    The resource data.

    id cuidrequired

    The unique identifier of the Signing Room Link

    resource_type stringrequired

    Possible values: [signing_room_link]

    agreement_id cuidrequired

    The unique identifier of the agreement the link opens

    url urlrequired

    The full signing room URL. It is a bearer credential: anyone with it can open the signing room for this participant.

    status stringrequired

    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.

    expires_at stringrequired

    When the link stops granting access to the signing room

    created_at stringrequired

    UTC datetime ISO string

    updated_at stringrequired

    UTC datetime ISO string

    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
  • Array [
  • string

  • ]
  • observers object
    oneOf
  • Array [
  • string

  • ]
  • signing_groups object
    oneOf
  • Array [
  • string

  • ]
  • documents object
    original_documents objectrequired
    main object required

    The main document which will be signed.

    oneOf

    string

    attachments object
    oneOf
  • Array [
  • string

  • ]
  • signed_document object required

    The finalized and signed document.

    oneOf

    string

    partially_signed_documents object[]
  • Array [
  • id cuidrequired

    The unique identifier of the partially signed document

    created_at stringrequired

    UTC datetime ISO string

    updated_at stringrequired

    UTC datetime ISO string

    status stringrequired

    Possible values: [queued, current, stale, deprecated, failed]

    revision int64nullablerequired

    Possible values: <= 9007199254740991

    delete_scheduled_at stringnullablerequired

    UTC datetime ISO string

    deleted_at stringnullablerequired

    UTC datetime ISO string

  • ]
  • signing_order objectrequired
    enabled booleanrequired
    grouped booleanrequired
    signing_flow string

    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
    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
    mask_pii boolean

    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.

    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

    delete_scheduled_at stringnullable

    The timestamp when deletion is scheduled to occur. Null if not scheduled.

    deleted_at stringnullable

    The timestamp when the agreement was deleted. Null if not deleted.

    deleted boolean

    Whether the agreement has been deleted. Returns true if either scheduled for deletion or if already deleted.

    updated_at stringrequired

    UTC datetime ISO string

    created_at stringrequired

    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.

    oneOf
    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

Loading...