NAV Navbar
json

Egreement Pro API documentation

Introduction

With the Egreement Pro API you can create and manage digital agreements from your own application.

The API has been designed to make an initial integration as easy as possible while still maintaining a high flexibility and security. We designed the API based on REST principles and the JSON API specification. A notable difference is support for including multiple entities instead of making a call per entity.

The API accepts JSON in request bodies and requires that the Content-Type: application/json header is specified for all such requests. The API will respond with an object where applicable. Depending on context, resources may be returned as single objects or as arrays of objects.

The API supports Webhooks. It means that we are able to do an HTTP(S) callback to an endpoint of your choice each time an event occurs related to an agreement. Webhooks allow you to build fast integrations without the need to repeatedly poll for status updates.

In order to use the API you need to have an active account with API access.

We recommend you to explore our API, browse descriptions of the available attributes and see examples of working requests and responses. If you are using our API for the first time we suggest that you take a close look at the example requests for creating agreements.

Getting Started

Implementing the Egreement Pro API

The intention of this section is to provide a quick start, and some general guidelines for implementing the Egreement Pro API using a common use case, and a bare-bones example.

You will need an Egreement Pro account and API credentials prior to testing this.

Please keep in mind that this is a minimal bare-bones example. The detailed documentation will assist you in achieving more advanced use cases.

The use case

Creating the agreement

JSON payload

{
  "title": "Rental Agreement",
  "expireOn": "20220131T230000Z",
  "parties": [
    {
      "email": "randy.rentee@example.org",
      "firstName": "Randy",
      "lastName": "Rentee",
      "signingConfigurations": [
        {
          "country": "SE",
          "type": "EID"
        }
      ],
      "type": "PRIVATE"
    }
  ],
  "notifications": [
    {
      "recipients": [
        {
          "address": "https://your-app.your-domain/webhook-endpoint",
          "medium": "WEBHOOK"
        }
      ],
      "type": "SIGNED_BY_ALL"
    }
  ],
  "attachments": [
    {
      "data": "JVBERi0xLjQKJeLjz9MKNCAwIG9iagooU2ltcGxlIFBERikKZW5kb2JqCjUgMCBvYmoKPEZFRkYwMDREMDA2MTAwNjcwMDZFMDA3NTAwNzMwMDIwMDBENjAwNkQwMDYxMDA2RT4KZW5kb2JqCjYgMCBvYmoKPD4KZW5kb2JqCjcgMCBvYmoKKE1hYyBPUyBYIDEwLjExLjYgUXVhcnR6IFBERkNvbnRleHQpCmVuZG9iago4IDAgb2JqCihUZXh0RWRpdCkKZW5kb2JqCjkgMCBvYmoKKEQ6MjAxNjA4MTYxMjUyNTRaMDAnMDAnKQplbmRvYmoKMTAgMCBvYmoKPD4KZW5kb2JqCjExIDAgb2JqCls8Pl0KZW5kb2JqCjE0IDAgb2JqCjw8Ci9UeXBlIC9Gb250Ci9TdWJ0eXBlIC9UeXBlMQovQmFzZUZvbnQgL0hlbHZldGljYQovRW5jb2RpbmcgL01hY1JvbWFuRW5jb2RpbmcKPj4KZW5kb2JqCjEzIDAgb2JqCjw8Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9MZW5ndGggMTM5Cj4+CnN0cmVhbQp4nD2OMQvCMBCF9/crbmwGYy8xSbMWdXCyeOAgTtKKYKTt/x9MDMjBfbzHu8ctGLAgGArOa46Wdo61CZ7Yah+9o3XEFR+0VGZ95nCrY+is4Z+z+avS4aPuIj0SesFWhIlJJrCp0UxHnK2EW3N5qXxrmjRXvivGClJln/dVHdWd5ISD5GcHfAHTFCSXCmVuZHN0cmVhbQplbmRvYmoKMTIgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL01lZGlhQm94IFswIDAgNTk1LjI3NiA4NDEuODldCi9SZXNvdXJjZXMgPDwKL0ZvbnQgPDwKL1RUMSAxNCAwIFIKPj4KPj4KL0NvbnRlbnRzIDEzIDAgUgovUGFyZW50IDIgMCBSCj4+CmVuZG9iagoyIDAgb2JqCjw8Ci9UeXBlIC9QYWdlcwovS2lkcyBbMTIgMCBSXQovQ291bnQgMQo+PgplbmRvYmoKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjMgMCBvYmoKPDwKL1RpdGxlIDQgMCBSCi9BdXRob3IgNSAwIFIKL1N1YmplY3QgNiAwIFIKL0NyZWF0b3IgOCAwIFIKL0NyZWF0aW9uRGF0ZSA5IDAgUgovS2V5d29yZHMgMTAgMCBSCi9BQVBMOktleXdvcmRzIDExIDAgUgovUHJvZHVjZXIgKHd3dy5pbG92ZXBkZi5jb20pCi9Nb2REYXRlIChEOjIwMjAwMTE2MDczNTQ2WikKPj4KZW5kb2JqCnhyZWYKMCAxNQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDA3OTIgMDAwMDAgbg0KMDAwMDAwMDczNCAwMDAwMCBuDQowMDAwMDAwODQxIDAwMDAwIG4NCjAwMDAwMDAwMTUgMDAwMDAgbg0KMDAwMDAwMDA0MyAwMDAwMCBuDQowMDAwMDAwMTA5IDAwMDAwIG4NCjAwMDAwMDAxMjcgMDAwMDAgbg0KMDAwMDAwMDE3OSAwMDAwMCBuDQowMDAwMDAwMjA1IDAwMDAwIG4NCjAwMDAwMDAyNDYgMDAwMDAgbg0KMDAwMDAwMDI2NSAwMDAwMCBuDQowMDAwMDAwNTk3IDAwMDAwIG4NCjAwMDAwMDAzODUgMDAwMDAgbg0KMDAwMDAwMDI4NiAwMDAwMCBuDQp0cmFpbGVyCjw8Ci9TaXplIDE1Ci9Sb290IDEgMCBSCi9JbmZvIDMgMCBSCi9JRCBbPDlDQjc4NEM2NjU2RTBERUFBNUJBQjA3NkJDODc4RTQwPiA8OEE2MDhGNkQ3NkMyRDMzNTZCRjIyQTgzNDYxN0QxMUI+XQo+PgpzdGFydHhyZWYKMTAzNgolJUVPRgo=",
      "name": "rental agreement.pdf",
      "type": "BASE64"
    }
  ],
  "accessRights": [
    {
      "type": "GRANT_BY_NAME",
      "actorType": "group",
      "actorName": "Rental Admins",
      "action": "read"
    },
    {
      "type": "GRANT_BY_NAME",
      "actorType": "group",
      "actorName": "Rental Admins",
      "action": "update"
    },
    {
      "type": "GRANT_BY_NAME",
      "actorType": "group",
      "actorName": "Rental Admins",
      "action": "delete"
    }
  ]
}

In order to achieve the use case described above, an agreement named Rental Agreement will be created. To prevent Randy Rentee from signing the agreement after the offer is no longer valid, the agreement will be expired at midnight CET between January 31 and February 1.

As only Randy Rentee will sign the agreement, his private person details are specified. So is the signature method of Swedish BankID. A PDF file, which has been prepared in advance, is Base64 encoded and added to the attachment list.

To get to know when the agreement has been signed by all parties, a webhook notification is configured.

By default, only the creator of the agreement will have access to it. Access Rights are specified to provide full access to all users on the same Egreement Pro account that has access to the Rental Admins group.

URL

Method Resource URL
POST https://{{environment}}/services/api/v1/agreements/
Name Value
Authorization Token {{API_TOKEN}}
Content-Type application/json

Quickly knowing when an agreement has been signed

When the agreement party (Randy Rentee) has signed the agreement, you want to know this in your Rental Application as quickly as possible.

You will achieve this by using webhooks. When the agreement has been signed by Randy Rentee, Egreement Pro will execute an HTTP POST request to the URL specified in the Create Agreement call. When you receive this POST call you must fetch the individual agreement by ID to cross verify.

To have a solution that is resilient to failed webhook calls or other communication hiccups, you should also implement scheduled reconciliation. This is done by periodically listing agreements and specifying that you want to only include agreements that have changed since your last check, e.g.

At 14:00 UTC, you list agreements for the first time. Remember that the API response will be paginated and that you need to check all pages in the response.

At 15:00 UTC, you know that you have checked all agreements that have been modified up until 14:00 UTC, so you only need to query the status for agreements that have changed since 14:00. This is done by applying a filter in your list call. An example URL would be https://environment/services/api/v1/agreements?filter[lastActivityOn]=after:20210115T140000Z. Don't forget that pagination applies here too.

One might be tempted to use the Agreement fetch call (which fetches data for a specific agreement), for all the agreements you need to check the status of, but as the number of agreements you keep track of in Rental Application increases, so will the number of API calls. This is an anti-pattern, and you must not do this.

Now you know how to:

Authentication

API tokens are used for accessing the API.

All API requests must have a proper Authorization header.

Header Value
Authorization Token API_TOKEN

An unauthorized access to the API will result in an HTTP status 401 response.

Environments

Test environments

A separate production test environment is available for development purposes. It uses production certificates for all EID services. Any agreement seals will be made using an untrusted AATL certificate.

The production test environment has the following base URL:

https://pro-prodtest.egreement.com/services/api

Production environment

The production environment is available 24/7 with the exception of service windows and has the following base URL:

https://pro.egreement.com/services/api

Terminology

Account

An organization using the Egreement Pro service will have at least one Account. All Users in the organization are linked to the same Account. The Account can have settings that affects all Users and all Agreements created using the Account.

Accounts are not connected to each other in any way.

Agreement

An Agreement is an object in the Egreement Pro service which includes document files, configurations, signatures and metadata.

Agreements will have different states during their life cycles.

Agreement states

States Description
DRAFT The agreement has been created but does not yet contain all the mandatory attributes to be sent for signing by its parties.
READY_TO_SEND The agreement now contains all the mandatory attributes in order to be sent to its parties for signing.
READY_TO_SIGN The agreement has been made available to all stakeholders and is waiting for the parties to sign it.
SIGNED One or more parties have signed the agreement and are waiting for others to sign.
SIGNED_BY_ALL The agreement has been signed by all parties.
REJECTED The agreement has been rejected by one of the parties and can no longer be signed.
REVOKED The agreement is revoked by the creator and can no longer be signed.
EXPIRED The agreement is expired since it exceeded the configured expiry time period and can no longer be signed.

Event

Transition between states on an agreement or party level.

User

A User is a person who has access to and can login to an Account in the Egreement Pro service. A User is typically a person who creates and manages Agreements or administers Account settings, Users and Groups.

Group

A Group is used to easily manage access rights. A Group has a name and it has Users as members. By sharing an Agreement with a Group, all members of that Group will have access to the Agreement.

By default, agreements created by an API user will not be accessible by any other user. For that reason, it's strongly recommended to utilize sharing (to groups) via Access Rights.

Party

A party of an Agreement is a person or organization that shall sign the agreement.

Party states

States Description
DRAFT The party has been added to the agreement and waiting for the agreement to be sent for signing by its parties.
WAITING_TO_SIGN The party is waiting for his/her turn to sign the agreement.
READY_TO_SIGN The party can sign the agreement.
SIGNED The party has signed the agreement.
REJECTED The party has rejected the agreement.

Shared with

Status of how the agreement is shared with the stakeholders.

States Description
ALL Agreement is shared with all the users under the account
NONE Agreement is not shared with anyone
CUSTOM Agreement is shared with selected users/groups, check accessRights section for details

Agreement creator

The agreement creator is the User who created the Agreement.

Notification

A Notification is a message sent by the Egreement Pro system - typically as a part of a state change - per email, SMS or as a Webhook.

Tags

Tags are custom name-value pairs associated with an Agreement. Tags are not visible to, nor signed by any Party of an Agreement.

Tag limitations

Limitation
Max tags per agreement 100
Max key length 128
Max value length 256
Allowed characters Unicode letters, whitespace, and numbers, plus the following special characters: + - = . _ : /
Reserved prefix egr:
 Leading/trailing space not allowed

Signing methods

Signing methods are different ways for signing an Agreement in the Egreement Pro service.

Please refer to more detailed information in the section Signature methods

Conventions

Attachments encoding

An agreement is created using documents such as a PDF file. When creating an agreement the documents are added as attachments in the API call. All agreement attachments must be Base64 encoded.

Country codes

