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

A rental agreement (PDF) is to be signed by a private person (Randy Rentee) prior to renting digging equipment.
The agreement must be signed before the 1st of February 2022. Otherwise, it must be automatically expired.
The private person must sign the agreement using Swedish BankID.
The agreement will be created via your Rental Application (which you host).
The agreement must be accessible by multiple users who are active on the same Egreement Pro account.
When the agreement is concluded upon signing, Rental Application needs to know about this in order to continue the process (e.g. making a reservation in your Rental Application for the digging equipment).

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:

Create agreements.
Make sure other users on the same Egreement Pro account can access it.
Make sure your application gets to know that a party has signed it as quickly as possible.

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.

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

Return 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

EID - This method allow the parties to identify using Swedish BankID. When accessing the signing web flow, the user will be redirected to the integrated BankID services for identification. Once the identification process is completed the user will be redirected back to the agreement in the signing web flow. This identification method requires the parties personal identity number to be configured when the agreement is created.
SMS_OTP - This method allow the party to identify using SMS OTP. When accessing the signing web flow, the user will be required to enter a One Time Password, OTP, sent by SMS for identification. Once the identification process is completed the user will be redirected back to the agreement in the signing web flow. This identification method requires the parties mobile phone number to be configured when the agreement is created.

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

For this signature method to be used the party's Signing Configuration must be EID.
The party country flag must be set to SE.
By optionally configuring a personal identity number the system will only allow for signatures made with a certificate with that personal identity number.

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

For this signature method to be used the party's Signing Configuration must be EID.
The party country flag must be set to NO.

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

For this signature method to be used the party's Signing Configuration must be EID.
The party country flag must be set to FI.
It is optional to configure a personal identity number.

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

For this signature method to be used the party's Signing Configuration must be EID.
The party country flag must be set to DK.

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

For this signature method to be used the party's Signing Configuration must be QES.
The Signing Configuration provider must be configured with SWISSCOM.
The Signing Configuration identifier must be configured with the party's mobile phone number being bound to their electronic identity.

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

For this signature method to be used the party's Signing Configuration must be SMS_OTP.
The Signing Configuration identifier must be configured with the party's mobile phone number.

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

For this signature method to be used party's Signing Configuration must be DRAW.
Attachment type must be BASE64 and data must contain editable PDF content.
Attachment fields section can contain information about the fields where the signature is to be embedded.

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

For this signature method to be used the party's Signing Configuration must be CLICK.

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

It is only possible to use this signature method for parties of the type MY_COMPANY.
For this signature method to be used the party's Signing Configuration must be API.
The signature is made by calling the API Sign Agreement.

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:

party (on party level) - information that the parties would benefit from
info (on agreement level) - information that a non-party would benefit from - typically the creator of the agreement who might not necessarily be an agreement party

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

You can only download an agreement if it is concluded.

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

You can only revoke an agreement as long as it is not concluded.
You must have "update" rights for the agreement.

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

You can only sign an agreement as long as it is not concluded
The party signing the agreement must be the owner of the agreement, i.e. the API consumer can only sign the agreement on behalf of party having type as MY_COMPANY.

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

You can only update an agreement when it's in the READY_TO_SIGN, SIGNED or EXPIRED state.

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

The agreement state must be READY_TO_SIGN or SIGNED.
The party state must be READY_TO_SIGN or WAITING_TO_SIGN.
The email address in the request body must be different from the existing address.

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

The agreement state must be READY_TO_SIGN or SIGNED.
The party state must be READY_TO_SIGN.

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

The agreement state must be READY_TO_SIGN or SIGNED.
The party state must be READY_TO_SIGN.
The notification type must be READY_TO_SIGN.

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": ""
    },
    {
      "type": "REVIEW_DETAILS",
      "enabled": false,
      "visible": true
    },
    {
      "type": "WATERMARK",
      "x": 1.0,
      "y": 1.0,
      "rotation": 90.0
    },
    {
      "type": "OWNER_DETAILS",
      "companyName": "",
      "companyShortName": ""
    },
    {
      "type": "PDF_SEALING",
      "enabled": false
    }
  ]
}

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. `REVIEW_DETAILS` : This type overrides the system default configuration for the agreement review page. `WATERMARK` : This type overrides the system default configuration for the watermark inside the agreement PDF container. `OWNER_DETAILS` : This type overrides the system default configuration for the sender for Email & SMS. `PDF_SEALING` : This type overrides the system default configuration for the sealing details and account level configuration.
`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.
`enabled` Boolean	Only available if the type is `REVIEW_DETAILS` or `PDF_SEALING`. `REVIEW_DETAILS` Whether to allow toggle agreement details section. `PDF_SEALING` Whether to seal agreement PDF after it is signed by all parties.
`visible` Boolean	Only available if the type is `REVIEW_DETAILS`. Whether to show or hide agreement details section.
`x` Float	Only available if the type is `WATERMARK`. `x` co-ordinate or horizontal position for the watermark.
`y` Float	Only available if the type is `WATERMARK`. `y` co-ordinate or vertical position for the watermark.
`rotation` Float	Only available if the type is `WATERMARK`. Rotation in degree for the watermark to show it horizontally or vertically.
`companyName` String	Only available if the type is `OWNER_DETAILS`. Replace default sender for Email notification.
`companyShortName` String	Only available if the type is `OWNER_DETAILS`. Replace default sender for SMS notification. Constraints: Length must be max 11 characters.

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": 0,
      "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` Long	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 Required: Only if `type` of the party is `PRIVATE`
`lastName` String	Last name of the person signing the agreement Required: Only if `type` of the party is `PRIVATE`
`name` String	Name of the company. Required: Only if `type` of the party 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 `personNumber` is 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 `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 `type` of the party 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 `personNumber` is 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 `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 `type` is `EID`. Otherwise N/A.
`provider` String	Signature method provider. Required if the field `type` is `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 `country` is `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 `type` is `EID`. Otherwise N/A.
`provider` String	Signature method provider. Will be present if the field `type` is `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` Boolean	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` Boolean	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` Boolean	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` Boolean	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

Return Link Schema

{
  "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.

The user might review and sign the agreement.
There might be a failure when the user tries to sign the agreement.
The user might reject the agreement.

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

Webflow Link Schema

{
  "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 `personnumber`is 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

Introduction

Getting Started

Implementing the Egreement Pro API

The use case

Creating the agreement

URL

Header

Quickly knowing when an agreement has been signed

Authentication

Environments

Test environments

Production environment

Terminology

Account

Agreement

Agreement states

Event

User

Group

Party

Party states

Shared with

Agreement creator

Notification

Tags

Tag limitations

Signing methods

Conventions

Attachments encoding

Country codes

Data encoding

Whitespaces

Date and time

Email addresses

Object identifiers

Personal identity numbers

Phone numbers

The signing web flow

Return links

Success URL

Failure URL

Reject URL

Identification before review

Identification Methods

Signature Methods

EID signatures

Swedish BankID

How to Use

Norwegian BankID

How to Use

Finnish EID

How to Use

Danish MitID

How to Use

Qualified Electronic Signature

How to Use

SMS OTP signature

How to Use

Draw signature

How to Use

Click signature

How to Use

API signature

How to Use

Notifications

Notification types

Notification templates

Localization

Time zones

Custom templates

Email notifications

SMS notifications

Webhooks

Agreement Pro API V1

Create Agreement

Description

URL

Header

Parameters

Response