NAV Navbar
json

Egreement Pro API documentation

Introduction

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

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

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

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

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

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

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

Party

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

Party States

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

Shared With

Status of how the agreement is shared with the stakeholders.

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

Agreement creator

The agreement creator is the User who created the Agreement.

Notification

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

Tags

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

Tag limitations

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

Signing methods

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

Please refer to more detailed information in the section Signature methods

Conventions

Attachments encoding

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

Country codes

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

Data Encoding

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

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
Norway Standard DDMMYYXXXXX
Norway D-nummer (D+4)DMMYYXXXXX
Norway H-nummer DD(M+4)MYYXXXXX
Norway FH-nummer (8/9)XXXXXXXXXX

Phone numbers

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

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

Country code (max 3 digits)

Subscriber number (max 12 digits)

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

Finding International country calling codes

The signing web flow

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

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

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

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

For more information check: Webflow Links

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

Success URL

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

Failure URL

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

Reject URL

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

Identification before review

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

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

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

Identification Methods

Signature methods

EID signatures

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

Swedish BankID

Example of signing configuration for Swedish BankID

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

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

Using Swedish BankID will result in an advanced electronic signature.

How to Use

Norwegian BankID

Example of signing configuration for Norwegian BankID

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

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

SMS OTP signature

Example of signing configuration for SMS OTP signature

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

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

How to Use

Draw signature

Example of signing configuration for draw signature

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

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

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

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

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

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

How to Use

Click signature

Example of signing configuration for click signature

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

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

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

How to Use

API signature

Example of signing configuration for API signature

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

Example of creating an API signature with API Sign agreement

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

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

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

How to Use

Notifications

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

Notification Types

States Description
READY_TO_SIGN The agreement has been made available to all stakeholders and is waiting for the parties to sign it.
SIGNED One or more parties have signed the agreement and are waiting for others to sign.
SIGNED_BY_ALL The agreement has been signed by all parties.
REJECTED The agreement has been rejected by one of the parties and can no longer be signed.
REVOKED The agreement is revoked by the creator and can no longer be signed.
EXPIRED The agreement is expired since it exceeded the configured expiry time period and can no longer be signed.
EXPIRED_REMINDER The agreement is about to expiry since it exceeded the configured expireOn time period.
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.

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

Language/Country Locale
English (United states) en_US
Swedish (Sweden) sv_SE
Norwegian bokmål (Norway) nb_NO

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.

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

By default the system sends notifications to parties and the creator by mail. The following mail notifications are sent by default:

Event Parties Creator
READY_TO_SIGN yes yes
SIGNED yes yes
SIGNED_BY_ALL yes yes
REJECTED yes yes
REVOKED yes yes
EXPIRED yes yes
VIEWED no no

SMS notifications

Notifications can be sent by SMS and has to be configured manually.

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",
      "placeholders": {},
      "recipients": [
        {
          "address": "https://app.mydomain.com/webhook",
          "medium": "WEBHOOK"
        }
      ]
    }
  ],
  "accessRights": []
}

In the same way that email 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, and JSON for webhooks) are different, so when you want to create an email notification and webhook notification, you need to use two notification blocks instead of having two 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.domain.com/succeed"
    },
    {
      "type": "WEBFLOW_SIGNING_REJECTED",
      "href": "https://www.domain.com/rejected"
    },
    {
      "type": "WEBFLOW_SIGNING_FAILED",
      "href": "https://www.domain.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

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}
Content-Type application/json

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

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}
Content-Type application/json

Parameters

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

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

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

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

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

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

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

Response

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

Download agreement

Description

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

URL

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

Constraints

Parameters

Parameter In Description
id path The agreement UUID

Response

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

Delete agreement

Description

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

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

URL

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

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}
Content-Type application/json

Constraints

Parameters

Parameter In Description
id path The agreement UUID

Response

Status Meaning Body Description
200 Success Agreement default JSON object Agreement revoked successfully
400 Failure Error object Any unexpected error
403 Failure Error object The user is not authorized to revoke the agreement
404 Failure Error object The agreement is not found

Sign agreement

Example JSON

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

Description

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

URL

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

Constraints

Parameters

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

Response

Status Meaning Body Description
200 Success Agreement default JSON object Agreement signed successfully
400 Failure Error object Any unexpected error
403 Failure Error object The user is not authorized to sign the agreement
404 Failure Error object The agreement is not found