Country codes are sometimes used by the system to control functionality. For instance, the format of a personal identity number can depend on a country code. The Egreement Pro API use the standard ISO 3166-1 alpha-2 for country codes.

Data encoding

All data sent through the API must be UTF-8 encoded.

Whitespaces

All characters mentioned here are considered whitespace characters.

Date and time

The Egreement Pro API uses the ISO 8601 format for date and time yyyyMMdd'T'HHmmss'Z'. All time parameters in the API are entered and given in UTC (Zulu time zone).

Email addresses

The Egreement Pro API is forgiving when entering email addresses and the responsibility for validating the address is left to the API consumer.

The API requires email addresses to have the following format:

{{something}}@{{domain}}.{{TLD}}

Example of a valid email address: john.smith@example.com

Example of an invalid email address: john.smith@example

Object identifiers

All objects in the API will be referenced by a unique identification key. The API uses a 128-bit Universal Unique Identifier (UUID) version 1, RFC4122.

Personal identity numbers

Personal identity numbers follow different formats depending on country.

Country Type Format
Sweden Standard YYYYMMDDXXXX
Finland Standard DDMMYYCZZZQ

Phone numbers

The Egreement Pro API uses the E.164 recommendation for mobile phone numbers.

The presentation of a number is prefixed with the plus sign (+). Numbers are limited to a maximum of 15 digits The E.164 general format must contain only digits split as follows:

Country code (max 3 digits)

Subscriber number (max 12 digits)

For example the Swedish mobile number 031-400 980 would be represented as +4631400980 - including neither hyphens nor spaces.

Finding International country calling codes

The signing web flow

The signing web flow, hosted by Egreement, makes it possible for the parties to review and sign an agreement. The web flow will also present information about the agreement parties, events, files and other details.

The signing web flow is a web application and it has a responsive design that will support all screen sizes.

There are different options on how to give access to the web flow. Each party will have a unique URL that needs to be used for access. In the default notification configuration the parties will receive a clickable link to the web flow in a mail when the agreement is READY_TO_SIGN. It is also possible to send that notification by SMS.

When integrating with the Egreement Pro API it is also possible to forward the parties to the web flow directly. The unique URL for each party can be obtained from the API. The API also makes it possible to configure return URLs for the continued process in the integrated application.

For more information check: Webflow Links

By configuring return URLs you can control where a party will be forwarded from the web flow depending on outcome. For more information check: Return Links

Success URL

This will be the return URL when a party has successfully signed the agreement.

Failure URL

This will be the return URL for a party if something fails when the party tries to sign the agreement.

Reject URL

This will be the return URL if the party chooses to reject the agreement.

Identification before review

An identification mechanism can be used to restrict access to agreements in the signing web flow.

Each party has a unique link to the agreement which gives them access to review and sign the agreement. The link is not possible to guess but anyone with knowledge of the link can access the agreement. By configuring the system to require the parties to identify using configured methods before granting access to read the agreement it is possible to add an extra level of security.

To enable identification before review, a Identification Configuration has to be supplied for the parties when creating an agreement.

Identification Methods

Signature Methods

EID signatures

With the EID signature method it is possible to create advanced electronic signatures. The following EIDs can be used.

Swedish BankID

Example of signing configuration for Swedish BankID

{
  "signingConfigurations": [
    {
      "type": "EID",
      "country": "SE",
      "identifier": "198901023286"
    }
  ]
}

Swedish BankID is the most common EID in Sweden run by Finansiell ID-Teknik BID AB which is owned by a number of large Swedish banks. It is a PKI based solution with support for file based tokens as well as smart cards, supported on a number of platforms for desktop and mobile.

Using Swedish BankID will result in an advanced electronic signature.

How to Use

Norwegian BankID

Example of signing configuration for Norwegian BankID

{
  "signingConfigurations": [
    {
      "type": "EID",
      "country": "NO"
    }
  ]
}

Norwegian BankID is the largest EID provider in Norway run by BankID Norway AS. It is a PKI based solution that uses a one time password in combination with a personal password, supported on a number of platforms for desktop and mobile.

Using Norwegian BankID will result in an advanced electronic signature.

How to Use

Finnish EID

Example of signing configuration for Finnish EID

{
  "signingConfigurations": [
    {
      "type": "EID",
      "country": "FI",
      "identifier": "131052-308T"
    }
  ]
}

Strong identification broker services are provided by Telia Finland for banks and mobile operators in the Finnish Trust Network ("FTN").

How to Use

Danish MitID

Example of signing configuration for Danish MitID

{
  "signingConfigurations": [
    {
      "type": "EID",
      "country": "DK",
      "actionType": "AUTHENTICATION"
    }
  ]
}

MitID is the Danish EID solution provided to all Danish citizens. It is a replacement of NemID as the former EID solution was called.

A number of solutions exists to use the EID like OTP tokens or mobile apps which results with different Level of Assurance LOA. The default LOA used by Egreement is Substantial.

How to Use

Qualified Electronic Signature

Example of signing configuration for Qualified Electronic Signature

{
  "signingConfigurations": [
    {
      "type": "QES",
      "provider": "SWISSCOM",
      "identifier": "+46701740605"
    }
  ]
}

With the QES signature method it is possible to create qualified electronic signatures, which are currently provided by Swisscom Trust Services.

How to Use

SMS OTP signature

Example of signing configuration for SMS OTP signature

{
  "signingConfigurations": [
    {
      "type": "SMS_OTP",
      "identifier": "+46701740605"
    }
  ]
}

SMS Signature is an electronic signature created by responding to an SMS with context specific content. The content of the SMS is One Time Password (OTP), a 6 digits number sent to the registered mobile no of the signee. The Signee has to submit the OTP in order to sign the agreement. The OTP Number is generated by TOTP algorithm by hashing the current time along with the agreement information. OTP can be regenerated and verified by the same logic provided the given time & agreement information are same.

How to Use

Draw signature

Example of signing configuration for draw signature

{
  "signingConfigurations": [
    {
      "type": "DRAW"
    }
  ]
}

This example will place the first party's signature in a field called 'signature1' and the second party's signature in a field called 'signature2' in the attached PDF file.

{
  "fields": [
    {
      "name": "signature1",
      "value": "{{@agr.parties[0].signature}}"
    },
    {
      "name": "signature2",
      "value": "{{@agr.parties[1].signature}}"
    }
  ]
}

The draw signature is an electronic alternative to traditional handwritten signatures. Using this signature method the signing party draws a signature on a web canvas. The signature will be displayed in the agreement verification in the PDF and can also be configured to be printed in dynamic PDF fields anywhere in the agreement.

This signature method is not classified as an advanced electronic signature. The draw signature method can often be suitable in use cases where advanced electronic signatures are not required.

Producing a signature should preferably be done using a touch screen device.

How to Use

Click signature

Example of signing configuration for click signature

{
  "signingConfigurations": [
    {
      "type": "CLICK"
    }
  ]
}

This click signature is a fast and uncomplicated signature method. The user only has to click a signature button to sign the agreement.

This signature method is not classified as an advanced electronic signature. The click signature method can often be suitable in use cases where advanced electronic signatures are not required and simplicity is of high importance.

How to Use

API signature

Example of signing configuration for API signature

{
  "signingConfigurations": [
    {
      "type": "API"
    }
  ]
}

Example of creating an API signature with API Sign agreement

{
  "firstName": "Per",
  "lastName": "Andersson",
  "country": "SE",
  "signedOn": "20191001T094006Z",
  "personNumber": "198901023286",
  "email": "per.andersson@example.com",
  "mobile": "+46701740605"
}

The API signature method makes it possible to sign a document from an external system. When using this signature method it is the external systems responsibility to create and save a chain of evidence of who made the signature and when.

This signature method is not classified as an advanced electronic signature.

How to Use

Notifications

Notifications are means of agreement related communication, triggered by events and state changes of an agreement. The notifications are sent in two different contexts:

Notification types

States Description
READY_TO_SIGN The agreement has been made available to all stakeholders and is waiting for the parties to sign it.
SIGNED One or more parties have signed the agreement and are waiting for others to sign.
SIGNED_BY_ALL The agreement has been signed by all parties.
REJECTED The agreement has been rejected by one of the parties and can no longer be signed.
REVOKED The agreement is revoked by the creator and can no longer be signed.
EXPIRY_REMINDER The agreement is about to expiry since it exceeded the configured expireOn time period.
EXPIRED The agreement is expired since it exceeded the configured expiry time period and can no longer be signed.
VIEWED The agreement is viewed by the party till the time agreement is not closed or signed by that party.

Notification templates

The system has default email templates configured for every notifiable event.

Localization

The Egreement Pro API has language support for the following languages.

Language/Country Locale
English (United states) en_US
Danish (Denmark) da_DK
Dutch (Netherlands) nl_NL
Finnish (Finland) fi_FI
French (France) fr_FR
German (Germany) de_DE
Italian (Italy) it_IT
Norwegian bokmål (Norway) nb_NO
Polish (Poland) pl_PL
Spanish (Spain) es_ES
Swedish (Sweden) sv_SE

The system will default to en_US if a configured locale is not supported.

It is possible to configure default and fallback locale on the account level. The default locale will be used unless explicitly configured in the API request. The fallback locale will be used if the API request specifies a locale that is currently not supported, such as ru_RU. If locale is not configured at account level, Default Locale will be sv_SE and Fallback Locale will be en_US.

For the web based parts of the system, language is controlled by the users locale setting in the browser. For notifications the locale has to be set specifically to be able to send notifications in the correct language.

Time zones

If it has not been configured elsewhere, the default Europe/Stockholm time zone will be used. It is possible to configure the time zone on the account level and this will override the system default. If the time zone is configured in the API request, both of the above will be overridden.

The time zone configuration is used for proper (time zone dependent) time stamps. When agreements are being accessed via a web browser, the browser time zone will still apply in some cases.

Custom templates

The recommendation is to use the default templates since they are tested across a myriad of different email clients as well as providing localization for multiple languages. It is possible to have fully customized email messages and then use the templateId mentioned later in the documentation, but these templates will not benefit from the email client testing and localization that the default templates provide. In most use cases it will be sufficient to provide a custom message via placeholders.

Email notifications

Notifications can be sent to parties and the creator over email. Either the notifications are explicitly set in the request using available notification types or default settings will be applied by combining email address provided in party with account notification configuration.

SMS notifications

Notifications can be sent to parties over SMS. Either the notifications are explicitly set in the request using available notification types or default settings will be applied by combining mobile number provided in party with account notification configuration.

Webhooks

Webhook JSON payload

{
  "id": "",
  "event": "",
  "timestamp": ""
}

Example of configuring a webhook when creating an agreement

{
  "title": "",
  "expireOn": "20171001T094006Z",
  "deleteOn": "20191001T094006Z",
  "attachments": [],
  "parties": [],
  "notifications": [
    {
      "type": "",
      "templateId": "",
      "locale": "en_US",
      "timeZone": "Europe/Stockholm",
      "placeholders": {},
      "recipients": [
        {
          "address": "https://www.example.com/webhook",
          "medium": "WEBHOOK"
        }
      ]
    }
  ],
  "accessRights": []
}

In the same way that email/SMS notifications can be sent, it is also possible to configure notifications to be sent using a computer-to-computer HTTP(S) call.

A webhook is typically sent when an agreement changes state. A payload of JSON data containing information about the event is sent via POST to a specified endpoint URL over HTTP(S). For security reasons the payload of the Webhooks does not include any sensitive data. Upon receiving a Webhook the recommended action is to retrieve more information about the object referenced by the Webhook via the API.

We highly recommend using Webhooks for best performance. To ensure that your data is in sync we also recommend that you combine Webhooks with user driven API calls and/or polling at longer intervals.

The templates (HTML for email, Plain Text for SMS, and JSON for webhooks) are different, so when you want to create an email notification, an SMS notification and webhook notification, you need to use separate notification blocks instead of having different recipients in a single notification block. Locale for webhook notification will be en_US for now. See the JSON payload example below on the necessary structure.

See the Notification types section for event types.

Agreement Pro API V1

Create Agreement

Example Request JSON

