Skip to main content

Create an Agreement

POST 
/agreements

Creates a new agreement in draft status. Use the agreement ID in subsequent requests.

Request​

Body

POST /agreements request body

    issuer object

    The issuer of the agreement. If not provided, the authenticated client will be used.

    name string

    The name of the issuer

    email string

    The email of the issuer. Will be used for communication if email communication is enabled for the agreement.

    role string

    Possible values: [observer, signer, approver]

    Default value: observer

    The role of the issuer within the signing process.

    locale string

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

    Default value: sv-SE

    Optional. The locale for the issuer of the signing process. Can be overridden in the signing room, but the locale provided by you will serve as the default in initial communication. If not specified, the default locale for the agreement will be used.

    send_emails boolean

    Default value: true

    Enables email communication in the agreement process. If not provided, the default value is true. If disabled, you will be responsible for handling all communication.

    automatic_reminders string

    Possible values: [intense, normal]

    Enables automatic reminders for all participants. Disabled by default. If disabled, you can still manually send reminders via the /reminders endpoint or via the signing room.

    trust_level string

    Possible values: [SES, AES, QES]

    Default value: SES

    The minimum trust level used for all signatures in accordance with the eIDAS regulation. If not provided, the default value is SES.

    signing_order boolean

    Default value: false

    Enables signing order for the agreement process. If not provided, the default value is false. If enabled, the signers will be required to sign in the order in which they are defined.

    theme_id cuid

    The ID of the theme to use for the agreement.

    default_locale string

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

    Default value: sv-SE

    The default locale of the signing process. Can be overridden by individual participants, but the default locale determines the primary language used in all communication and UI.

    lookup_key string

    Arbitrary string used to identify the agreement. This ID will be returned in the metadata field of the agreement resource.

    expires_at date-time

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

    Set an expiration date for the signing process. The agreement will be automatically marked as expired after this date and won't be able to be signed. Time part of the date will be ignored and set to 23:59:59:999 UTC.

    success_callback_url url

    An optional callback url to refer the participants back to post taking action.

Responses​

POST /agreements Successful response

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

    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

    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

Loading...