JSON Schemas

Agreement Request Schema

{
  "title": "",
  "expireOn": "20191001T094006Z",
  "deleteOn": "20191002T094006Z",
  "configurations": [
    {
      "type": "DEFAULT",
      "locale": ""
    },
    {
      "type": "NOTIFICATION",
      "locale": "",
      "sendExpiryReminderOn" : "20191001T094006Z"
    },
    {
      "type": "CONTAINER",
      "locale": ""
    }
  ],
  "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": "",
          "sendExpiryReminderOn" : "20191001T094006Z"
        }
      ],
      "signingConfigurations": [
        {
          "type": "",
          "country": "",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      ],
      "identificationConfigurations": [
        {
          "type": "",
          "country": "",
          "identifier": ""
        }
      ],
      "notifications": [
        {
          "type": "",
          "templateId": "",
          "locale": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        }
      ]
    },
    {
      "type": "COMPANY",
      "name": "",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "companyNumber": "",
      "country": "",
      "signingOrder": 1,
      "configurations": [
        {
          "type": "NOTIFICATION",
          "locale": "",
          "sendExpiryReminderOn" : "20191001T094006Z"
        }
      ],
      "signingConfigurations": [
        {
          "type": "EID",
          "country": "SE",
          "identifier": ""
        }
      ],
      "identificationConfigurations": [
        {
          "type": "EID",
          "country": "SE",
          "identifier": ""
        }
      ],
      "notifications": [
        {
          "type": "",
          "templateId": "",
          "locale": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "type": "",
          "templateId": "",
          "locale": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "WEBHOOK"
            }
          ]
        }
      ]
    },
    {
      "type": "MY_COMPANY",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "configurations": [
        {
          "type": "NOTIFICATION",
          "locale": "",
          "sendExpiryReminderOn" : "20191001T094006Z"
        }
      ],
      "signingConfigurations": [
        {
          "type": "EID",
          "country": "SE",
          "identifier": ""
        }
      ],
      "identificationConfigurations": [
        {
          "type": "EID",
          "country": "SE",
          "identifier": ""
        }
      ],
      "notifications": [
        {
          "type": "",
          "templateId": "",
          "locale": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        }
      ]
    }
  ],
  "notifications": [
    {
      "type": "",
      "templateId": "",
      "locale": "",
      "placeholders": {},
      "attachPdf": true,
      "recipients": [
        {
          "address": "",
          "medium": "EMAIL"
        }
      ]
    }
  ],
  "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. If no value is specified, the agreement will be automatically rejected after 60 days. Maximum: 99, minimum: 0.
Format: yyyyMMdd'T'HHmmss'Z'
Constraints: Time must always be in the future.
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 AccessRight
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": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        }
      ],
      "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": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "WEBHOOK"
            }
          ]
        }
      ],
      "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": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        }
      ],
      "links": [
        {
            "type": "WEBFLOW_SIGNING",
            "href": ""
        }
      ],
      "signingResult": {
        "signingConfiguration": {
          "id": "",
          "type": "EID",
          "country": "SE",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      },
      "rejectionResult": {
        "reason": ""
      }
    }
  ],
  "notifications": [
    {
      "id": "",
      "type": "",
      "templateId": "",
      "locale": "",
      "placeholders": {},
      "attachPdf": true,
      "recipients": [
        {
          "address": "",
          "medium": "EMAIL"
        }
      ]
    }
  ],
  "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 revokedOn
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. If no value is specified, the agreement will be automatically rejected after 60 days. Maximum: 99, minimum: 0.
Format: yyyyMMdd'T'HHmmss'Z'
Constraints: Time must always be in the future.
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.
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. 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
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.
sharedWith
String
Status of how the agreement is shared with the stakeholders.
links
Array of Link
Configuration of return links
accessRights
Object
AccessRight
tags
Object
Tags can be used to add metadata to the agreement.

Agreement Configurations Request Schema

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

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

Field descriptions

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

Attachment Request Schema

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

Field descriptions

Field Description
name
String
Required
The attachment filename.
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
Applicable only if attachment.type is BASE64
Fields contain the information about editable fields and the values that should be merged with the given template. It can be used when you have a common business template as a pdf(editable) 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 should be embedded into the given template.

Attachment Response Schema

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

Field descriptions