{
  "title": "",
  "expireOn": "20190101T000000Z",
  "deleteOn": "20190102T000000Z",
  "attachments": [
    {
      "name": "dummy.pdf",
      "data": "JVBERi0xLjQKMSAwIG9iago8PAovVGl0bGUgKP7/AFQAaQBjAGsAZQ=",
      "type": "BASE64"
    }
  ],
  "parties": [
    {
      "type": "PRIVATE",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingConfigurations": [
        {
          "type": "EID",
          "country": "SE",
          "identifier": ""
        }
      ]
    }
  ],
  "accessRights": [
    {
      "type": "GRANT_BY_ID",
      "actorType": "user",
      "actorId": "",
      "action": "read"
    },
    {
      "type": "GRANT_BY_NAME",
      "actorType": "group",
      "actorName": "",
      "description": "",
      "action": "read"
    }
  ],
  "links": [
    {
      "type": "WEBFLOW_SIGNING_SUCCEEDED",
      "href": "https://www.example.com/succeed"
    },
    {
      "type": "WEBFLOW_SIGNING_REJECTED",
      "href": "https://www.example.com/rejected"
    },
    {
      "type": "WEBFLOW_SIGNING_FAILED",
      "href": "https://www.example.com/failed"
    }
  ],
  "tags": {
    "key1": "value1",
    "key2": "value2"
  }
}

Description

This API allows you to configure and create a new agreement. In response it presents agreement information in JSON format based on your input.

When an agreement is created successfully it will automatically transit to the READY_TO_SIGN state and any notifications configured for that event will be sent.

URL

Method Resource URL
POST /v1/agreements
Name Value
Authorization Token {TOKEN}
Content-Type application/json

Parameters

Parameter In Description
json data body Agreement

Response

Header

Name Value
ETag {ETag value}
Status Meaning Body Description
200 Success Agreement JSON object Agreement created successfully
400 Failure Error object Invalid JSON object or contract mismatch
422 Failure Error object One or more JSON fields have issues (i.e. missing mandatory fields, invalid date format)

Fetch Agreement

Default response JSON

{
  "data": {
    "id": "",
    "title": "",
    "state": "",
    "createdOn": "",
    "closedOn": "",
    "rejectedOn": "",
    "revokedOn": "",
    "expiredOn": "",
    "expireOn": "",
    "deleteOn": "",
    "lastSignedOn": "",
    "sharedWith": ""
  }
}

Description

This API allows you to fetch agreement information in JSON format based on id. In response it presents agreement information in JSON format based on your input.

URL

Method Resource URL
GET /v1/agreements/{id}
Name Value
Authorization Token {TOKEN}

Parameters

Parameter In Description
id path The agreement UUID
include query Response object configuration.
Possible values: attachments, parties, notifications, accessRights, links, tags, parties.notifications, parties.links, parties.signingConfigurations, parties.signingResult, parties.rejectionResult, attachments.fields, parties.identificationConfigurations, parties.signingConfigurations.tbs, owner, owner.links.
fields query Response object configuration. Return only specific fields in the response on a per-type basis by including a fields[TYPE] parameter. The value of the fields parameter MUST be a comma-separated (U+002C COMMA, “,”) list that refers to the name(s) of the fields to be returned. If a client requests a restricted set of fields for a given resource type, an endpoint MUST NOT include additional fields in resource objects of that type in its response.

Response

Header

Name Value
ETag {ETag value}
Status Meaning Description
200 Success Agreement loaded successfully
403 Failure The user is not authorized to read the agreement
404 Failure The agreement is not found

List Agreements

Example response JSON

{
  "data": [
    {
      "id": "dfe9a640-1316-11e8-89be-3926acd183cb",
      "title": "AAAA",
      "state": "READY_TO_SIGN",
      "createdOn": "20180216T124240Z",
      "postedOn": "20180216T125015Z",
      "expireOn": "20180417T125015Z",
      "deleteOn": "20190417T125015Z",
      "sharedWith": "NONE"
    },
    {
      "id": "e7039f70-1317-11e8-89be-3926acd183cb",
      "title": "AAAA",
      "state": "READY_TO_SEND",
      "createdOn": "20180216T125001Z",
      "sharedWith": "NONE"
    },
    {
      "id": "ae6e69c0-1316-11e8-98e4-f535db932583",
      "title": "AAAA",
      "state": "READY_TO_SEND",
      "createdOn": "20180216T124117Z",
      "sharedWith": "NONE"
    }
  ],
  "meta": {
    "pageNumber": 1,
    "pageSize": 3,
    "totalPages": 10,
    "totalRecords": 29
  },
  "links": {
    "self": "/services/api/v1/agreements?page%5Bnumber%5D=6&page%5Bsize%5D=3",
    "first": "/services/api/v1/agreements?page%5Bnumber%5D=1&page%5Bsize%5D=3",
    "prev": "/services/api/v1/agreements?page%5Bnumber%5D=5&page%5Bsize%5D=3",
    "next": "/services/api/v1/agreements?page%5Bnumber%5D=7&page%5Bsize%5D=3",
    "last": "/services/api/v1/agreements?page%5Bnumber%5D=10&page%5Bsize%5D=3"
  }
}

Description

This API allows you to list and filter the agreements.

URL

Method Resource URL
GET /v1/agreements
Name Value
Authorization Token {TOKEN}

Parameters

Parameter In Description
filter query This parameter is reserved for filtering the agreements based on values of the attributes. Only one filter can be applied per request. More advanced querying will come at a later point in time. Filtering is supported on the following attributes:

filter[state] - This will filter the agreements based on agreement state, supported states are described below:
READY_TO_SIGN - agreement has been posted
SIGNED - agreement is posted but signed by few
AWAITING - Either is READY_TO_SIGN or SIGNED
SIGNED_BY_ALL - agreement is signed by everyone
CLOSED - agreement is closed (same as SIGNED_BY_ALL)
REJECTED - agreement is rejected by party
REVOKED - agreement is revoked by the owner
CANCELLED - agreement is either REJECTED or REVOKED

filter[lastActivityOn] - filter the agreements based on when the last activity occured on the agreements.
Format: SEARCH_TYPE:DATE_1:DATE_2
SEARCH_TYPE
between (search between dates)
DATE_1: used as a from date
DATE_2: used as a to date
DATE_1 & DATE_2 are mandatory

before (search before a date)
DATE_1: used as a before date
DATE_2: not required will be ignored
DATE_1 is mandatory

after (search after a date)
DATE_1: used as an after date
DATE_2: not required will be ignored
DATE_1 is mandatory
DATE_1 & DATE_2
Date format: yyyyMMdd'T'HHmmss'Z'

Agreement state dictates which date will be used for lastActivityOn filtering;
READY_TO_SIGN - filtered on postedOn
SIGNED - filtered on lastSignedOn
SIGNED_BY_ALL - filtered on closedOn
REJECTED - filtered on rejectedOn
REVOKED - filtered on revokedOn

Example: filter[lastActivityOn]=between:20180201T62957Z:20180201T062957Z
include query Response object configuration.
Possible values: attachments, parties, notifications, accessRights, links, tags, parties.notifications, parties.links, parties.signingConfigurations, parties.signingResult, parties.rejectionResult, attachments.fields, parties.identificationConfigurations, parties.signingConfigurations.tbs, owner, owner.links.
fields query Response object configuration. Return only specific fields in the response on a per-type basis by including a fields[TYPE] parameter. The value of the fields parameter MUST be a comma-separated (U+002C COMMA, “,”) list that refers to the name(s) of the fields to be returned. If a client requests a restricted set of fields for a given resource type, an endpoint MUST NOT include additional fields in resource objects of that type in its response.
page[number] query Configure the wanted pagination page.
page[size] query Configure the number of agreements in each pagination.

Response

Status Meaning Body Description
200 Success Agreement list default JSON object or according to include or field parameter. List fetched successfully

Download Agreement

Description

This API allows you to download the agreement in PDF format. The PDF contains all signed agreement parts, documentation and logs producing a self-contained, tamper proof document.

URL

Method Resource URL
GET /v1/agreements/{id}/download
Name Value
Authorization Token {TOKEN}
Accept application/pdf

Constraints

Parameters

Parameter In Description
id path The agreement UUID

Response

Status Meaning Description
200 Success A binary stream containing the PDF file
400 Failure The agreement is not concluded
403 Failure The user is not authorized to read the agreement
404 Failure The agreement is not found

Delete Agreement

Description

This API allows you to delete an agreement from the Egreement Pro service. It is not possible to recover the agreement after it has been deleted.

This method is recommended to use after having Downloaded the agreement if you do not want to store it in the Egreement Pro service.

URL

Method Resource URL
DELETE /v1/agreements/{id}
Name Value
Authorization Token {TOKEN}

Parameters

Parameter In Description
id path The agreement UUID

Response

Status Meaning Description
204 Success The agreement has been deleted
403 Failure The user is not authorized to delete the agreement
404 Failure The agreement is not found

Revoke Agreement

Description

This API allows the agreement Owner to revoke the agreement and delivers the response in JSON format. When the agreement is revoked it is no longer accessible for the parties and it is not possible to sign the agreement. Revoking an agreement will trigger the agreement state to transit to the REVOKED state.

URL

Method Resource URL
GET /v1/agreements/{id}/revoke
Name Value
Authorization Token {TOKEN}

Constraints

Parameters

Parameter In Description
id path The agreement UUID

Response

Header

Name Value
ETag {ETag value}
Status Meaning Body Description
200 Success Agreement default JSON object Agreement revoked successfully
400 Failure Error object Any unexpected error, see Constraints
403 Failure Error object The user is not authorized to revoke the agreement
404 Failure Error object The agreement is not found

Sign Agreement

Example JSON

{
  "firstName": "",
  "lastName": "",
  "country": "",
  "signedOn": "20191001T094006Z",
  "personNumber": "",
  "email": "",
  "mobile": ""
}

Description

This API allows for a party to sign the agreement from an external system. Information about the person signing the agreement can be supplied and will then be included in the final agreement.

URL

Method Resource URL
POST /v1/agreements/{id}/parties/{partyId}/sign/{signingConfigurationId}
Name Value
Authorization Token {TOKEN}
Content-Type application/json

Constraints

Parameters

Parameter In Description
id path The agreement UUID
partyId path The party UUID
signingConfigurationId path The signing configuration UUID
json data body Sign

Response

Header

Name Value
ETag {ETag value}
Status Meaning Body Description
200 Success Agreement default JSON object Agreement signed successfully
400 Failure Error object Any unexpected error, see Constraints
403 Failure Error object The user is not authorized to sign the agreement
404 Failure Error object The agreement or party or signing configuration is not found

Update Agreement

Example JSON

{
  "expireOn": "20190101T000000Z",
  "deleteOn": "20190102T000000Z"
}

Description

This API allows the agreement Owner to update the agreement based on id. Before making a call to this API, extract <ETag value> from the ETag header (via fetch API call) and use it for the If-Match header. Information that needs to be updated can be supplied. The JSON response contains the updated agreement information.

URL

Method Resource URL
PATCH /v1/agreements/{id}
Name Value
Authorization Token {TOKEN}
If-Match <ETag value>
Content-Type application/json

Constraints

Parameters

Parameter In Description
id path The agreement UUID
json data body Update

Response

Header

Name Value
ETag {ETag value}
Status Meaning Body Description
200 Success Agreement default JSON object Agreement updated successfully
400 Failure Error object Any unexpected error, see Constraints
403 Failure Error object The user is not authorized to update the agreement
404 Failure Error object The agreement is not found
412 Failure Error object If-Match header value is missing or incorrect

Update Party Email Address

Example JSON

{
  "address": "new_email@domain.com"
}

Description

This API allows the agreement Owner to update the Email Address of the Party. The Party's Notifications having an Email address that matches the old/previous Party Email will also be updated.

Before making a call to this API, extract <ETag value> from the ETag header (via fetch API call) and use it for the If-Match header. Information that needs to be updated can be supplied. The JSON response contains the updated agreement and party notification information.

URL

Method Resource URL
POST /v1/agreements/{id}/parties/{partyId}/updateEmail
Name Value
Authorization Token {TOKEN}
If-Match <ETag value>
Content-Type application/json

Constraints

Parameters

Parameter In Description
id path The agreement UUID
partyId path The party UUID
json data body Email Update

Response

Header

Name Value
ETag {ETag value}
Status Meaning Body Description
200 Success Party Update JSON object Party's Email Address was updated successfully. The response also contain the updated ETag.
400 Failure Error object Any unexpected error, see Constraints
403 Failure Error object The user is not authorized to update the agreement
404 Failure Error object The agreement or party is not found
412 Failure Error object If-Match header value is missing or incorrect

Fetch Party Notification

Description

This API allows the agreement Owner to fetch a notification of the agreement party. Keep in mind that this API is for the party level notifications.

URL

Method Resource URL
GET /v1/agreements/{id}/parties/{partyId}/notifications/{notificationId}
Name Value
Authorization Token {TOKEN}

Parameters

Parameter In Description
id path The agreement UUID
partyId path The party UUID
notificationId path The notification UUID

Response

Header

Name Value
ETag {ETag value}
Status Meaning Body Description
200 Success Notification Party's Notification. The response also contain the current ETag.
403 Failure Error object The user is not authorized to perform this action on the agreement
404 Failure Error object The agreement or party or notification is not found

Update Party Notification Recipients

Example JSON

[
  {
    "address": "",
    "medium": ""
  },
  {
    "address": "",
    "medium": ""
  }
]

Description

This API allows the agreement Owner to change/replace the recipients of a notification of the agreement party. Information about party and notification needs to extracted from agreement JSON. Keep in mind that this API is for the party level notifications.

URL

Method Resource URL
PUT /v1/agreements/{id}/parties/{partyId}/notifications/{notificationId}/recipients
Name Value
Authorization Token {TOKEN}
If-Match <ETag value>
Content-Type application/json

Constraints

Parameters

Parameter In Description
id path The agreement UUID
partyId path The party UUID
notificationId path The notification UUID
json data body Notification Recipients Update

Response

Header

Name Value
ETag {ETag value}
Status Meaning Body Description
200 Success JSON object Recipients updated successfully. The response also contain the updated ETag.
403 Failure Error object The user is not authorized to perform this action on the agreement
404 Failure Error object The agreement or party or notification is not found
412 Failure Error object If-Match header value is missing or incorrect

Delete Party Notification

Description

This API allows the agreement Owner to delete a notification of the agreement party. Information about party and notification needs to extracted from agreement JSON. Keep in mind that this API is for the party level notifications.

URL

Method Resource URL
DELETE /v1/agreements/{id}/parties/{partyId}/notifications/{notificationId}
Name Value
Authorization Token {TOKEN}
If-Match <ETag value>

Parameters

Parameter In Description
id path The agreement UUID
partyId path The party UUID
notificationId path The notification UUID

Response

Header

Name Value
ETag {ETag value}
Status Meaning Body Description
204 Success N/A Party's Notification was deleted successfully. The response also contain the updated ETag.
403 Failure Error object The user is not authorized to perform this action on the agreement
404 Failure Error object The agreement or party or notification is not found
412 Failure Error object If-Match header value is missing or incorrect

Notify Agreement Party

Example JSON

{
}

Description

This API allows the agreement Owner to notify the agreement party. Information about party and notification needs to extracted from agreement JSON. Keep in mind that this API is for the party level notifications.

URL

Method Resource URL
POST /v1/agreements/{id}/parties/{partyId}/notifications/{notificationId}/notify
Name Value
Authorization Token {TOKEN}
Content-Type application/json

Constraints

Parameters

Parameter In Description
id path The agreement UUID
partyId path The party UUID
notificationId path The notification UUID
json data body empty JSON object, i.e., {}

Response

Status Meaning Body Description
202 Accepted JSON object without additional properties, i.e., {"data":{}} Notification will be scheduled for delivery
400 Failure Error object Any unexpected error, see Constraints
403 Failure Error object The user is not authorized to perform this action on the agreement
404 Failure Error object The agreement or party or notification is not found

JSON Schemas

Agreement Request Schema