Field Description
id
String
UUID of attachment
name
String
The attachment filename.
title The attachment title.
mimeType
String
Possible values:
BASE64 Accepting the file content in the BASE64 format
TOKEN If the file is already uploaded to the account.
fileSize
String
Size of attached file
lastModifiedOn
String
Last Modified Time of the uploaded File
fields
Array of Objects
Applicable only if attachment.type is BASE64
fields contain the information about editable fields and the values that should be merged with the given template. It can be used when you have a common business template as a pdf(editable) 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 should be embedded into the given template.

Attachment Fields 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 which should be merged in corresponding pdf field.
Special case: if party draw-signature (Party's signing configuration type should be DRAW Signing Configuration ) needs to be merged in pdf on specific field then its value should follow a syntax : {{@agr.parties[0].signature}}, 0 is index of the party (starting from 0) for which signature needs to be merge, if index exceeds total number of parties it will return an error.

Party Request Schema

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

Field descriptions

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

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

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

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

Party Response Schema

{
  "parties": [
    {
      "id": "",
      "type": "PRIVATE",
      "state": "",
      "firstName": "",
      "lastName": "",
      "email": "",
      "mobile": "",
      "personNumber": "",
      "country": "",
      "signingOrder": 1,
      "signingConfigurations": [
        {
          "id": "",
          "type": "EID",
          "country": "SE",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      ],
      "identificationConfigurations": [
         {
           "id": "",
           "type": "EID",
           "country": "SE",
           "identifier": ""
         }
       ],
      "notifications": [
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        }
      ],
      "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": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        },
        {
          "id": "",
          "type": "",
          "templateId": "",
          "locale": "",
          "placeholders": {},
          "recipients": [
            {
              "address": "",
              "medium": "WEBHOOK"
            }
          ]
        }
      ],
      "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": "",
          "placeholders": {},
          "attachPdf": true,
          "recipients": [
            {
              "address": "",
              "medium": "EMAIL"
            }
          ]
        }
      ],
      "links": [
        {
            "type": "WEBFLOW_SIGNING",
            "href": ""
        }
      ],
      "signingResult": {
        "signingConfiguration": {
          "id": "",
          "type": "EID",
          "country": "SE",
          "identifier": "",
          "tbs": {
            "sender": "",
            "description": ""
          }
        }
      },
      "rejectionResult": {
        "reason": ""
      }
    }
  ]
}

Field descriptions

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

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

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

One or more parties having the same signingOrder will result in a parallel scenario. In this case if 2 parties are having signingOrder 1, they both need to sign the agreement in order for the parties at signingOrder 2 to receive the notifications.
signingConfigurations
Array of Signing Configuration
Configuration of how the party shall sign the agreement.
identificationConfigurations
Array of Identification Configuration
Configuration of how the party shall identify themself for reviewing the agreement.
signingResult
SigningResult
Response only
Signing result for the party. Only present for parties that have signed the agreement.
rejectionResult
RejectionResult
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. 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.
links
Array of Link
Webflow Signing Url for the party

Party Configurations Request Schema

{
  "configurations": [
    {
      "type": "NOTIFICATION",
      "locale": "",
      "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.
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.

SigningConfiguration Request Schema

{
  "signingConfigurations": [
    {
      "type": "",
      "country": "",
      "identifier": "",
      "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,SMS_OTP,CLICK,DRAW,API
country
String
Country of origin for the party.
Required if the field typeis EID. Otherwise N/A.
identifier
String
If type is EID or SMS_OTP, this field specifies the Personal identity number or mobile phone number of the person signing the agreement.
Required if the field typeis 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 SMS_OTP
The identifier shall be a valid 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.

SigningConfiguration Response Schema

{
  "signingConfigurations": [
    {
      "id": "",
      "type": "",
      "country": "",
      "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,SMS_OTP,CLICK,DRAW,API
country
String
Country of origin for the party, will be present if the field typeis EID. Otherwise N/A.
identifier
String
If type is EID or SMS_OTP, this field specifies the Personal identity number or mobile phone number of the person signing the agreement.
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.

IdentificationConfigurations 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 should contain the Personal identity number
If type is SMS_OTP, this field should contain the mobile phone number

IdentificationConfigurations 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 will 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": "",
      "placeholders": {},
      "attachPdf": true,
      "recipients": [
        {
          "address": "",
          "medium": "EMAIL"
        }
      ]
    }
  ]
}

Field descriptions

Field Description
type
String
Required
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).
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.
placeholders
String
Key-value pair that is used to fill the template placeholders. It is mandatory when you use any placeholders (i.e., namespace) in the template. All standard email templates have support for the message placeholder which can be used to send a custom message to the party. Placeholder values that are not provided will be rendered blank.
Example: If you configured the template as,
"Hi {{user}}, Agreement has been rejected by {{party}}"
then, you shall send placeholders as, placeholders: {"user": "John Smith", "party": "Bob Adams"}
Output will be
"Hi John Smith, Agreement has been rejected by Bob Adams"
attachPdf
String
Applicable only if type is SIGNED_BY_ALL
If set to true, the final pdf will be attached.
If set to false, the pdf will not be attached.
If it is not set or set to null, the request will check the account level configurations.
If enabled, then the final pdf will be attached.
If disabled, then the final pdf will not be attached.
If not configured, then the final pdf will not be attached.
recipients
Array of Recipient
Configuration of to whom the notification will be sent.

Notification Response Schema

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

Field descriptions

Field Description
id
String
UUID of the notification
type
String
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).
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.
placeholders
String
Key-value pair that is used to fill the template placeholders. It is mandatory when you use any placeholders (i.e., namespace) in the template. All standard email templates have support for the message placeholder which can be used to send a custom message to the party. Placeholder values that are not provided will be rendered blank.
Example: If you configured the template as,
"Hi {{user}}, Agreement has been rejected by {{party}}"
then, you shall send placeholders as, placeholders: {"user": "John Smith", "party": "Bob Adams"}
Output will be
"Hi John Smith, Agreement has been rejected by Bob Adams"
attachPdf
String
Applicable only if type is SIGNED_BY_ALL
If set to true, the final pdf will be attached.
If set to false, the pdf will not be attached.
If it is not set or set to null, the request will check the account level configurations.
If enabled, then the final pdf will be attached.
If disabled, then the final pdf will not be attached.
If not configured, then the final pdf will not be attached.
sendOn
String
Only available if notification type is EXPIRY_REMINDER and if sendExpiryReminderOn is configured for Agreement Configuration or Party Configuration .
Time at which the notification will be sent to recipients about agreement expiry.
recipients
Array of Recipient
Configuration of to whom the notification will be sent.

Recipient Schema

{
  "recipients": [
    {
      "medium": "EMAIL",
      "address": "support@egreement.com"
    },
    {
      "medium": "SMS",
      "address": "+46768588851"
    }
  ]
}

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.

Accessright 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

Accessright 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 will be granted to the entity type user.
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).
actorId
String
Id of the entity configured by actorType.
actorName
String
Name of the actor
action
String
Rights granted to the given actorId.
Possible Types:
read: actor will be able to read the created agreement (get/list)
update: actor will be able to update/add parties/notifications/attachments/accessRights of the granted agreement
delete: actor will be able to delete agreement or parties/notifications/attachments/accessRights of the granted agreement
{
  "links": [
    {
      "type": "WEBFLOW_SIGNING_SUCCEEDED",
      "href": ""
    },
    {
      "type": "WEBFLOW_SIGNING_REJECTED",
      "href": ""
    },
    {
      "type": "WEBFLOW_SIGNING_FAILED",
      "href": ""
    }
  ]
}

Configuration of return URLs for the signing web flow.

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

Field descriptions

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

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

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

Field descriptions

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

Sign Request Schema

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

Field descriptions

Field Type Description
firstName
String
Required
First name of the person signing the agreement
lastName
String
Last name of the person signing the agreement
country
String
Countrycode 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

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

RejectionResult Response Schema

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

This schema contains details about the rejection.

Field descriptions

Field Description
reason
String
A reason for the agreement rejection.

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 incorrect value is passed in the attribute
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 attribute has leading or trailing whitespaces
0018 When todate 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 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 the identification before review feature
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
0045 When attribute value is not valid
4301 When JSON is incorrect
4302 When invitation is not marked as accepted
4303 When user is already identified
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
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
5004 When identity provider is not acceptable to invitation
5005 When some of the configurations are duplicate
5006 When company number is incorrect
5007 When template already exists
9999 When some unexpected error occurs

Changelog

Date Change description
2019-07-XX 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