{
  "title": "",
  "expireOn": "20191001T094006Z",
  "deleteOn": "20191002T094006Z",
  "configurations": [
    {
      "type": "DEFAULT",
      "locale": "",
      "timeZone": ""
    },
    {
      "type": "NOTIFICATION",
      "locale": "",
      "timeZone": "",
      "sendExpiryReminderOn" : "20191001T094006Z"
    },
    {
      "type": "CONTAINER",
      "locale": "",
      "timeZone": ""
    }
  ],
  "attachments": [
    {
      "title": "",
      "name": "",
      "data": "",
      "type": "BASE64",
      "token": "",
      "fields": [
        {
          "name": "",
          "value": ""
        }
      ]
    },
    {
      "title": "",
      "name": "",
      "type": "TOKEN",
      "token": "",
      "fields": [
        {
          "name": "",
          "value": ""
        }
      ]
    }
  ],
  "parties": [
    {
      "type": "PRIVATE",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "configurations": [
        {
          "type": "NOTIFICATION",
          "locale": "",
          "timeZone": "",
          "sendExpiryReminderOn" : "20191001T094006Z"
        }
      ],
      "signingConfigurations": [
        {
          "type": "",
          "country": "",
          "provider": "",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      ],
      "identificationConfigurations": [
        {
          "type": "",
          "country": "",
          "identifier": ""
        }
      ],
      "notifications": [
        {
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ]
    },
    {
      "type": "COMPANY",
      "name": "",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "companyNumber": "",
      "country": "",
      "signingOrder": 1,
      "configurations": [
        {
          "type": "NOTIFICATION",
          "locale": "",
          "timeZone": "",
          "sendExpiryReminderOn" : "20191001T094006Z"
        }
      ],
      "signingConfigurations": [
        {
          "type": "EID",
          "country": "SE",
          "identifier": ""
        }
      ],
      "identificationConfigurations": [
        {
          "type": "EID",
          "country": "SE",
          "identifier": ""
        }
      ],
      "notifications": [
        {
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ]
    },
    {
      "type": "MY_COMPANY",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "configurations": [
        {
          "type": "NOTIFICATION",
          "locale": "",
          "timeZone": "",
          "sendExpiryReminderOn" : "20191001T094006Z"
        }
      ],
      "signingConfigurations": [
        {
          "type": "EID",
          "country": "SE",
          "identifier": ""
        }
      ],
      "identificationConfigurations": [
        {
          "type": "EID",
          "country": "SE",
          "identifier": ""
        }
      ],
      "notifications": [
        {
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ]
    }
  ],
  "notifications": [
    {
      "type": "",
      "templateId": "",
      "locale": "",
      "timeZone": "",
      "placeholders": {},
      "attachPdf": true,
      "recipients": [
        {
          "address": "",
          "medium": "EMAIL"
        }
      ]
    },
    {
      "type": "",
      "templateId": "",
      "locale": "",
      "timeZone": "",
      "placeholders": {},
      "recipients": [
        {
          "address": "",
          "medium": "SMS"
        }
      ]
    },
    {
      "type": "",
      "templateId": "",
      "locale": "",
      "timeZone": "",
      "placeholders": {},
      "recipients": [
        {
          "address": "",
          "medium": "WEBHOOK"
        }
      ]
    }
  ],
  "links": [
    {
      "type": "WEBFLOW_SIGNING_SUCCEEDED",
      "href": ""
    },
    {
      "type": "WEBFLOW_SIGNING_REJECTED",
      "href": ""
    },
    {
      "type": "WEBFLOW_SIGNING_FAILED",
      "href": ""
    }
  ],
  "accessRights": [
    {
      "type": "GRANT_BY_ID",
      "actorType": "user",
      "actorId": "",
      "action": "read"
    },
    {
      "type": "GRANT_BY_NAME",
      "actorType": "group",
      "actorName": "",
      "description": "",
      "action": "read"
    }
  ],
  "tags": {
    "key1": "value1",
    "key2": "value2"
  }
}

Agreement field descriptions

Field Description
title
String
Required
Title of the agreement
expireOn
String
Time at which the agreement will expire and no parties will be allowed to sign.
Format: yyyyMMdd'T'HHmmss'Z'
Constraints: Time must always be in the future and before the deleteOn.
deleteOn
String
Time at which the agreement will be automatically deleted from the system.
Format: yyyyMMdd'T'HHmmss'Z'
Constraints: Time must always be in the future.
Caution: Agreement can not be retrieved once it is deleted. All the data related to the agreement such as attached files, audit events,configurations etc will also be deleted from the system permanently. If you do not want the agreement to be deleted automatically, do not set any value for this field.
configurations
Array of Configuration
Configuration describe how the agreement level configurations be tweaked.
attachments
Array of Attachment
Required
Files having the content of the agreement. The pages of the agreement will be in the same order as the attachments.
Constraints: At least one attachment must be added
parties
Array of Party
Required
Parties added to be the signatories of the agreement.
Constraints: At least one party must be added.
notifications
Array of Notification
Configuration of notifications. If notifications are not configured, by default all notifications will be sent to owner's email. If notifications are configured but recipients are not provided, owner's email will be used.
accessRights
Array of Access Right
Configuration of access rights.
links
Array of Link
Configuration of return links
tags
Object
Tags can be used to add metadata to the agreement.

Agreement Response Schema

{
  "id": "",
  "title": "",
  "state": "",
  "createdOn": "20171001T094006Z",
  "lastActivityOn": "20171001T094006Z",
  "postedOn": "20171001T094006Z",
  "closedOn": "20171001T094006Z",
  "rejectedOn": "20171001T094006Z",
  "revokedOn": "20171001T094006Z",
  "expiredOn": "20171001T094006Z",
  "expireOn": "20171001T094006Z",
  "deleteOn": "20191001T094006Z",
  "lastSignedOn": "20191001T094006Z",
  "importedOn": "20191001T094006Z",
  "attachments": [
    {
      "id": "",
      "name": "",
      "title": "",
      "mimeType": "",
      "fileSize": "",
      "lastModifiedOn": "",
      "fields": [
        {
          "name": "",
          "value": ""
        }
      ]
    }
  ],
  "parties": [
    {
      "id": "",
      "type": "PRIVATE",
      "state": "",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "signingConfigurations": [
        {
          "id": "",
          "type": "EID",
          "country": "SE",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      ],
      "identificationConfigurations": [
         {
           "id": "",
           "type": "EID",
           "country": "SE",
           "identifier": ""
         }
       ],
      "notifications": [
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ],
      "links": [
        {
            "type": "WEBFLOW_SIGNING",
            "href": ""
        }
      ],
      "signingResult": {
        "signingConfiguration": {
          "id": "",
          "type": "EID",
          "country": "SE",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      },
      "rejectionResult": {
        "reason": ""
      }
    },
    {
      "id": "",
      "type": "COMPANY",
      "state": "",
      "name": "",
      "companyNumber": "",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "signingConfigurations": [
        {
          "id": "",
          "type": "EID",
          "country": "SE",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      ],
      "identificationConfigurations": [
         {
           "id": "",
           "type": "EID",
           "country": "SE",
           "identifier": ""
         }
       ],
      "notifications": [
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ],
      "links": [
        {
            "type": "WEBFLOW_SIGNING",
            "href": ""
        }
      ],
      "signingResult": {
         "signingConfiguration": {
             "id": "",
             "type": "EID",
             "country": "SE",
             "identifier": "",
             "tbs": {
               "sender": "",
               "description": ""
             }
           }
      },
      "rejectionResult": {
         "reason": ""
      }
    },
    {
      "id": "",
      "type": "MY_COMPANY",
      "state": "",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "signingConfigurations": [
        {
          "id": "",
          "type": "EID",
          "country": "SE",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      ],
      "identificationConfigurations": [
         {
           "id": "",
           "type": "EID",
           "country": "SE",
           "identifier": ""
         }
       ],
      "notifications": [
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ],
      "links": [
        {
            "type": "WEBFLOW_SIGNING",
            "href": ""
        }
      ],
      "signingResult": {
        "signingConfiguration": {
          "id": "",
          "type": "EID",
          "country": "SE",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      },
      "rejectionResult": {
        "reason": ""
      }
    }
  ],
  "notifications": [
    {
      "id": "",
      "type": "",
      "templateId": "",
      "locale": "",
      "timeZone": "",
      "placeholders": {},
      "attachPdf": true,
      "recipients": [
        {
          "address": "",
          "medium": "EMAIL"
        }
      ]
    },
    {
      "id": "",
      "type": "",
      "templateId": "",
      "locale": "",
      "timeZone": "",
      "placeholders": {},
      "recipients": [
        {
          "address": "",
          "medium": "SMS"
        }
      ]
    },
    {
      "id": "",
      "type": "",
      "templateId": "",
      "locale": "",
      "timeZone": "",
      "placeholders": {},
      "recipients": [
        {
          "address": "",
          "medium": "WEBHOOK"
        }
      ]
    }
  ],
  "sharedWith": "",
  "links": [
    {
      "type": "WEBFLOW_SIGNING_SUCCEEDED",
      "href": ""
    },
    {
      "type": "WEBFLOW_SIGNING_REJECTED",
      "href": ""
    },
    {
      "type": "WEBFLOW_SIGNING_FAILED",
      "href": ""
    }
  ],
  "tags": {
    "key1": "value1",
    "key2": "value2"
  },
  "accessRights": [
    {
      "id":"",
      "actorType":"group",
      "actorName":"",
      "actorId":"",
      "action":"read"
    }
  ]
}

Field descriptions

Field Description
id
String
UUID of the agreement
title
String
Title of the agreement
state
String
State of agreement
createdOn
String
Time at which the agreement created
lastActivityOn
String
Time at which the last activity occurred on agreement
postedOn
String
Time at which the agreement was sent (posted) to the stakeholders
closedOn
String
Time at which the agreement was concluded (Signed by All)
rejectedOn
String
Time at which the agreement was rejected
revokedOn
String
Time at which the agreement was revoked
expiredOn
String
Time at which the agreement was expired (expired due to the tender timeout period exceeded)
expireOn
String
Time at which the agreement will expire and no parties will be allowed to sign.
Format: yyyyMMdd'T'HHmmss'Z'.
deleteOn
String
Time at which the agreement will be automatically deleted from the system.
Format: yyyyMMdd'T'HHmmss'Z'.
lastSignedOn
String
Time at which the agreement was last signed on
importedOn
String
Time at which the agreement was imported
attachments
Array of Attachment
Files having the content of the agreement.
parties
Array of Party
Parties of the agreement.
notifications
Array of Notification
Configuration of notifications.
sharedWith
String
Status of how the agreement is shared with the stakeholders.
links
Array of Link
Configuration of return links.
accessRights
Object Access Right
Used in granting access to agreement for specific users and groups.
tags
Object Tags
Used to add metadata to the agreement.

Agreement Configuration Request Schema

{
  "configurations": [
    {
      "type": "DEFAULT",
      "locale": "",
      "timeZone": ""
    },
    {
      "type": "NOTIFICATION",
      "locale": "",
      "timeZone": "",
      "sendExpiryReminderOn" : "20191001T094006Z"
    },
    {
      "type": "CONTAINER",
      "locale": "",
      "timeZone": ""
    }
  ]
}

This schema is used to override the default configurations applied by the system for a specific agreement. It applies to all parties of the agreement.

Field descriptions

Field Description
type
String
Required
The type of agreement configuration which would override the account level configurations.
Possible Types:
DEFAULT : This is a generic configuration which allows to configure values in a single place instead of providing the same configuration value for different use cases (types). It primarily serves as a forward-compatible way to provide settings if development and release cycles are long and you won't have the possibility to quickly release to provide new API configuration features.
NOTIFICATION : This type overrides the default system configuration for the notifications sent by the system.
CONTAINER : This type overrides the default system configuration for the agreement PDF container.
locale
String
Only available if the type is DEFAULT, NOTIFICATION or CONTAINER
timeZone
String
Only available if the type is DEFAULT, NOTIFICATION or CONTAINER
sendExpiryReminderOn
String
Only available if the type is NOTIFICATION
Time at which the notification will be sent to recipients about agreement expiry.
Format: yyyyMMdd'T'HHmmss'Z'
Constraints: Time must always be in the future and must at least be a day before expireOn of Agremeent.

Attachment Request Schema

{
  "attachments": [
    {
      "name": "",
      "title": "",
      "type": "BASE64",
      "data": "",
      "lastModifiedOn": "",
      "fields": [
        {
          "name": "",
          "value": ""
        }
      ]
    },
    {
      "title": "",
      "type": "TOKEN",
      "token": "",
      "lastModifiedOn": "",
      "fields": [
        {
          "name": "",
          "value": ""
        }
      ]
    }
  ]
}

Field descriptions

Field Description
name
String
The attachment filename.
Required When type has the value BASE64
title The attachment title.
type
String
Required
Possible values:
BASE64 Accepting the file content in the BASE64 format
TOKEN If the file is already uploaded to the account.
data
String
Content of the attached file.
Required When type has the value BASE64
Format: Base64
token
String
ID of the already upload file.
Required When type has the value TOKEN
lastModifiedOn
String
Last Modified Time of the uploaded File
fields
Array of Objects
Field containing information about editable fields and the values that are to be merged with the given template. It can be used when you have a common business template as a PDF (with fields) and want the business values to be merged dynamically. In this case, attachments.data must contain the Base64 version of the template and fields must contain the information that is to be embedded into the given template.

Attachment Response Schema

{
  "attachments": [
    {
      "id": "",
      "name": "",
      "title": "",
      "mimeType": "",
      "fileSize": "",
      "lastModifiedOn": "",
      "fields": [
        {
          "id": "",
          "name": "",
          "value": ""
        }
      ]
    }
  ]
}

Field descriptions

Field Description
id
String
UUID of attachment
name
String
The attachment filename.
title
String
The attachment title.
mimeType
String
MimeType of attached file.
fileSize
String
Size of attached file.
lastModifiedOn
String
Last Modified Time of the uploaded file
fields
Array of Field
Field containing information about editable fields and the values that are to be merged with the given template.

Attachment Field Request Schema

{
  "fields": [
    {
      "name": "firstName",
      "value": "John"
    },
    {
      "name": "lastName",
      "value": ""
    },
    {
      "name": "drawsignature",
      "value": "{{@agr.parties[0].signature}}"
    }
  ]
}

Field descriptions

Field Description
name
String
Required
Name of the field in the PDF
value
String
Value to be merged into the corresponding PDF field.
Special case: if party draw-signature (Party's Signing Configuration type must be DRAW) is to be merged in a specific PDF field then its value must follow the syntax: {{@agr.parties[0].signature}}, where 0 is index of the party (starting from 0) signature to merge. Exceeding the total number of parties will return an error.

Attachment Field Response Schema

{
  "fields": [
    {
      "id": "",
      "name": "firstName",
      "value": "John"
    },
    {
      "id": "",
      "name": "lastName",
      "value": ""
    },
    {
      "id": "",
      "name": "drawsignature",
      "value": "{{@agr.parties[0].signature}}"
    }
  ]
}

Field descriptions

Field Description
id
String
UUID of field
name
String
Name of the field in the PDF
value
String
Value to be merged into the corresponding PDF field.

Party Request Schema

{
  "parties": [
    {
      "type": "PRIVATE",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "configurations": [
        {
          "type": "NOTIFICATION",
          "locale": "",
          "timeZone": "",
          "sendExpiryReminderOn" : "20191001T094006Z"
        }
      ],
      "signingConfigurations": [
        {
          "type": "EID",
          "country": "SE",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      ],
      "identificationConfigurations": [
        {
          "type": "EID",
          "country": "SE",
          "identifier": ""
        }
      ],
      "notifications": [
        {
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ]
    },
    {
      "type": "COMPANY",
      "name": "",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "companyNumber": "",
      "country": "",
      "signingOrder": 1,
      "configurations": [
        {
          "type": "NOTIFICATION",
          "locale": "",
          "timeZone": "",
          "sendExpiryReminderOn" : "20191001T094006Z"
        }
      ],
      "signingConfigurations": [
        {
          "type": "EID",
          "country": "SE",
          "identifier": ""
        }
      ],
      "notifications": [
        {
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ]
    },
    {
      "type": "MY_COMPANY",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "configurations": [
        {
          "type": "NOTIFICATION",
          "locale": "",
          "timeZone": "",
          "sendExpiryReminderOn" : "20191001T094006Z"
        }
      ],
      "signingConfigurations": [
        {
          "type": "EID",
          "country": "SE",
          "identifier": ""
        }
      ],
      "notifications": [
        {
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ]
    }
  ]
}

Field descriptions

Field Description
type
String
Required
Type of party.
Possible Types:
PRIVATE: a private person is a party.
COMPANY: an organization is a party.
MY_COMPANY: your company is a party.

When MY_COMPANY is used as party, you can not send name,companyNumber or country as part of the request. These details will be taken from the Account Configuration.
firstName
String
First name of the person signing the agreement
lastName
String
Last name of the person signing the agreement
name
String
Name of the company.
Required: Only if parties.type is COMPANY
email
String
Email address of the party.
mobile
String
Mobile phone number of the party.
country
String
Country of origin for the party.
Required if the field personnumberis used.
personNumber
String
Personal identity number of the person signing the agreement. Format is dependent on the field country.
companyNumber
String
Organizational identity number for the company.
Only applicable if parties.type of the party is COMPANY.
signingOrder
Integer
Configuration of the order in which the parties can sign the agreement and posted/created email notifications will be sent.
Order shall start from 1. If the value is not provided, it will be set to 1 and no signing order will be enforced.

Example: An agreement with 3 parties X, Y and Z having the order 1, 2, 3 respectively. When the agreement is created the email notification will only be sent to the party X (having order 1). When party X signs the agreement, the posted email notification will be sent to party Y (having order 2) and the flow continues until the last party signs the agreement.

One or more parties having the same signingOrder will result in a parallel scenario. In this case if 2 parties are having signingOrder 1, they both need to sign the agreement in order for the parties at signingOrder 2 to receive the notifications.
configurations
Array of Configuration
Configuration describe how the system level configurations be tweaked.
signingConfigurations
Array of Signing Configuration
Required
Configuration of how the party shall sign the agreement.
notifications
Array of Notification
Notifications configured at the party level. If notifications are not configured, by default all notifications will be sent to party's email. If notifications are configured but recipients are not provided, party's email will be used.
identificationConfigurations
Array of Identification Configuration
Configuration of how the party shall identify itself for reviewing the agreement.

Party Response Schema

{
  "parties": [
    {
      "id": "",
      "type": "PRIVATE",
      "state": "",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "signingConfigurations": [
        {
          "id": "",
          "type": "EID",
          "country": "SE",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      ],
      "identificationConfigurations": [
         {
           "id": "",
           "type": "EID",
           "country": "SE",
           "identifier": ""
         }
       ],
      "notifications": [
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ],
      "links": [
        {
            "type": "WEBFLOW_SIGNING",
            "href": ""
        }
      ],
      "signingResult": {
        "signingConfiguration": {
          "id": "",
          "type": "EID",
          "country": "SE",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      },
      "rejectionResult": {
        "reason": ""
      }
    },
    {
      "id": "",
      "type": "COMPANY",
      "state": "",
      "name": "",
      "companyNumber": "",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "signingConfigurations": [
        {
          "id": "",
          "type": "EID",
          "country": "SE",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      ],
      "identificationConfigurations": [
        {
          "id": "",
          "type": "EID",
          "country": "SE",
          "identifier": ""
        }
      ],
      "notifications": [
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ],
      "links": [
        {
            "type": "WEBFLOW_SIGNING",
            "href": ""
        }
      ],
      "signingResult": {
        "signingConfiguration": {
          "id": "",
          "type": "EID",
          "country": "SE",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      },
      "rejectionResult": {
        "reason": ""
      }
    },
    {
      "id": "",
      "type": "MY_COMPANY",
      "state": "",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "signingConfigurations": [
        {
          "id": "",
          "type": "EID",
          "country": "SE",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      ],
      "identificationConfigurations": [
        {
          "id": "",
          "type": "EID",
          "country": "SE",
          "identifier": ""
        }
      ],
      "notifications": [
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ],
      "links": [
        {
            "type": "WEBFLOW_SIGNING",
            "href": ""
        }
      ],
      "signingResult": {
        "signingConfiguration": {
          "id": "",
          "type": "EID",
          "country": "SE",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      },
      "rejectionResult": {
        "reason": ""
      }
    }
  ]
}

Field descriptions

Field Description
id
String
UUID of the party
type
String
Type of party.
Possible Types:
PRIVATE: a private person is a party.
COMPANY: an organization is a party.
MY_COMPANY: your company is a party.

When MY_COMPANY is used as party, you can not send name,companyNumber or country as part of the request. These details will be taken from the Account Configuration.
state
String
State of the party
firstName
String
First name of the person signing the agreement
lastName
String
Last name of the person signing the agreement
name
String
Name of the company will be present only if parties.type is COMPANY
email
String
Email address of the party.
mobile
String
Mobile phone number of the party.
country
String
Country of origin for the party, will be present if the field personnumberis used.
personNumber
String
Personal identity number of the person signing the agreement. Format is dependent on the field country.
companyNumber
String
Organizational identity number for the company.
Only applicable if parties.type of the party is COMPANY.
signingOrder
Integer
Configuration of the order in which the parties can sign the agreement and posted/created email notifications will be sent.
Order shall start from 1. If the value is not provided, it will be set to 1 and no signing order will be enforced.

Example: An agreement with 3 parties X, Y and Z having the order 1, 2, 3 respectively. When the agreement is created the email notification will only be sent to the party X (having order 1). When party X signs the agreement, the posted email notification will be sent to party Y (having order 2) and the flow continues until the last party signs the agreement.

One or more parties having the same signingOrder will result in a parallel scenario. In this case if 2 parties are having signingOrder 1, they both need to sign the agreement in order for the parties at signingOrder 2 to receive the notifications.
signingConfigurations
Array of Signing Configuration
Configuration of how the party shall sign the agreement.
identificationConfigurations
Array of Identification Configuration
Configuration of how the party shall identify themself for reviewing the agreement.
signingResult
Signing Result
Response only
Signing result for the party. Only present for parties that have signed the agreement.
rejectionResult
Rejection Result
Response only
Rejection result for the party. Only present for the party that has rejected the agreement.
notifications
Array of Notification
Notifications configured at the party level.
links
Array of Link
Webflow Signing Url for the party

Party Configuration Request Schema

{
  "configurations": [
    {
      "type": "NOTIFICATION",
      "locale": "",
      "timeZone": "",
      "sendExpiryReminderOn" : "20191001T094006Z"
    }
  ]
}

This schema is used to override the default configurations applied by the system for a specific agreement party.

Field descriptions

Field Description
type
String
Required
The type of party configuration which would override the account level configurations.
Possible Types:
NOTIFICATION
locale
String
Only available if the type is NOTIFICATION
This is used to override the default configured language. If locale is set and party.notifications are not configured with locale, this locale will be used to set language for all default notifications.
timeZone
String
Only available if the type is NOTIFICATION
This is used to override the default configured time zone.
sendExpiryReminderOn
String
Only available if the type is NOTIFICATION
Time at which the notification will be sent to recipients about agreement expiry.
Format: yyyyMMdd'T'HHmmss'Z'
Constraints: Time must always be in the future and must at least be a day before expireOn of Agremeent.

Signing Configuration Request Schema

{
  "signingConfigurations": [
    {
      "type": "",
      "country": "",
      "provider": "",
      "identifier": "",
      "actionType": "",
      "tbs": {
        "sender": "",
        "description": ""
      }
    }
  ]
}

This schema is used to configure how a party shall sign an agreement.

Field descriptions

Field Description
type
String
Required
The type of signature method that the party shall use to sign the agreement.
Possible Types:
EID, QES, SMS_OTP, CLICK, DRAW, API
country
String
Country of origin for the party.
Required if the field typeis EID. Otherwise N/A.
provider
String
Signature method provider.
Required if the field typeis QES. Otherwise N/A.
identifier
String
When type is EID, this field specifies the Personal identity number of the person signing the agreement. When type is QES or SMS_OTP, it specifies the associated mobile phone number.
Required if the field type is QES or SMS_OTP.

Case 1 - type is EID
The identifier must be a valid Personal identity number.
The format of the personal identity number is dependent on the field country when type is EID.
Caution: identifier is an optional field. If it is not specified the party will be able to sign the agreement with an EID with any personal identity number.

Case 2 - type is QES
The identifier shall be a valid mobile phone number.

Case 3 - type is SMS_OTP
The identifier shall be a valid mobile phone number.
actionType
String
If type is EID and country is DK, this field specifies the signature action to use for signing the agreement.
Required if the field type is EID and countryis DK.
Possible Types:
AUTHENTICATION
tbs
TBS
Configuration of the To Be Signed text, TBS, when using Swedish BankID.
TBS is the text that will be displayed in the BankID application when signing.
This can be used to add information about the sender and a description of the agreement to the TBS.

Only applicable if type is EID and country is SE.

Signing Configuration Response Schema

{
  "signingConfigurations": [
    {
      "id": "",
      "type": "",
      "country": "",
      "provider": "",
      "identifier": "",
      "tbs": {
        "sender": "",
        "description": ""
      }
    }
  ]
}

Field descriptions

Field Description
id
String
UUID of the signing configuration
type
String
The type of signature method that the party has configure to sign the agreement.
Possible Types:
EID, QES, SMS_OTP, CLICK, DRAW, API
country
String
Country of origin for the party, will be present if the field typeis EID. Otherwise N/A.
provider
String
Signature method provider. Will be present if the field typeis QES. Otherwise N/A.
identifier
String
When type is EID, this field specifies the Personal identity number of the person signing the agreement. When type is QES or SMS_OTP, it specifies the associated mobile phone number.
tbs
TBS
Configuration of the To Be Signed text, TBS, when using Swedish BankID.
TBS is the text that will be displayed in the BankID application when signing.
This can be used to add information about the sender and a description of the agreement to the TBS.

Only applicable if type is EID and country is SE.

TBS Schema

{
  "sender": "",
  "description": ""
}

This can be used to add information about the sender and a description of the agreement to the TBS when using Swedish BankID. TBS is the text that will be displayed in the BankID application when signing.

Field descriptions

Field Description
sender
String
This field is used to add information about the sender in the TBS.
Limitation: Only 25 chars Allowed.
description
String
This field is used to add a description in the TBS.
Limitation: Only 400 chars Allowed.

Identification Configuration Request Schema

{
  "identificationConfigurations": [
    {
      "type": "SMS_OTP",
      "identifier": "+999999999999"
    },
    {
      "type": "EID",
      "country": "SE",
      "identifier": "1999999999"
    }
  ]
}

Field descriptions

This schema is used to enable identification before review in the signing web flow.

Field Description
type
String
Type of identification.
Possible Types:
SMS_OTP: This method requires the party to identify using a One Time Password, OTP, sent by SMS.
EID: This method requires the party to identify using Swedish BankID.
country
String
Country of origin for the party, required if the field type is EID. Otherwise N/A.
identifier
String
If type is EID this field can contain the Personal identity number
If type is SMS_OTP, this field must contain the mobile phone number

Identification Configuration Response Schema

{
  "identificationConfigurations": [
    {
      "id":"",
      "type": "SMS_OTP",
      "identifier": "+999999999999"
    },
    {
      "id": "",
      "type": "EID",
      "country": "SE",
      "identifier": "1999999999"
    }
  ]
}

Field descriptions

Field Description
id
String
UUID of the identification
type
String
Type of identification.
Possible Types:
SMS_OTP: This method requires the party to identify using a One Time Password, OTP, sent by SMS.
EID: This method requires the party to identify using Swedish BankID.
country
String
Country of origin for the party, will be present if the field type is EID. Otherwise N/A.
identifier
String
If type is EID this field can contain the Personal identity number
If type is SMS_OTP, this field will contain the mobile phone number

Notification Request Schema

{
  "notifications": [
    {
      "type": "",
      "templateId": "",
      "locale": "",
      "timeZone": "",
      "placeholders": {},
      "attachPdf": true,
      "recipients": [
        {
          "address": "",
          "medium": "EMAIL"
        }
      ]
    }
  ]
}

Caution: please read carefully as parties.notifications may be manipulated by the system depending on the configuration.

Kindly go through the use cases carefully and create your request based on your business requirement.

Case 1: when not specifying notifications

Notifications will be sent for all events to the party's email address. In most cases a reasonable default. It simplifies your JSON payload too.

Case 2: notifications set to an empty array - []

No notifications will be sent at all (as requested). Can be used when you want to handle the communication with the party in your end.

Case 3: notifications.templateId is not set

Default templates will be used. When omitting notifications.templateId you can still specify email locale to get the emails in the requested language (where supported).

Field descriptions

Field Description
type
String
Required
The type of notification.
Possible Types:
READY_TO_SIGN: Notifies the parties that an agreement is awaiting signatures from one or more parties. A Notification includes a link to the agreement.
SIGNED: Notifies the parties that an agreement has been signed and is pending signatures from one or more parties.
SIGNED_BY_ALL: Notifies the parties that an agreement has been closed (i.e. signed by all parties). A PDF version of the agreement is attached to this notification.
REJECTED: Notifies the parties that an agreement has been rejected by a party.
REVOKED: Notifies the parties that an agreement has been revoked from the creator’s side.
EXPIRY_REMINDER: Notifies the parties that an agreement is about to expire (i.e. expireOn has been passed). By default, the notification will be sent one day before expireOn. This can be changed by configuring sendExpiryReminderOn for Agreement Configuration or Party Configuration.
EXPIRED: Notifies the parties that an agreement has been automatically expired.
VIEWED: Notifies that an agreement has been viewed by the party.
templateId
String
Customized notification template. Shall only be used when customized templates are setup together with Egreement support. Default template will be used if not configured
locale
String
Locale for the configured template. Controls the language.
timeZone
String
TimeZone for the configured template. Controls the date formatting.
placeholders
String
Key-value pair that is used to fill the template placeholders. It is mandatory when you use any placeholders (i.e., namespace) in the template. All standard email templates have support for the message placeholder which can be used to send a custom message to the party. Placeholder values that are not provided will be rendered blank.
Example: If you configured the template as,
"Hi {{user}}, Agreement has been rejected by {{party}}"
then, you shall send placeholders as, placeholders: {"user": "John Smith", "party": "Bob Adams"}
Output will be
"Hi John Smith, Agreement has been rejected by Bob Adams"
attachPdf
String
Applicable only if type is SIGNED_BY_ALL
If set to true, the final PDF will be attached.
If set to false, the PDF will not be attached.
If it is not set or set to null, the request will check the account level configurations.
If enabled, then the final PDF will be attached.
If disabled, then the final PDF will not be attached.
If not configured, then the final PDF will not be attached.
recipients
Array of Recipient
Configuration of to whom the notification will be sent.

Notification Response Schema

{
  "notifications": [
    {
      "id": "",
      "type": "",
      "templateId": "",
      "locale": "",
      "timeZone": "",
      "placeholders": {},
      "attachPdf": true,
      "sendOn":"",
      "recipients": [
        {
          "address": "",
          "medium": "EMAIL"
        }
      ]
    }
  ]
}

Field descriptions

Field Description
id
String
UUID of the notification
type
String
The type of notification.
Possible Types:
READY_TO_SIGN: Notifies the parties that an agreement is awaiting signatures from one or more parties. A Notification includes a link to the agreement.
SIGNED: Notifies the parties that an agreement has been signed and is pending signatures from one or more parties.
SIGNED_BY_ALL: Notifies the parties that an agreement has been closed (i.e. signed by all parties). A PDF version of the agreement is attached to this notification.
REJECTED: Notifies the parties that an agreement has been rejected by a party.
REVOKED: Notifies the parties that an agreement has been revoked from the creator’s side.
EXPIRY_REMINDER: Notifies the parties that an agreement is about to expire (i.e. expireOn has been passed). By default, the notification will be sent one day before expireOn. This can be changed by configuring sendExpiryReminderOn for Agreement Configuration or Party Configuration.
EXPIRED: Notifies the parties that an agreement has been automatically expired.
VIEWED: Notifies that an agreement has been viewed by the party.
templateId
String
Customized notification template. Shall only be used when customized templates are setup together with Egreement support. Default template will be used if not configured
locale
String
Locale for the configured template. Controls the language.
timeZone
String
TimeZone for the configured template. Controls the date formatting.
placeholders
String
Key-value pair that is used to fill the template placeholders. It is mandatory when you use any placeholders (i.e., namespace) in the template. All standard email templates have support for the message placeholder which can be used to send a custom message to the party. Placeholder values that are not provided will be rendered blank.
Example: If you configured the template as,
"Hi {{user}}, Agreement has been rejected by {{party}}"
then, you shall send placeholders as, placeholders: {"user": "John Smith", "party": "Bob Adams"}
Output will be
"Hi John Smith, Agreement has been rejected by Bob Adams"
attachPdf
String
Applicable only if type is SIGNED_BY_ALL
If set to true, the final PDF will be attached.
If set to false, the PDF will not be attached.
If it is not set or set to null, the request will check the account level configurations.
If enabled, then the final PDF will be attached.
If disabled, then the final PDF will not be attached.
If not configured, then the final PDF will not be attached.
sendOn
String
Only available if notification type is EXPIRY_REMINDER and if sendExpiryReminderOn is configured for Agreement Configuration or Party Configuration .
Time at which the notification will be sent to recipients about agreement expiry.
recipients
Array of Recipient
Configuration of to whom the notification will be sent.

Recipient Request Schema

{
  "recipients": [
    {
      "medium": "",
      "address": ""
    },
    {
      "medium": "",
      "address": ""
    }
  ]
}

Field descriptions

Field Description
medium
String
Required
Possible Types :
EMAIL, SMS, WEBHOOK
address
String
Required
Address to which the notification shall be sent.
Email address if medium is EMAIL.
Mobile phone number if medium is SMS.
URL if medium is WEBHOOK.

Recipient Response Schema

{
  "recipients": [
    {
      "medium": "",
      "address": ""
    },
    {
      "medium": "",
      "address": ""
    }
  ]
}

Field descriptions

Field Description
medium
String
Possible Types :
EMAIL, SMS, WEBHOOK
address
String
Address to which the notification shall be sent.
Email address if medium is EMAIL.
Mobile phone number if medium is SMS.
URL if medium is WEBHOOK.

Party Notification Request Schema

{
  "notifications": [
    {
      "type": "",
      "templateId": "",
      "locale": "",
      "timeZone": "",
      "placeholders": {},
      "attachPdf": true,
      "recipients": [
        {
          "address": "",
          "medium": "EMAIL"
        }
      ]
    }
  ]
}

Caution: please read carefully as parties.notifications may be manipulated by the system depending on the configuration.

Kindly go through the use cases carefully and create your request based on your business requirement.

Case 1: when not specifying notifications

Notifications will be sent for all events to the party's email address. In most cases a reasonable default. It simplifies your JSON payload too.

Case 2: notifications set to an empty array - []

No notifications will be sent at all (as requested). Can be used when you want to handle the communication with the party in your end.

Case 3: notifications.templateId is not set

Default templates will be used. When omitting notifications.templateId you can still specify email locale to get the emails in the requested language (where supported).

Field descriptions

Field Description
type
String
Required
The type of notification.
Possible Types:
READY_TO_SIGN: Notifies the parties that an agreement is awaiting signatures from one or more parties. A Notification includes a link to the agreement.
SIGNED: Notifies the parties that an agreement has been signed and is pending signatures from one or more parties.
SIGNED_BY_ALL: Notifies the parties that an agreement has been closed (i.e. signed by all parties). A PDF version of the agreement is attached to this notification.
REJECTED: Notifies the parties that an agreement has been rejected by a party.
REVOKED: Notifies the parties that an agreement has been revoked from the creator’s side.
EXPIRY_REMINDER: Notifies the parties that an agreement is about to expire (i.e. expireOn has been passed). By default, the notification will be sent one day before expireOn. This can be changed by configuring sendExpiryReminderOn for Agreement Configuration or Party Configuration.
EXPIRED: Notifies the parties that an agreement has been automatically expired.
VIEWED: Notifies that an agreement has been viewed by the party.
templateId
String
Customized notification template. Shall only be used when customized templates are setup together with Egreement support. Default template will be used if not configured
locale
String
Locale for the configured template. Controls the language.
timeZone
String
TimeZone for the configured template. Controls the date formatting.
placeholders
String
Key-value pair that is used to fill the template placeholders. It is mandatory when you use any placeholders (i.e., namespace) in the template. All standard email templates have support for the message placeholder which can be used to send a custom message to the party. Placeholder values that are not provided will be rendered blank.
Example: If you configured the template as,
"Hi {{user}}, Agreement has been rejected by {{party}}"
then, you shall send placeholders as, placeholders: {"user": "John Smith", "party": "Bob Adams"}
Output will be
"Hi John Smith, Agreement has been rejected by Bob Adams"
attachPdf
String
Applicable only if type is SIGNED_BY_ALL
If set to true, the final PDF will be attached.
If set to false, the PDF will not be attached.
If it is not set or set to null, the request will check the account level configurations.
If enabled, then the final PDF will be attached.
If disabled, then the final PDF will not be attached.
If not configured, then the final PDF will not be attached.
recipients
Array of Recipient
Configuration of to whom the notification will be sent.

Party Notification Response Schema

{
  "notifications": [
    {
      "id": "",
      "type": "",
      "templateId": "",
      "locale": "",
      "timeZone": "",
      "placeholders": {},
      "attachPdf": true,
      "sendOn":"",
      "recipients": [
        {
          "address": "",
          "medium": "EMAIL"
        }
      ]
    }
  ]
}

Field descriptions

Field Description
id
String
UUID of the notification
type
String
The type of notification.
Possible Types:
READY_TO_SIGN: Notifies the parties that an agreement is awaiting signatures from one or more parties. A Notification includes a link to the agreement.
SIGNED: Notifies the parties that an agreement has been signed and is pending signatures from one or more parties.
SIGNED_BY_ALL: Notifies the parties that an agreement has been closed (i.e. signed by all parties). A PDF version of the agreement is attached to this notification.
REJECTED: Notifies the parties that an agreement has been rejected by a party.
REVOKED: Notifies the parties that an agreement has been revoked from the creator’s side.
EXPIRY_REMINDER: Notifies the parties that an agreement is about to expire (i.e. expireOn has been passed). By default, the notification will be sent one day before expireOn. This can be changed by configuring sendExpiryReminderOn for Agreement Configuration or Party Configuration.
EXPIRED: Notifies the parties that an agreement has been automatically expired.
VIEWED: Notifies that an agreement has been viewed by the party.
templateId
String
Customized notification template. Shall only be used when customized templates are setup together with Egreement support. Default template will be used if not configured
locale
String
Locale for the configured template. Controls the language.
timeZone
String
TimeZone for the configured template. Controls the date formatting.
placeholders
String
Key-value pair that is used to fill the template placeholders. It is mandatory when you use any placeholders (i.e., namespace) in the template. All standard email templates have support for the message placeholder which can be used to send a custom message to the party. Placeholder values that are not provided will be rendered blank.
Example: If you configured the template as,
"Hi {{user}}, Agreement has been rejected by {{party}}"
then, you shall send placeholders as, placeholders: {"user": "John Smith", "party": "Bob Adams"}
Output will be
"Hi John Smith, Agreement has been rejected by Bob Adams"
attachPdf
String
Applicable only if type is SIGNED_BY_ALL
If set to true, the final PDF will be attached.
If set to false, the PDF will not be attached.
If it is not set or set to null, the request will check the account level configurations.
If enabled, then the final PDF will be attached.
If disabled, then the final PDF will not be attached.
If not configured, then the final PDF will not be attached.
sendOn
String
Only available if notification type is EXPIRY_REMINDER and if sendExpiryReminderOn is configured for Agreement Configuration or Party Configuration .
Time at which the notification will be sent to recipients about agreement expiry.
recipients
Array of Recipient
Configuration of to whom the notification will be sent.

Party Recipient Request Schema

{
  "recipients": [
    {
      "medium": "",
      "address": ""
    },
    {
      "medium": "",
      "address": ""
    }
  ]
}

Field descriptions

Field Description
medium
String
Required
Possible Types :
EMAIL, SMS
address
String
Required
Address to which the notification shall be sent.
Email address if medium is EMAIL.
Mobile phone number if medium is SMS.

Party Recipient Response Schema

{
  "recipients": [
    {
      "medium": "",
      "address": ""
    },
    {
      "medium": "",
      "address": ""
    }
  ]
}

Field descriptions

Field Description
medium
String
Possible Types :
EMAIL, SMS
address
String
Address to which the notification shall be sent.
Email address if medium is EMAIL.
Mobile phone number if medium is SMS.

Access Right Request Schema

{
  "accessRights": [
    {
      "type": "GRANT_BY_ID",
      "actorType": "user",
      "actorId": "",
      "action": "read"
    },
    {
      "type": "GRANT_BY_NAME",
      "actorType": "group",
      "actorName": "HR",
      "description": "Human resources",
      "action": "read"
    }
  ]
}

Granting the access to specific users and groups.

For convenience it is possible to refer to groups by name instead of ID. If the group name does not exist, the system will automatically create it.

Field descriptions

Field Description
type
String
Required
Possible Types:
GRANT_BY_ID: Granting the access to the actor based on id. actorType is then used to refer actor.
GRANT_BY_NAME: Granting the access to the actor based on Name. If the given name is not found the server will create an actor and grant access to the resource. Proper system role will be required for the group creation.
actorType
String
Required
Type of the entity to which the access is granted.
Possible Types:
user: Access will be granted to the entity type user. Not applicable if type is GRANT_BY_NAME
group: Access will be granted to the entity type group (group of users)
account: Access will be granted to the entity type account (all the users and groups of the account). Not applicable if type is GRANT_BY_NAME.
description
String
Description of the group to set for a non-existent group. Only applicable when actorType is GRANT_BY_NAME.
actorId
String
Id of the entity configured by actorType.
Required if actorType is GRANT_BY_ID.
action
String
Required
Rights granted to the given actorId.
Possible Types:
read: actor will be able to read the created agreement (get/list)
update: actor will be able to update/add parties/notifications/attachments/accessRights of the granted agreement
delete: actor will be able to delete agreement or parties/notifications/attachments/accessRights of the granted agreement

Access Right Response Schema

{
  "accessRights": [
    {
      "id":"",
      "actorType": "user",
      "actorId": "",
      "actorName": "",
      "action": "read"
    }
  ]
}

Field descriptions

Field Description
id
String
UUID of the access rights
actorType
String
Type of the entity to which the access is granted.
Possible Types:
user: Access is granted to the entity type user.
group: Access is granted to the entity type group (group of users)
account: Access is granted to the entity type account (all the users and groups of the account).
actorId
String
Id of the entity configured by actorType.
actorName
String
Name of the actor
action
String
Rights granted to the given actorId.
Possible Types:
read: actor will be able to read the created agreement (get/list)
update: actor will be able to update/add parties/notifications/attachments/accessRights of the granted agreement
delete: actor will be able to delete agreement or parties/notifications/attachments/accessRights of the granted agreement
{
  "links": [
    {
      "type": "WEBFLOW_SIGNING_SUCCEEDED",
      "href": ""
    },
    {
      "type": "WEBFLOW_SIGNING_REJECTED",
      "href": ""
    },
    {
      "type": "WEBFLOW_SIGNING_FAILED",
      "href": ""
    }
  ]
}

Configuration of return URLs for the signing web flow.

When the user reviews and signs the agreement in the signing web flow there are different possible outcomes.

Field descriptions

Field Description
type
String
Required
Possible Types:
WEBFLOW_SIGNING_SUCCEEDED: Upon successful agreement signing, the party will be redirected to href.
WEBFLOW_SIGNING_REJECTED: Upon agreement rejection, the party will be redirected to href.
WEBFLOW_SIGNING_FAILED: Upon agreement signing being rejected (due to issues with their certificate for instance), the party will be redirected to href.
href
String
Required
URL of the web page/REST endpoint where the party will be redirected. href is always works in tandem with type.
{
  "links": [
    {
        "type": "WEBFLOW_SIGNING",
        "href": ""
    }
  ]
}

A party can use it's webflow link to review the agreement and then sign or reject the agreement.

On Agreement creation, each party receives a mail with it's own unique link for the webflow.
When integrating with the Egreement Pro API, it is also possible to redirect the parties to the web flow directly by fetching the unique link for the party from the API.

Field descriptions

Field Description
type
String
Possible Types:
WEBFLOW_SIGNING
href
String
Unique Webflow Link for the Party.

Sign Request Schema

{
  "firstName": "",
  "lastName": "",
  "country": "",
  "signedOn": "20191001T094006Z",
  "personNumber": "",
  "email": "",
  "mobile": ""
}

Field descriptions

Field Type Description
firstName
String
Required
First name of the person signing the agreement
lastName
String
Last name of the person signing the agreement
country
String
Country code for the country of origin of the person signing the agreement
signedOn
String
Time when the agreement was signed
personNumber
String
Personal identity number of the person signing the agreement. Format is dependent on country
email
String
Email address of the person signing the agreement
mobile
String
Mobile phone number of the person signing the agreement

Signing Result Response Schema

{
  "signingResult": {
    "signingConfiguration": {}
  }
}

This schema contains details about the signing.

Field descriptions

Field Description
signingConfiguration
Signing Configuration
A copy of the signing configuration being used for signing the agreement.

Rejection Result Response Schema

{
  "rejectionResult": {
    "reason": ""
  }
}

This schema contains details about the rejection.

Field descriptions

Field Description
reason
String
A reason for the agreement rejection.

Agreement Update Request Schema

{
  "expireOn": "20191001T094006Z",
  "deleteOn": "20191002T094006Z"
}

Field descriptions

Field Type Description
expireOn
String
Time at which the agreement will expire and no parties will be allowed to sign.
Format: yyyyMMdd'T'HHmmss'Z'
Constraints: Time must always be in the future, after current expireOn and before deleteOn.
deleteOn
String
Time at which the agreement will be automatically deleted from the system.
Format: yyyyMMdd'T'HHmmss'Z'
Constraints: Time must always be in the future.
Caution: Agreement can not be retrieved once it is deleted. All the data related to the agreement such as attached files, audit events,configurations etc will also be deleted from the system permanently. If you do not want the agreement to be deleted automatically, do not set any value for this field.

Agreement Party Email Update Request Schema

{
  "address": "new_email@domain.com"
}

Field descriptions

Field Description
address
String
The new email address value for the Party

Agreement Party Notification Recipients Update Request Schema

[
  {
    "medium": "",
    "address": ""
  },
  {
    "medium": "",
    "address": ""
  }
]

This schema contains an array of recipients. It replaces all recipients of the notification.

Field descriptions

Field Description
medium
String
Required
Possible Types :
EMAIL, SMS
address
String
Required
Address to which the notification shall be sent.
Email address if medium is EMAIL.
Mobile phone number if medium is SMS.

Agreement Party Notification Recipients Update Response Schema

[
  {
    "medium": "",
    "address": ""
  },
  {
    "medium": "",
    "address": ""
  }
]

This schema contains an array of recipients.

Field descriptions

Field Description
medium
String
Possible Types :
EMAIL, SMS
address
String
Address to which the notification shall be sent.
Email address if medium is EMAIL.
Mobile phone number if medium is SMS.

Agreement Party Update Response Schema

{
  "id": "",
  "title": "",
  "state": "",
  "createdOn": "20171001T094006Z",
  "lastActivityOn": "20171001T094006Z",
  "postedOn": "20171001T094006Z",
  "closedOn": "20171001T094006Z",
  "rejectedOn": "20171001T094006Z",
  "revokedOn": "20171001T094006Z",
  "expiredOn": "20171001T094006Z",
  "expireOn": "20171001T094006Z",
  "deleteOn": "20191001T094006Z",
  "lastSignedOn": "20191001T094006Z",
  "importedOn": "20191001T094006Z",
  "parties": [
    {
      "id": "",
      "type": "PRIVATE",
      "state": "",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "notifications": [
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ],
      "links": [
        {
          "type": "WEBFLOW_SIGNING",
          "href": ""
        }
      ]
    },
    {
      "id": "",
      "type": "COMPANY",
      "state": "",
      "name": "",
      "companyNumber": "",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "notifications": [
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ],
      "links": [
        {
          "type": "WEBFLOW_SIGNING",
          "href": ""
        }
      ]
    },
    {
      "id": "",
      "type": "MY_COMPANY",
      "state": "",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "notifications": [
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ],
      "links": [
        {
          "type": "WEBFLOW_SIGNING",
          "href": ""
        }
      ]
    }
  ],
  "sharedWith": ""
}

Field descriptions

Field Description
id
String
UUID of the agreement
title
String
Title of the agreement
state
String
State of agreement
createdOn
String
Time at which the agreement created
lastActivityOn
String
Time at which the last activity occurred on agreement
postedOn
String
Time at which the agreement was sent (posted) to the stakeholders
closedOn
String
Time at which the agreement was concluded (Signed by All)
rejectedOn
String
Time at which the agreement was rejected
revokedOn
String
Time at which the agreement was revoked
expiredOn
String
Time at which the agreement was expired (expired due to the tender timeout period exceeded)
expireOn
String
Time at which the agreement will expire and no parties will be allowed to sign.
Format: yyyyMMdd'T'HHmmss'Z'.
deleteOn
String
Time at which the agreement will be automatically deleted from the system.
Format: yyyyMMdd'T'HHmmss'Z'.
lastSignedOn
String
Time at which the agreement was last signed on
importedOn
String
Time at which the agreement was imported
parties
Array of Party
Parties added to be the signatories of the agreement.
sharedWith
String
Status of how the agreement is shared with the stakeholders.

Party Update Response Schema

{
  "parties": [
    {
      "id": "",
      "type": "PRIVATE",
      "state": "",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "notifications": [
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ],
      "links": [
        {
            "type": "WEBFLOW_SIGNING",
            "href": ""
        }
      ]
    },
    {
      "id": "",
      "type": "COMPANY",
      "state": "",
      "name": "",
      "companyNumber": "",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "notifications": [
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ],
      "links": [
        {
            "type": "WEBFLOW_SIGNING",
            "href": ""
        }
      ]
    },
    {
      "id": "",
      "type": "MY_COMPANY",
      "state": "",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "notifications": [
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "timeZone": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "SMS"
            }
          ]
        }
      ],
      "links": [
        {
            "type": "WEBFLOW_SIGNING",
            "href": ""
        }
      ]
    }
  ]
}

Field descriptions

Field Description
id
String
UUID of the party
type
String
Type of party.
Possible Types:
PRIVATE: a private person is a party.
COMPANY: an organization is a party.
MY_COMPANY: your company is a party.

When MY_COMPANY is used as party, you can not send name,companyNumber or country as part of the request. These details will be taken from the Account Configuration.
state
String
State of the party
firstName
String
First name of the person signing the agreement
lastName
String
Last name of the person signing the agreement
name
String
Name of the company will be present only if parties.type is COMPANY
email
String
Email address of the party.
mobile
String
Mobile phone number of the party.
country
String
Country of origin for the party, will be present if the field personnumberis used.
personNumber
String
Personal identity number of the person signing the agreement. Format is dependent on the field country.
companyNumber
String
Organizational identity number for the company.
Only applicable if parties.type of the party is COMPANY.
signingOrder
Integer
Configuration of the order in which the parties can sign the agreement and posted/created email notifications will be sent.
Order shall start from 1. If the value is not provided, it will be set to 1 and no signing order will be enforced.

Example: An agreement with 3 parties X, Y and Z having the order 1, 2, 3 respectively. When the agreement is created the email notification will only be sent to the party X (having order 1). When party X signs the agreement, the posted email notification will be sent to party Y (having order 2) and the flow continues until the last party signs the agreement.

One or more parties having the same signingOrder will result in a parallel scenario. In this case if 2 parties are having signingOrder 1, they both need to sign the agreement in order for the parties at signingOrder 2 to receive the notifications.
notifications
Array of Notification
Notifications configured at the party level.
links
Array of Link
Webflow Signing Url for the party

Limitations

Transactions

Currently the API does not limit the number of transactions. Egreement recommends avoiding periodically polling the API and instead using a combination of Webhooks for callbacks and user driven API requests. If your network infrastructure does not allow the incoming network traffic from Webhooks you might be forced to use polling instead. In that case Egreement recommends keeping the polling interval as long as possible for your needs. Please contact Egreement Support if you need polling intervals shorter than 60 seconds.

Error handling

Example of error response

{
  "errors": [
    {
      "id": "696e0fa0-04c1-11e8-a8f1-990f5e5f0294",
      "code": "0010",
      "title": "Ogiltigt attribut",
      "detail": "may not be empty",
      "source": {
        "pointer": "/parties/0/firstName"
      }
    }
  ]
}

The Agreement Pro API V1 follows the JSON-API standard for Error Responses.

All the errors will be in below mentioned format and error handling can be simplified by checking the presence of “errors”.

Error field descriptions

Field Type Description
id
String
A unique identifier for this particular occurrence of the problem.
code
String
An application-specific error code, expressed as a string value.
title
String
A short, human-readable summary of the problem.
detail
String
A human-readable explanation specific to this occurrence of the problem.
source
String
An object containing references to the source of the error, optionally including any of the following members:
pointer: a JSON Pointer RFC6901 to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].
parameter: a string indicating which URI query parameter caused the error.

Sometimes if the error is a generic one and not specific to any field source field will not be part of the response.

Error codes

Below is a list of possible error codes and corresponding description

Error code Generic description
0001 When attribute is not set
0002 When empty value is passed in attribute
0003 When incorrect value is passed in the attribute
0004 When invalid value is set in group
0005 When value is not valid Base64
0006 When email is not valid
0007 When attribute value doesn't satisfy a particular pattern
0008 When incorrect value is passed in the attribute
0009 When locale is not valid
0010 When empty value is passed in attribute
0011 When request doesn't match the desired parameters
0012 When attribute value can not exceed particular value
0013 When attribute value can not be less than a particular value
0014 When date is not in the future
0015 When attribute value is not valid
0016 When invalid date search is requested
0017 When invalid date search is requested
0018 When date is not present
0018 When dates are not present
0018 When from date is not present
0018 When to date is not present
0019 When date is not in mentioned format
0020 When attachment value is not valid Base64
0021 When attachment token value is not valid
0022 When attachment type is not valid
0023 When attachment values are not valid
0024 When signing configuration is incorrect
0025 When person number is incorrect
0026 When company number is incorrect
0027 When value or key of tag is invalid
0027 When tag key length is invalid
0027 When tag value length is invalid
0027 When tag value has leading or trailing spaces
0027 When tag key is invalid
0027 When tag value is invalid
0027 When max number of allowed tags is exceeded
0028 When attribute value is not a valid URL
0029 When person number is incorrect
0030 When more than one query filter is used
0031 When expression is invalid
0032 When signing values are incorrect
0033 When length exceed the mentioned length
0034 When notification medium is invalid
0035 When identification configuration is incorrect
0036 When size is not in defined range
0037 When party level webhook notification is present
0038 When too many webhook notifications of a particular notification type is used
0039 When trying to access a resource where access is not given
0040 When account is not authorized to use some of the features, eg. identification before review, the notification medium
0041 When notification recipient is not of same medium
0042 When sendOn value is invalid
0043 When expireOn value is invalid
0044 When operation is not allowed, see documentation for details
0045 When attribute value is not valid
0046 When SMS OTP is incorrect
0047 When party level notification type is invalid
0048 When identification provider is not allowed by system
0049 When signing order is incorrect
0050 Logo file is not having valid context
0051 Logo file is not having valid mime type
0052 Logo file size is not valid
0053 Logo file is not valid image
0054 Logo file image dimension is not valid
0055 When agreement is not in the required state to perform the operation
0056 When number of required signature count is more than number of signatories
0057 When same identifier are present in another signing configuration
0058 When expiry reminder date is not less than the expiry date
0059 When ID is not a version 1 UUID
0060 When color code is not in valid HEX format
0061 When 'actorType' is account and 'actorId' is not current user's account ID (access rights)
0062 When file name is not valid
0063 When time zone is not valid
0064 When CONTAINER configuration is not valid
0065 When language configuration is not valid
0066 When attribute has leading or trailing whitespace(s)
0067 When involved objects are not fulfilling the required condition, see documentation and check objects
0070 When account has configured identification before review feature as mandatory and is missing in request
4301 When JSON is incorrect
4302 When invitation is not marked as accepted
4303 When user is already identified
4304 When unrecognized property is supplied
4305 When invalid JSON 'type'
4306 When invalid 'type' identifier
4401 When JWT is not valid
4401 When user is not authenticated
4401 When auth token is invalid
4403 When unauthorized resource is requested
4404 When requested resource can't be found
4405 When HTTP method is not allowed
4412 When If-Match header is missing or has an incorrect value
4901 When redirect URL is not valid
5001 When user already exists
5002 When user cannot be deleted from same user logged in context
5003 When group already exists
5004 When configuration type already exists
5005 When some of the configurations are duplicate
5006 When company number is incorrect
5007 When template already exists
5008 When different email used while accepting invitation
5009 When identity provider is not acceptable for invitation
9999 When some unexpected error occurs

Changelog

Date Change description
2024-02-07 Fetch Party Notification added
2024-02-07 Update Party Notification Recipients added
2024-02-07 Delete Party Notification added
2023-09-28 Qualified Electronic Signature added
2023-08-28 Notification locales enhanced with newly supported locales
2023-06-12 Webhook retry clarifications added
2022-10-18 Notify Agreement Party added
2022-06-02 Danish localization support in Notifications added
2022-04-28 Danish EID added
2022-03-02 Update Agreement added
2020-12-16 Time zone support for Container and Notifications added
2020-11-23 Finnish EID added
2020-08-11 Error Codes updates
2020-01-09 Whitespace(s) clarification
2019-08-16 sendExpiryReminderOn is added in Agreement Configuration & Party Configuration
2019-06-04 Signature methods is added
2019-04-16 Agreement Configuration is added
2019-04-16 Party Configuration is added
2019-04-16 Identification Configuration is added
2019-02-07 Notification Types are added
2018-11-08 RejectionResult added in Party
2018-10-11 SigningResult added in Party
2018-10-11 Description added to AccessRights
2018-10-11 Delete agreement added
2018-10-11 Custom email and SMS templates added
Configuration of attachments in emails added
2018-07-17 Configure TBS added
Webhooks added
2018-06-22 API Signature method added
2018-05-31 Access rights updated
Draw signature method added
2018-05-10 Automatic delete added
Click signature method added
2018-04-27 Template support added
2018-03-22 Language support for notifications added
Callback links for webflow added
2018-02-30 Added List Agreement
2018-01-30 Initial version of Egreement Pro API