v2.0

Assently API Documentation

Send documents for e-signing with Assently API.

Deprecated content warning.
This documentation is not updated. Please see the current API documentation instead. The deprecated APIv2 docs are found at https://developer.assently.com/v2.0/reference .

Basics

The system consists of a few concepts that you should know about before using the API.

Case

A case is a binder that contains all information about one signing process. The most notable parts are: the Document(s) that should be signed and the list of signing Parties. A Template is a Case that can be used as a starting point for new cases.

Case Statuses

A case is always in one of the following statuses.

Status Description
Draft The case is created and is modifiable.
Sent The case has been sent for signing. The case cannot be modified.
Finished The case is PAdES sealed and downloadable.
Signed The case is in an intermediate state, where it is signed by all parties. The signed document has been created but not yet PAdES sealed. The signed document cannot be downloaded.
Expired The case has not been signed by the parties before the expiry time.
Rejected The case has been rejected by a signing party.
Pending The case has been issued via Web Automation and has not yet been signed by any party.

Document

One or more documents in a Case that you want signed.

Party

A party is a signing participant in a Case. Parties are not Users.

Allowed Signature Types

Signature types that can be used to sign the case.

Signature Type Description
ElectronicID Makes use of Bank ID providers for singing.
Touch Sign with a finger or pen on any touch screen device.
Sms Sign via a unique code sent to a mobile phone by sms.
QuickIntent A click signature (not available to all customers).

User Profile

All users have an individual user account, a Profile. A user can be associated with one or more accounts, as an Agent. A user can enter multiple e-mail addresses and connect them to accounts the user has access to.

Agent

An agent is the combination of a User and Account, granting the user access to operate as an Agent of that account.

Account

All Cases belong to an Account. Accounts have multiple Agents with different roles, which designate how a User may operate on the Account.

Account Role

The connection between a user and an account is combined with an Account Role that describes what the user is allowed to do with the account. Administrator can customize roles and permission if needed.

IsolatedAgent

  • Can create, edit, send and view cases
  • Cannot see or work with cases handled by other agents
  • Cannot view shared templates or create cases from them

LimitedAgent

  • Can create, edit, send and view cases
  • Cannot see, edit, send or view cases handled by other agents
  • Can view shared templates and create cases from them
  • Cannot edit shared template

Agent

  • Can view, edit and send any case that is not private
  • May create and edit shared templates

Manager

  • May view, edit and send any case, including private cases
  • May create and edit shared templates, including private cases

Administrator

  • Everything Agents and Managers are permitted
  • Change account billing info and settings
  • Add new agents to the account
  • Assign account roles

Communication

Communication with the Assently API is done over encrypted HTTP (HTTPS).

Data for input as well as output is in JSON format. This is because the API is intended for use both from front-end (JavaScript) and from back-end of other systems. All requests to the system should use the Content-Type "application/json; charset=utf-8" in your requests in order to communicate with the service.

Successful requests return a HTTP 200 status code.

New fields may be introduced to JSON data models over time and is not considered a breaking change. Integrators must ensure that their integrations ignore unknown fields by default.

What you need

An Account with API access. You can create a trial account to get started. If you want to use electronic ID (eID), make sure you choose the country you want to try below:

An Agent connected to the account. When you create an account, you will be added as an agent and you can add more agents in the settings.

An API Key and Secret for your Agent. You can generate those on your API Settings page.

For .NET users, we provide an API Client available via NuGet. Some of the examples may be useful even if you're developing on a different stack.

Authentication

Authentication with the Assently API is done with Basic Authentication. For Basic Authentication the structure looks like Basic username:password where username:password is base64 encoded as one string in this case it would be dXNlcm5hbWU6cGFzc3dvcmQ= so in completeness it would look like Basic dXNlcm5hbWU6cGFzc3dvcmQ=. The API Key is your username, and the API Secret your password. When authentication fails the client will get an HTTP 401 status code.

For acting on sub accounts using master account api keys the API Key structure for username have to be: masteraccountapikey\subaccountIDorsubaccountexternalID

Security

The majority of the API commands will require an authenticated user. Usernames and passwords remains secured over the wire by utilizing secure HTTP (HTTPS).

We treat API secrets as passwords. We cannot recover a secret if you lose it, you will have to generate new keys. Keep your API Secret safe, do not share it with unauthorized people, do not send in emails or over unencrypted wires.

Formats and Languages

All times are UTC, formatted as ISO-dates. For example: 2048-04-12T20:44:55

Notifications, signing instructions and agent UI are available in en-US, sv-SE, fi-FI, da, fr, de, no and es-ES. Notifications and signing instructions are available in some additional languages.

Environments

For testing your integration with the API please primarily use our testing environment.

Environment Base address
Test test.assently.com
Production app.assently.com

 

API Reference

Working with Cases

 

 

Create a case

POST /api/v2/createcase

Parameter Description Type Required
Id Set a GUID for the Case. You can use it to do additional requests quickly. Guid
Name Name of the case. If omitted will be set to empty string. String
NameAlias Alias for internal use. Shown in internal listings but not visible to parties. If omitted will be set to empty string. String
Parties Parties who should sign. See Party subtype for more information. List of PartyModels
Documents Documents to sign. See Document subtype for more information. List of DocumentModels
AllowedSignatureTypes Allowed signature types. Any combination of methods is allowed. See information on signature types in Basics section. List of strings (electronicid, touch, sms or quickintent)
AgentUsername Optionally specify an agent responsible for this case. When omitted, agent will be the authenticated user. Username is either your ExternalId or the Agents EmailAdress. String
AgentUsernameType AgentUsernameType determines the exact type of username. The types are Id and EmailAddress. UsernameType is required when Agent Id has a format similar to EmailAddress. String
Visibility Controls how cases are visible to other agents. By default, cases are visible to other agents ('group'). String (group, private or inherit)
Description A short description of the case, included in emails to parties. If omitted will be set to an empty string. String
Stakeholders List of email addresses for stakeholders. Stakeholders are notified once a case is signed. List of StakeholderModels
Metadata Metadata for this case. You can use metadata to find it later. Key/value dictionary
CancelUrl URL where user is sent when rejecting the case. String
ContinueUrl URL to continue to when signature has been completed. If omitted will be set to empty string. String
ContinueName Name of URL to continue to when signature has been completed. If omitted will be set to empty string. String
ContinueAuto Automatically continues to the ContinueUrl when the signature has been added.The case can have a status of Sent, Signed or Finished at the time of addition of signature. The case will have status Sent for multi-party cases where the last party has not yet signed. The case will have a status of either Signed or Finished when all parties have signed. Boolean
NotificationMethods Determines how to notify parties of signature requests and finished cases. Default when omitted is Email. List of strings (none, email or sms)
SendSignRequestEmailToParties Send signature request notifications to all parties when the case is created. If false, no messages of this type will be sent, regardless of NotificationMethods. Boolean
SendFinishEmailToCreator Send email notifications to creator when the case has been finished. Boolean
SendFinishEmailToParties Send email notifications to parties when the case has been finished. If false, no messages of this type will be sent, regardless of NotificationMethods. Boolean
SendRecallEmailToParties Send email notifications to parties when the case has been recalled. Boolean
RequestMessage Custom message used in the request to sign notification email. Overrides the system default message. String
RequestMessageSms Custom message used in the request to sign notification SMS. Overrides the system default message. String
FinishedMessage Custom message used in the notification email to parties when all parties have signed. Overrides the system default message. String
FinishedMessageSms Custom message used in the notification SMS to parties when all parties have signed. Overrides the system default messages. String
Culture Culture of case. If omitted, Agent's culture will be used. If no Agent is specified the authenticated user's culture will be used. String
SignInSequence Enforce a signing order. When false, parties are notified and can sign simultaneously. Boolean
AccessControl Define whether parties must provide additional credentials to access the case. String (default, sms or electronicid)
IdentityCheck Party is required to take a photo of ID before signing. Boolean
IsEditable Indicates that documents in this case (provided that they contain form fields) can be edited by agent or party prior to first signature. Boolean
MergeOnSend For cases where IsEditable is enabled, this setting will merge and make the document(s) read-only when the case is sent. Boolean
UseGroupNames Display the group name fields (known as Company Name in the UI) for each party. If true, group name for each party must be set before the case can be sent. Boolean
ExpireAfterDays Signing deadline, relative to when the case is sent. ExpireOn overrides this property. Default when omitted is 0. Number
ExpireOn Absolute signing deadline. If set, the case will expire on this date and time. Date must be specifed in UTC format YYYY-MM-DDThh:mm:ss DateTime
RemindAfterDays A reminder will be sent automatically to parties that haven't signed after the specified number of days. Default when omitted is 0. Number
EventCallback We'll send a server side callback when one of your subscribed events occur. CaseEventSubscription
Procedure Process defaults. String (default, form, payload or batch)
ApprovalRequired Approval from a manager is required to send the case. When set, cases must be sent using /api/v2/requestapproval. Boolean
ApprovalType Approval requirements that must be met. When set, cases must be sent using /api/v2/requestapproval. String (requireall or requireany)
Approvers Approvers are notified that the case must be reviewed and approved before being sent. List of StakeholderModels
DisablePartyQuestion Determines if parties can ask questions Boolean
SendRejectNotification Send email notifications to creator when the case has been rejected. Boolean
AllowEditApprover Allow agents to change approver details if this is true. When set, cases must be sent using /api/v2/requestapproval. Boolean

Example

POST /api/v2/createcase 
{
  "Id": "5a0e0866-252e-4b79-8a9b-466ea5cca5ce",
  "Name": "Employment agreement 4132",
  "Parties": [
    {
      "Id": "s4jf",
      "Name": "Michael J. Fox",
      "EmailAddress": "michael.j.fox@example.com",
      "AnyoneCanSign": false,
      "SignatureType": "Unknown",
      "ShowInternalInformation": false,
      "Assignable": false,
      "HasIdCheckDocument": false
    }
  ],
  "Documents": [
    {
      "Filename": "agreement.pdf",
      "Data": "",
      "ContentType": "application/pdf",
      "Size": 43242,
      "Type": "Original",
      "FormFields": {},
      "IsRequired": false
    }
  ],
  "AllowedSignatureTypes": [
    "ElectronicId"
  ],
  "Visibility": "Group",
  "Stakeholders": [],
  "Metadata": {},
  "ContinueAuto": false,
  "NotificationMethods": [],
  "SendSignRequestEmailToParties": true,
  "SendFinishEmailToCreator": true,
  "SendFinishEmailToParties": true,
  "SendRecallEmailToParties": true,
  "Culture": "en-US",
  "SignInSequence": false,
  "AccessControl": "Default",
  "IdentityCheck": false,
  "IsEditable": false,
  "MergeOnSend": false,
  "UseGroupNames": false,
  "ExpireAfterDays": 0,
  "RemindAfterDays": 0,
  "EventCallback": {
    "Events": [
      "Created",
      "Signed",
      "SignatureAdded",
      "Finished"
    ],
    "Url": ""
  },
  "Procedure": "Default",
  "ApprovalRequired": false,
  "Approvers": [],
  "DisablePartyQuestion": false,
  "SendRejectNotification": false,
  "AllowEditApprover": false
}
              
Response: 200 OK
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/createcase' \
--header 'Authorization: Basic APIKEY' \
--header 'ContentType: application/json' \
--data-raw '
{
  "Id": "5a0e0866-252e-4b79-8a9b-466ea5cca5ce",
  "Name": "Employment agreement 4132",
  "Parties": [
    {
      "Id": "s4jf",
      "Name": "Michael J. Fox",
      "EmailAddress": "michael.j.fox@example.com",
      "AnyoneCanSign": false,
      "SignatureType": "Unknown",
      "ShowInternalInformation": false,
      "Assignable": false,
      "HasIdCheckDocument": false
    }
  ],
  "Documents": [
    {
      "Filename": "agreement.pdf",
      "Data": "",
      "ContentType": "application/pdf",
      "Size": 43242,
      "Type": "Original",
      "FormFields": {},
      "IsRequired": false
    }
  ],
  "AllowedSignatureTypes": [
    "ElectronicId"
  ],
  "Visibility": "Group",
  "Stakeholders": [],
  "Metadata": {},
  "ContinueAuto": false,
  "NotificationMethods": [],
  "SendSignRequestEmailToParties": true,
  "SendFinishEmailToCreator": true,
  "SendFinishEmailToParties": true,
  "SendRecallEmailToParties": true,
  "Culture": "en-US",
  "SignInSequence": false,
  "AccessControl": "Default",
  "IdentityCheck": false,
  "IsEditable": false,
  "MergeOnSend": false,
  "UseGroupNames": false,
  "ExpireAfterDays": 0,
  "RemindAfterDays": 0,
  "EventCallback": {
    "Events": [
      "Created",
      "Signed",
      "SignatureAdded",
      "Finished"
    ],
    "Url": ""
  },
  "Procedure": "Default",
  "ApprovalRequired": false,
  "Approvers": [],
  "DisablePartyQuestion": false,
  "SendRejectNotification": false,
  "AllowEditApprover": false
}'
Expand Collapse

 

 

Create from template

POST /api/v2/createcasefromtemplate

Creates a case based on a template. Set agentUsername to either ID or email address to specify an issuing agent other than the one that makes the API call. If agentUsername is omitted, the calling agent will be used.

Parameter Description Type Required
templateId A UUID for the template Guid
newCaseId A UUID for the new case Guid
agentUsername Optionally specify an agent responsible for this case. When omitted, agent will be the authenticated user. Username is either the Agents ExternalId or EmailAdress. String
agentUsernameType AgentUsernameType determines the exact type of username. The types are Id and EmailAddress. UsernameType is required when Agent Id has a format similar to EmailAddress. String

Example

POST /api/v2/createcasefromtemplate 
              
Response: 200 OK
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/createcasefromtemplate' \
--header 'Authorization: Basic APIKEY' \
--form 'templateId=Guid' \
--form 'newCaseId=Guid' \
--form 'agentUsername=String' \
--form 'agentUsernameType=String'
Expand Collapse

 

 

Update a case

POST /api/v2/updatecase

Updates properties and collections of a case. It is recommended to use 'Get a case' request before making an update. Collections: missing items will be removed, others updated or added. Documents collection: Only filename and formfields can be changed. To modify size, hash or data, the document must be removed first and a new document (with a new id) must be added.

Parameter Description Type Required
Id Case Id. Guid
Name Name of the case. If omitted, will be set to an empty string. String
NameAlias Alternate name for internal use. Not visible to parties. If set it substitutes the Name property. When the case is created from a template, this property is always empty. If omitted, will be set to an empty string. String
AccountId Account Id of the case. The Account connected to the case cannot be updated. Number
MasterAccountId Master account Id of the case. The master account connected to the case cannot be updated. Number
Parties Parties who should sign. See Party subtype for more information. List of PartyModels
Documents List of documents to sign. See Document subtype for more information. List of DocumentModels
Visibility Controls how cases are visible to other agents. By default, cases are visible to other agents ('group'). String (group, private or inherit)
AllowedSignatureTypes Allowed signature types. Any combination of methods is allowed. See information on signature types in Basics section List of strings (electronicid, touch, sms or quickintent)
Description Description of the case, included in emails to parties. If omitted will be set to empty string. String
Stakeholders Stakeholders, notified once a case is signed. List of StakeholderModels
Metadata Metadata for this case. Metadata can be used when searching for cases. Key/value dictionary
CancelUrl URL where user is sent when rejecting the case. String
ContinueUrl URL to continue to when signature has been completed. If omitted will be set to empty string. String
ContinueName Name of URL to continue to when signature has been completed. If omitted will be set to empty string. String
ContinueAuto Automatically continues to the ContinueUrl when the signature has been added. The case can have a status of Sent, Signed or Finished at the time of addition of signature. The case will have status Sent for multi-party cases where the last party has not yet signed. The case will have a status of either Signed or Finished when all parties have signed. Boolean
NotificationMethods Determines how to notify parties of signature requests and finished cases. Default when omitted is Email. List of strings (none, email or sms)
SendSignRequestEmailToParties Send signature request notifications to all parties when the case is created. If false, no messages of this type will be sent, regardless of NotificationMethods. Boolean
SendFinishEmailToCreator Send email notifications to creator when the case has been finished. Boolean
SendFinishEmailToParties Send email notifications to parties when the case has been finished. If false, no messages of this type will be sent, regardless of NotificationMethods. Boolean
SendRecallEmailToParties Send email notifications to parties when the case has been recalled. Boolean
RequestMessage Custom message used the request to sign notification email. Overrides the system default message. String
RequestMessageSms Custom message used in the request to sign notification SMS. Overrides the system default message. String
FinishedMessage Custom message used in the notification email to parties when all parties have signed. Overrides the system default message. String
FinishedMessageSms Custom message used in the notification SMS to parties when all parties have signed. Overrides the system default messages. String
Culture Culture of case. Will be set to the authenticated user's culture if omitted. String
SignInSequence Enforce a signing order. When false, parties are notified and can sign simultaneously. Boolean
AccessControl Define whether parties must provide additional credentials to access the case. String (default, sms or electronicid)
IdentityCheck Party is required to take a photo of ID before signing. Boolean
IsEditable Indicates that documents in this case (provided that they contain form fields) can be edited by agent or party prior to first signature. Boolean
MergeOnSend For cases where IsEditable is enabled, this setting will merge and make the document(s) read-only when the case is sent. Boolean
UseGroupNames Display the group name fields (known as Company Name in the UI) for each party. If true, group name for each party must be set before the case can be sent. Boolean
ExpireAfterDays Signing deadline, relative to when the case is sent. ExpireOn overrides this property. Default when omitted is 0. Number
ExpireOn Absolute signing deadline. If set, the case will expire on this date and time. Date specified in UTC format YYYY-MM-DDThh:mm:ss. DateTime
RemindAfterDays A reminder will be sent automatically to parties that haven't signed after the specified number of days. Default when omitted is 0. Number
ApprovalRequired Approval from a manager is required to send the case. When set, cases must be sent using /api/v2/requestapproval. Boolean
ApprovalType Approval requirements that must be met. When set, cases must be sent using /api/v2/requestapproval. String (requireall or requireany)
Approvers Approvers are notified that the case must be reviewed and approved before being sent. List of StakeholderModels
EventCallback We'll send a server side callback when one of your subscribed events occur. CaseEventSubscription
DisablePartyQuestion Determines if parties can ask questions Boolean
SendRejectNotification Determines if email notifications are sent to creator when the case has been rejected. Boolean
TemporaryId An ephemeral ID that can be used for quick lookups, valid for 24 hours after the case is created. Number
AllowEditApprover Allow agents to change approver details if this is true. When set, cases must be sent using /api/v2/requestapproval. Boolean

Example

POST /api/v2/updatecase 
{
  "Id": "5a0e0866-252e-4b79-8a9b-466ea5cca5ce",
  "Status": 0,
  "Name": "Employment agreement 4132-X",
  "AccountId": 0,
  "Parties": [
    {
      "Id": "s4jf",
      "Name": "Michael Foxly",
      "EmailAddress": "michael.foxly@example.com",
      "AnyoneCanSign": false,
      "SignatureType": 0,
      "ShowInternalInformation": false,
      "Assignable": false,
      "HasIdCheckDocument": false
    }
  ],
  "Documents": [],
  "Visibility": "Group",
  "AllowedSignatureTypes": [],
  "Stakeholders": [],
  "Metadata": {},
  "ContinueAuto": false,
  "NotificationMethods": [],
  "SendSignRequestEmailToParties": false,
  "SendFinishEmailToCreator": false,
  "SendFinishEmailToParties": false,
  "SendRecallEmailToParties": false,
  "SignInSequence": false,
  "IdentityCheck": false,
  "IsEditable": false,
  "MergeOnSend": false,
  "ExpireAfterDays": 0,
  "RemindAfterDays": 0,
  "CreatedOn": "0001-01-01T00:00:00",
  "Approvers": [],
  "Procedure": "Default",
  "SendRejectNotification": false
}
              
Response: 200 OK
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/updatecase' \
--header 'Authorization: Basic APIKEY' \
--header 'ContentType: application/json' \
--data-raw '
{
  "Id": "5a0e0866-252e-4b79-8a9b-466ea5cca5ce",
  "Status": 0,
  "Name": "Employment agreement 4132-X",
  "AccountId": 0,
  "Parties": [
    {
      "Id": "s4jf",
      "Name": "Michael Foxly",
      "EmailAddress": "michael.foxly@example.com",
      "AnyoneCanSign": false,
      "SignatureType": 0,
      "ShowInternalInformation": false,
      "Assignable": false,
      "HasIdCheckDocument": false
    }
  ],
  "Documents": [],
  "Visibility": "Group",
  "AllowedSignatureTypes": [],
  "Stakeholders": [],
  "Metadata": {},
  "ContinueAuto": false,
  "NotificationMethods": [],
  "SendSignRequestEmailToParties": false,
  "SendFinishEmailToCreator": false,
  "SendFinishEmailToParties": false,
  "SendRecallEmailToParties": false,
  "SignInSequence": false,
  "IdentityCheck": false,
  "IsEditable": false,
  "MergeOnSend": false,
  "ExpireAfterDays": 0,
  "RemindAfterDays": 0,
  "CreatedOn": "0001-01-01T00:00:00",
  "Approvers": [],
  "Procedure": "Default",
  "SendRejectNotification": false
}'
Expand Collapse

 

 

Update case metadata

POST /api/v2/updatecasemetadata

Allows updating metadata regardless of the case status. Existing metadata will be replaced with new metadata. Metadata cannot be complex objects.

Parameter Description Type Required
Id Case Id. Guid
Metadata Case Metadata (key/value). Key/value dictionary

Example

POST /api/v2/updatecasemetadata 
{
  "id": "5a0e0866-252e-4b79-8a9b-466ea5cca5ce",
  "metadata": {
    "Country": "Sweden",
    "ExternalReferenceId": "3D2V1WF3C4"
  }
}
              
Response: 200 OK
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/updatecasemetadata' \
--header 'Authorization: Basic APIKEY' \
--header 'ContentType: application/json' \
--data-raw '
{
  "id": "5a0e0866-252e-4b79-8a9b-466ea5cca5ce",
  "metadata": {
    "Country": "Sweden",
    "ExternalReferenceId": "3D2V1WF3C4"
  }
}'
Expand Collapse

 

 

Send a case

POST /api/v2/sendcase

Changes the status of the case to Sent, making it available for signing. In order to send a case the parameters Parties, Documents and AllowedSignatureTypes must be specified on the case. If notifications are enabled, parties will be notified.

Parameter Description Type Required
id Guid

Example

POST /api/v2/sendcase 
              
Response: 200 OK
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/sendcase' \
--header 'Authorization: Basic APIKEY' \
--form 'id=Guid'
Expand Collapse

 

 

Send a reminder

POST /api/v2/remindcase

Sends reminders to all parties that have not yet signed. If signing order is enforced, only the next party in turn will be reminded.

Parameter Description Type Required
id Guid

Example

POST /api/v2/remindcase 
              
Response: 200 OK
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/remindcase' \
--header 'Authorization: Basic APIKEY' \
--form 'id=Guid'
Expand Collapse

 

 

Delete a case

POST /api/v2/deletecase

Case is deleted permanently. If the case is sent, it will be recalled prior to deletion.

Parameter Description Type Required
id Guid

Example

POST /api/v2/deletecase 
              
Response: 200 OK
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/deletecase' \
--header 'Authorization: Basic APIKEY' \
--form 'id=Guid'
Expand Collapse

 

 

Recall a case

POST /api/v2/recallcase

If the case is sent, it will be recalled. Finished cases cannot be recalled.

Parameter Description Type Required
id Guid

Example

POST /api/v2/recallcase 
              
Response: 200 OK
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/recallcase' \
--header 'Authorization: Basic APIKEY' \
--form 'id=Guid'
Expand Collapse

 

 

Get a case

GET /api/v2/getcase

Gets a case based on its id. GetCase supports an optional additional query parameter IncludeAllStatuses which when set to true will return all statuses. June 13, 2018 release of Assently E-sign app includes PAdES which introduces a new case status called Signed. (Ref: to Statuses documentation). For backward compatibility, the Signed status is returned as Sent by default. If IncludeAllStatuses is set to true, the Signed status will be returned as is. All Assently API clients released after September 13, 2018 will return the new Signed status. For backward compatibility, the PendingApproval status is returned as Draft by default. If includePendingApprovalStatus is set to true, the PendingApproval status will be returned as is.

Parameter Description Type Required
Id The UUID for the Case to get. Guid

Return type

 CaseModel as application/json

Example

GET /api/v2/getcase ?id=5a0e0866-252e-4b79-8a9b-466ea5cca5ce
              
Response: 200 OK <CaseModel> {
  "Id": "5a0e0866-252e-4b79-8a9b-466ea5cca5ce",
  "Status": "Sent",
  "Name": "Employment agreement 4132",
  "AccountId": 0,
  "Parties": [
    {
      "Name": "Michael J. Fox",
      "EmailAddress": "michael.j.fox@example.com",
      "AnyoneCanSign": false,
      "SignatureType": 0,
      "ShowInternalInformation": false,
      "Assignable": false,
      "NotificationStatus": {
        "Email": "Sent"
      },
      "HasIdCheckDocument": false,
      "Reviewed": false
    }
  ],
  "Documents": [
    {
      "Filename": "agreement.pdf",
      "ContentType": "application/pdf",
      "Size": 43242,
      "Hash": "",
      "Type": "Original",
      "FormFields": {},
      "IsRequired": false
    }
  ],
  "Visibility": "Group",
  "AllowedSignatureTypes": [
    "ElectronicId"
  ],
  "Stakeholders": [],
  "Metadata": {},
  "ContinueAuto": false,
  "NotificationMethods": [],
  "SendSignRequestEmailToParties": true,
  "SendFinishEmailToCreator": true,
  "SendFinishEmailToParties": true,
  "SendRecallEmailToParties": true,
  "Culture": "en-US",
  "SignInSequence": false,
  "IdentityCheck": false,
  "IsEditable": false,
  "MergeOnSend": false,
  "ExpireAfterDays": 0,
  "RemindAfterDays": 0,
  "CreatedOn": "2048-12-12T13:37:00",
  "Approvers": [],
  "Procedure": "Default",
  "SendRejectNotification": false
}
Expand Collapse
cURL
curl --location --request GET 'https://app.assently.com/api/v2/getcase?id=5a0e0866-252e-4b79-8a9b-466ea5cca5ce' \
--header 'Authorization: Basic APIKEY'
Expand Collapse

 

 

Get a case by temporary id

GET /api/v2/getcasebytemporaryid

Gets a case by its temporaryId. A temporary id is a 4+ digit number that is only valid for 24 hours.

Parameter Description Type Required
id Number

Return type

 CaseModel as application/json

Example

GET /api/v2/getcasebytemporaryid ?id=1234
              
Response: 200 OK <CaseModel> {
  "Id": "5a0e0866-252e-4b79-8a9b-466ea5cca5ce",
  "Status": "Sent",
  "Name": "Employment agreement 4132",
  "AccountId": 0,
  "Parties": [
    {
      "Name": "Michael J. Fox",
      "EmailAddress": "michael.j.fox@example.com",
      "AnyoneCanSign": false,
      "SignatureType": 0,
      "ShowInternalInformation": false,
      "Assignable": false,
      "NotificationStatus": {
        "Email": "Sent"
      },
      "HasIdCheckDocument": false,
      "Reviewed": false
    }
  ],
  "Documents": [
    {
      "Filename": "agreement.pdf",
      "Data": "",
      "ContentType": "application/pdf",
      "Size": 43242,
      "Type": "Original",
      "FormFields": {},
      "IsRequired": false
    }
  ],
  "Visibility": "Group",
  "AllowedSignatureTypes": [
    "ElectronicId"
  ],
  "Stakeholders": [],
  "Metadata": {},
  "ContinueAuto": false,
  "NotificationMethods": [],
  "SendSignRequestEmailToParties": true,
  "SendFinishEmailToCreator": true,
  "SendFinishEmailToParties": true,
  "SendRecallEmailToParties": true,
  "Culture": "en-US",
  "SignInSequence": false,
  "IdentityCheck": false,
  "IsEditable": false,
  "MergeOnSend": false,
  "ExpireAfterDays": 0,
  "RemindAfterDays": 0,
  "CreatedOn": "2048-12-12T13:37:00",
  "Approvers": [],
  "Procedure": "Default",
  "SendRejectNotification": false
}
Expand Collapse
cURL
curl --location --request GET 'https://app.assently.com/api/v2/getcasebytemporaryid?id=1234' \
--header 'Authorization: Basic APIKEY'
Expand Collapse

 

 

Find and list cases

GET /api/v2/findcases

Finds and Lists cases based upon the input parameters.

FindCases supports an optional additional query parameter IncludeAllStatuses which when set to true will return all statuses. June 28, 2018 release of Assently E-sign app includes PAdES which introduces a new case status called Signed. (Ref: to Statuses documentation). For backward compatibility, the Signed status is returned as Sent by default. If IncludeAllStatuses is set to true, the Signed status will be returned as is. All Assently API clients released after September 13, 2018 will return the new Signed status.

For backward compatibility, the PendingApproval status is returned as Draft by default. If includePendingApprovalStatus is set to true, the PendingApproval status will be returned as is.

This method supports strict/partial matching based on the field. Strict match means that the whole search text must exactly match value of the field. Partial match means that the search text must match 100% but can be a subset of the value of the field. Below is a list of fields that are searchable and the type of supported matching:

Following fields support strict matching:
AgentUsername (agent id or email address)
Status
Metadata (key)
Documents.FormData (key)

Following fields support partial matching:
Description
Name
NameAlias
Metadata (value)
Stakeholders.Name
Stakeholders.EmailAddress
Stakeholders.MobilePhone
Stakeholders.NationalID
Stakeholders.EidSerialNumber
Approvers.Name
Approvers.EmailAddress
Approvers.MobilePhone
Approvers.NationalID
Documents.Filename
Documents.FormData (value)
Parties.Name
Parties.CaseMobilePhone
Parties.EmailAddress
Parties.GroupName
Parties.SocialSecurityNumber
Parties.EidSerialNumber

When returned results are based on partial matching, non unique values or values that can be subset to other values will return multiple results. Special care should therefore be taken for situations where a specific result is expected based on an exact value.

Search relevancy can be improved by combining different parameters.

Parameter Description Type Required
FromDate Include cases created on or after this date. Date must be specifed in UTC format YYYY-MM-DDThh:mm:ss. Set to null to not filter on this parameter. DateTime
ToDate Include cases created on or before this date. Date must be specifed in UTC format YYYY-MM-DDThh:mm:ss. Set to null to not filter on this parameter. DateTime
Status Include cases with this case status. Set to null to not filter on this parameter. Status uses strict matching. String (pending, draft, sent, finished, expired, rejected, signed or pendingapproval)
Search Search cases that have the specified search text. String
AgentUsername Include cases belonging to this agent by EmailAddress or Id. If empty, cases from all agents are returned. This filter uses strict matching String
PartySocialSecurityNumber Include cases where a party has this social security number. Filter uses partial matching. String
PartyEidSerialNumber Include cases where a party has this serial number. Filter uses partial matching. String
PartyEmailAddress Include cases where a party has this email address. Filter uses partial matching. String
PartyMobilePhone Include cases where a party has this phone number. Filter uses partial matching. String
Metadata Include cases where the following metadata matches (key/value). Filter uses partial matching on values. Key/value dictionary
FormData Include cases where the following form fields matches (key/value). Filter uses partial matching on values. Key/value dictionary
Sort Sort by either Status, Name or Created. Example: 'Created DESC' to sort newest cases first. String
Skip For paging purposes, the number of cases to skip before Take. Default is 0. Should be a multiple of Take. The value of Skip and Take combined must not be higher than 10000 Number
Take Number of cases to return. Default is 20. Maximum cases that can be returned in one request is 100. Use in combination with Skip to get more cases in multiple requests. Number

Return type

List of CaseModels as application/json

Example

GET /api/v2/findcases 
              
Response: 200 OK CaseModels>
Expand Collapse
cURL
curl --location --request GET 'https://app.assently.com/api/v2/findcases' \
--header 'Authorization: Basic APIKEY' \
--form 'FromDate=DateTime' \
--form 'ToDate=DateTime' \
--form 'Status=String (pending, draft, sent, finished, expired, rejected, signed or pendingapproval)' \
--form 'Search=String' \
--form 'AgentUsername=String' \
--form 'PartySocialSecurityNumber=String' \
--form 'PartyEidSerialNumber=String' \
--form 'PartyEmailAddress=String' \
--form 'PartyMobilePhone=String' \
--form 'Metadata=Key/value dictionary' \
--form 'FormData=Key/value dictionary' \
--form 'Sort=String' \
--form 'Skip=Number' \
--form 'Take=Number'
Expand Collapse

 

 

Request approval to send

POST /api/v2/requestapproval

Used when a case is set to require approval before sent. Sends a request to approver stakeholders to approve and send the case. Approvals are requested in the name of the API user.

Parameter Description Type Required
id Guid

Example

POST /api/v2/requestapproval 
              
Response: 200 OK
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/requestapproval' \
--header 'Authorization: Basic APIKEY' \
--form 'id=Guid'
Expand Collapse

 

 

Mark that a party has signed a case

POST /api/v2/markassigned

Used when a party signs a physical document with a hand written signature. After receiving and validating the signature, an agent can mark the party as signed on the case in E-Sign.The agent is responsible for the validity, and archival, of the signature.

Parameter Description Type Required
CaseId Case reference ID. Guid
PartyId ID of the party in the case. String
PartyName Name of signing party. Optional unless name was empty String

Example

POST /api/v2/markassigned 
              
Response: 200 OK
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/markassigned' \
--header 'Authorization: Basic APIKEY' \
--form 'CaseId=Guid' \
--form 'PartyId=String' \
--form 'PartyName=String'
Expand Collapse

 

 

Mark that a party will not sign a case

POST /api/v2/markasnotsigned

Used when a party is not going to sign, but the case should still be finished. The party will still appear in the receipt, marked as not signed.

Parameter Description Type Required
caseId Guid
partyId String

Example

POST /api/v2/markasnotsigned 
              
Response: 200 OK
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/markasnotsigned' \
--header 'Authorization: Basic APIKEY' \
--form 'caseId=Guid' \
--form 'partyId=String'
Expand Collapse

 

 

Find and list templates

GET /api/v2/findtemplates

Parameter Description Type Required
FromDate Include templates created on or after this date. Specify date in UTC format YYYY-MM-DDThh:mm:ss. Set to null to not filter on this parameter. DateTime
ToDate Include templates created on or before this date. Specify date in UTC format YYYY-MM-DDThh:mm:ss. Set to null to not filter on this parameter. DateTime
AgentUsername Include templates belonging to this agent by EmailAddress or Id. If empty, templates for all agents are returned. String
Metadata Include templates where the following metadata matches (key/value). Key/value dictionary
FormData Include templates where the following form fields matches (key/value). Key/value dictionary
Sort Sort by either Status, Name or Created. Example: 'Created DESC' to sort newest templates first. String
Skip For paging purposes, the number of items to skip before Take. Default is 0. Should be a multiple of Take. Number
Take Number of items to return. Default is 20. Maximum cases that can be returned in one request is 100. Use in combination with Skip to get more cases in multiple requests. Number

Return type

List of CaseModels as application/json

Example

GET /api/v2/findtemplates 
              
Response: 200 OK CaseModels>
Expand Collapse
cURL
curl --location --request GET 'https://app.assently.com/api/v2/findtemplates' \
--header 'Authorization: Basic APIKEY' \
--form 'FromDate=DateTime' \
--form 'ToDate=DateTime' \
--form 'AgentUsername=String' \
--form 'Metadata=Key/value dictionary' \
--form 'FormData=Key/value dictionary' \
--form 'Sort=String' \
--form 'Skip=Number' \
--form 'Take=Number'
Expand Collapse

 

 

Retrieve a document

GET /api/v2/getdocumentdata

Returns the file data of the specified document

Parameter Description Type Required
caseId Guid
documentId String

Return type

Stream as application/octet-stream

Example

GET /api/v2/getdocumentdata 
              
Response: 200 OK
Expand Collapse
cURL
curl --location --request GET 'https://app.assently.com/api/v2/getdocumentdata' \
--header 'Authorization: Basic APIKEY' \
--form 'caseId=Guid' \
--form 'documentId=String'
Expand Collapse

Working with Agents

 

 

Create agent

POST /api/v2/createagent

This action creates the agent and the underlying user if it does not exist. The action is safe to repeat. If the agent already exists, nothing happens.

Parameter Description Type Required
Name John Smith, or similar String
EmailAddress Notification will be sent to this address. Used as login if Id is omitted. String
Role Determines which permissions the agent will have. Standard roles are IsolatedAgent, LimitedAgent, Agent, Manager, Administrator. String
Id Id of this agent. Unique within the account to which the agent belongs. You may provide an Id, or one will be generated for you. String
PhoneNumber Phone number. String
Culture Controls UI language for this agent. String
AllowedLoginTypes Allowed login types. Any combination of methods is allowed. For backwards compatibility, If the field is not specified or set to null, web and assentlysso will be set as allowed login types. List of strings (web, saml or assentlysso)

Example

POST /api/v2/createagent 
{
  "Name": "Test User",
  "EmailAddress": "test.user@example.com",
  "Role": "Agent",
  "Id": "cipe-237",
  "PhoneNumber": "+46XXXXXXXXX",
  "Culture": "en-US",
  "AllowedLoginTypes": [
    "Web"
  ]
}
              
Response: 200 OK
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/createagent' \
--header 'Authorization: Basic APIKEY' \
--header 'ContentType: application/json' \
--data-raw '
{
  "Name": "Test User",
  "EmailAddress": "test.user@example.com",
  "Role": "Agent",
  "Id": "cipe-237",
  "PhoneNumber": "+46XXXXXXXXX",
  "Culture": "en-US",
  "AllowedLoginTypes": [
    "Web"
  ]
}'
Expand Collapse

 

 

Get agent

GET /api/v2/getagent

This action will return the agent for the current account

Parameter Description Type Required
Username Username is either Agent Id or EmailAddress. String
UsernameType UsernameType determines the exact type of username. The types are Id and EmailAddress. UsernameType is required when Agent Id has a format similar to EmailAddress. String

Example

GET /api/v2/getagent ?username=john.smith%40example.com
              
Response: 200 OK {
  "Id": "cipe-237",
  "EmailAddress": "test.user@example.com",
  "Name": "Test User",
  "Role": "Agent",
  "PhoneNumber": "+46XXXXXXXXX",
  "Culture": "en-US",
  "AllowedLoginTypes": [
    "Web"
  ]
}
Expand Collapse
cURL
curl --location --request GET 'https://app.assently.com/api/v2/getagent?username=john.smith%40example.com' \
--header 'Authorization: Basic APIKEY'
Expand Collapse

 

 

Update agent or underlying user

POST /api/v2/updateagent

This action will update agent or the underlying user. Missing values will be removed. EmailAddress cannot be updated.

Parameter Description Type Required
Id User specified or automatically generated Id of this agent. Id is unique within the account to which the agent belongs. String
EmailAddress Email address of the underlying user. Notification will be sent to this email address. EmailAddress can also be used to identify the agent in the account. EmailAddress cannot be updated. String
Name Name of the underlying user for this agent. If the value is different from current value, it will be updated String
Role Role of the Agent. If the value is different from current value, it will be updated. Standard roles are IsolatedAgent, LimitedAgent, Agent, Manager, Administrator. String
PhoneNumber Phone number of the underlying user for this agent. If the value is difference from current value, it will be updated. Missing PhoneNumber will remove any previously set PhoneNumber. String
Culture UI language for this agent. If the value is different from current value, it will be updated. Missing Culture will remove any previously set Culture hence setting Culture to Default. String
AllowedLoginTypes Allowed login types. Any combination of methods is allowed. If the field is not specified or set to null, the AllowedLoginTypes will be left unchanged. List of strings (web, saml or assentlysso)

Example

POST /api/v2/updateagent 
{
  "Id": "cipe-237",
  "EmailAddress": "test.user@example.com",
  "Name": "Test User",
  "Role": "LimitedAgent",
  "Culture": "sv-SE",
  "AllowedLoginTypes": [
    "Saml"
  ]
}
              
Response: 200 OK
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/updateagent' \
--header 'Authorization: Basic APIKEY' \
--header 'ContentType: application/json' \
--data-raw '
{
  "Id": "cipe-237",
  "EmailAddress": "test.user@example.com",
  "Name": "Test User",
  "Role": "LimitedAgent",
  "Culture": "sv-SE",
  "AllowedLoginTypes": [
    "Saml"
  ]
}'
Expand Collapse

 

 

Remove agent

POST /api/v2/removeagent

Removing an agent disassociates the underlying user from the account. To switch an agent from one account to another, agent should be provisioned in the new account first and then removed from the old.

Parameter Description Type Required
Username Username is either Agent Id or EmailAddress String
UsernameType UsernameType determines the exact type of username. The types are Id and EmailAddress. UsernameType is required when Agent Id has a format similar to EmailAddress. String

Example

POST /api/v2/removeagent 
{
  "Username": "test.user@example.com"
}
              
Response: 200 OK
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/removeagent' \
--header 'Authorization: Basic APIKEY' \
--header 'ContentType: application/json' \
--data-raw '
{
  "Username": "test.user@example.com"
}'
Expand Collapse

 

 

Agent single sign-on

POST /api/v2/createssoticket

Creates a single sign-on ticket for an agent. Redirect your user to the returned URL to log them in. Ticket is valid for 3 minutes and can only be used once.

Parameter Description Type Required
Username Username is either Agent Id or Agent EmailAddress. String
UsernameType UsernameType determines the exact type of username. The types are Id and EmailAddress. UsernameType is required when Agent Id has a format similar to EmailAddress. String
TargetUrl If supplied, user will be redirected to this address after login. String

Example

POST /api/v2/createssoticket 
{
  "Username": "cipe-237",
  "TargetUrl": "https://test.assently.com/a/case/edit/5a0e0866-252e-4b79-8a9b-466ea5cca5ce"
}
              
Response: 200 OK "https://test.assently.com/user/sso/?token=0ITDig220QiANbkBJxZwqkuXtojY6pBuDx8JxKol&username=cipe-237&redirect=/a/case/edit/5a0e0866-252e-4b79-8a9b-466ea5cca5ce"
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/createssoticket' \
--header 'Authorization: Basic APIKEY' \
--header 'ContentType: application/json' \
--data-raw '
{
  "Username": "cipe-237",
  "TargetUrl": "https://test.assently.com/a/case/edit/5a0e0866-252e-4b79-8a9b-466ea5cca5ce"
}'
Expand Collapse

Working with LiveID

 

 

Start LiveID Authentication

POST /api/v2/liveid/start

Starts a new authentication attempt.

Parameter Description Type Required
EmailAddress Specifies customer email address. Format: michael.j.fox@example.com. String
PhoneNumber Specifies customer phone number. Format: +4671234567 (phone number with country code included). String
EventCallback Specifies at what stages to send callbacks. Available events to get callbacks on are: Started | Verified | Unverified. LiveIdEventSubscription
Culture Specifies what language any sms or email will be sent in, can be left blank for the default language, English. Available other languages are: sv-SE for Swedish | da-DK for Danish | fi-FI for Finnish | no for Norwegian. String
AllowedEidProvider Specifies the allowed E-identification provider when authenticating, uses the CoreId provider name. Can be left blank to allow all providers. String

Example

POST /api/v2/liveid/start 
{
  "EmailAddress": "john.doe@example.com",
  "PhoneNumber": "+46762012345",
  "EventCallback": {
    "Events": [
      "Started",
      "Verified",
      "Failed"
    ],
    "Url": ""
  },
  "Culture": "sv-SE"
}
              
Response: 200 OK {
  "Id": "5a0e0866-252e-4b79-8a9b-466ea5cca5ce",
  "Status": "Pending",
  "Identity": {
    "Provider": "Unknown"
  },
  "EventCallback": {
    "Events": [
      "Started",
      "Verified",
      "Failed"
    ],
    "Url": ""
  },
  "PartyUrl": "https://app.assently.com/liveid/5a0e0866-252e-4b79-8a9b-466ea5cca5ce"
}
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/liveid/start' \
--header 'Authorization: Basic APIKEY' \
--header 'ContentType: application/json' \
--data-raw '
{
  "EmailAddress": "john.doe@example.com",
  "PhoneNumber": "+46762012345",
  "EventCallback": {
    "Events": [
      "Started",
      "Verified",
      "Failed"
    ],
    "Url": ""
  },
  "Culture": "sv-SE"
}'
Expand Collapse

 

 

Start Swedish BankId Authentication

POST /api/v2/liveid/swedishbankid

Starts a new authentication attempt using Swedish BankID.

Parameter Description Type Required
NationalId Specifies customer swedish national ID. Format: 8-digits with optional dash continued with last 4 digits for the Swedish number (YYYYMMDD[-]NNNN). String
EventCallback Specifies at what stages to send callbacks as well as where to send them. Available events to get callbacks on are: Started | Verified | Unverified LiveIdEventSubscription

Example

POST /api/v2/liveid/swedishbankid 
{
  "NationalId": "19910203-1234",
  "EventCallback": {
    "Events": [
      "Started",
      "Verified",
      "Failed"
    ],
    "Url": ""
  }
}
              
Response: 200 OK {
  "Id": "5a0e0866-252e-4b79-8a9b-466ea5cca5ce",
  "Status": "Pending",
  "Identity": {
    "Provider": "Unknown"
  },
  "EventCallback": {
    "Events": [
      "Started",
      "Verified",
      "Failed"
    ],
    "Url": ""
  },
  "PartyUrl": "https://app.assently.com/liveid/5a0e0866-252e-4b79-8a9b-466ea5cca5ce"
}
Expand Collapse
cURL
curl --location --request POST 'https://app.assently.com/api/v2/liveid/swedishbankid' \
--header 'Authorization: Basic APIKEY' \
--header 'ContentType: application/json' \
--data-raw '
{
  "NationalId": "19910203-1234",
  "EventCallback": {
    "Events": [
      "Started",
      "Verified",
      "Failed"
    ],
    "Url": ""
  }
}'
Expand Collapse

 

 

Get LiveID Authentication Status

GET /api/v2/liveid/status

Returns the status of an on-going authentication attempt.

Parameter Description Type Required
id Guid

Example

GET /api/v2/liveid/status ?id=5a0e0866-252e-4b79-8a9b-466ea5cca5ce
              
Response: 200 OK {
  "Id": "5a0e0866-252e-4b79-8a9b-466ea5cca5ce",
  "Status": "Pending",
  "Identity": {
    "Name": "Assently Testperson",
    "NationalId": "19910203-1234",
    "EIdSerialNumber": "ABC0123456789",
    "Date": "2026-10-07T22:05:48.9464178Z",
    "Provider": "se-bankid"
  },
  "EventCallback": {
    "Events": [
      "Started",
      "Verified",
      "Failed"
    ],
    "Url": ""
  },
  "PartyUrl": "https://app.assently.com/liveid/5a0e0866-252e-4b79-8a9b-466ea5cca5ce"
}
Expand Collapse
cURL
curl --location --request GET 'https://app.assently.com/api/v2/liveid/status?id=5a0e0866-252e-4b79-8a9b-466ea5cca5ce' \
--header 'Authorization: Basic APIKEY'
Expand Collapse

Models

These models are representations of objects in the Assently domain model.

AccountInfoModel

Information about the account which the case belongs to.
Property Description Type Required
ExternalId The external ID of the account, if any. String
MasterAccountExternalId The external ID of the master account, if any. String
Name The name of the account String

StakeholderCaseApprovalReview

Response by stakeholder, added as approver, on case with that require approval.
Property Description Type Required
Status Stakeholders approval or rejection. String (notreviewed, approved, rejected or approvedasagent)
ReviewedOn Timestamp of approval or rejection given by stakeholder as part of a case approval. DateTime
Comment Comment given by stakeholder if they have rejected case as part of a case approval. String

CaseEventModel

Payload in event callbacks for Case Events.
Property Description Type Required
Model The Case for which the event applies. CaseModel
PartyId The party which caused the event to occur. Included when applicable, for instance for the SignatureAdded event. String
AccountInfo Information about the account which the case belongs to. AccountInfoModel
When When the event occurred specified in UTC format YYYY-MM-DDThh:mm:ss. DateTime
Type Type of event (CaseEvent or LiveIdEvent). String
Event Event that occured. String (created, sent, recalled, finished, rejected, expired, deleted, signatureadded, approvalrequested, reminded, metadataupdated, signed, approvaladded, rejectionadded or finalapproval)

CaseEventSubscription

Subscribe to events related to the case. See the Events property for available events. Besides HTTP you can also utilize:

E-sign protocol

E-sign protocol allows to send more data to multiple destinations. It is set in the URL property of the caseEventSubscription and has a format like this: esign:// where the domain part is a base 64 encoded JSON string which is formatted like this:

{
    "callbacks": [ "link1", "link2" ],
    "documentCallbacks": ["link1", "link2"],
    "identityCallbacks": ["link1", "link2"]
}
PropertyDescriptionRequired
callbacksList of links for sending the standard callback information to the endpoints
documentCallbacksList of links that will receive the receipt document as a stream
identityCallbacksList of links that will receive the identification document as a stream
Property Description Type Required
Events The registered URL will receive notifications for these events. List of strings (created, sent, recalled, finished, rejected, expired, deleted, signatureadded, approvalrequested, reminded, metadataupdated, signed, approvaladded, rejectionadded or finalapproval)
Url When one of the listed events occur, the event data will be posted to this URL. String

CaseModel

The Case is an envelope containing all information about the signing process.
Property Description Type Required
Id Case Id. Guid
Status Status of this case. String (pending, draft, sent, finished, expired, rejected, signed or pendingapproval)
Name Name of the case. If omitted, will be set to an empty string. String
NameAlias Alternate name for internal use. Not visible to parties. If set it substitutes the Name property. When the case is created from a template, this property is always empty. If omitted, will be set to an empty string. String
AccountId Account Id of the case. The Account connected to the case cannot be updated. Number
MasterAccountId Master account Id of the case. The master account connected to the case cannot be updated. Number
Parties Parties who should sign. See Party subtype for more information. List of PartyModels
Documents List of documents to sign. See Document subtype for more information. List of DocumentModels
Visibility Controls how cases are visible to other agents. By default, cases are visible to other agents ('group'). String (group, private or inherit)
AllowedSignatureTypes Allowed signature types. Any combination of methods is allowed. See information on signature types in Basics section List of strings (electronicid, touch, sms or quickintent)
Description Description of the case, included in emails to parties. If omitted will be set to empty string. String
Stakeholders Stakeholders, notified once a case is signed. List of StakeholderModels
Metadata Metadata for this case. Metadata can be used when searching for cases. Key/value dictionary
CancelUrl URL where user is sent when rejecting the case. String
ContinueUrl URL to continue to when signature has been completed. If omitted will be set to empty string. String
ContinueName Name of URL to continue to when signature has been completed. If omitted will be set to empty string. String
ContinueAuto Automatically continues to the ContinueUrl when the signature has been added. The case can have a status of Sent, Signed or Finished at the time of addition of signature. The case will have status Sent for multi-party cases where the last party has not yet signed. The case will have a status of either Signed or Finished when all parties have signed. Boolean
NotificationMethods Determines how to notify parties of signature requests and finished cases. Default when omitted is Email. List of strings (none, email or sms)
SendSignRequestEmailToParties Send signature request notifications to all parties when the case is created. If false, no messages of this type will be sent, regardless of NotificationMethods. Boolean
SendFinishEmailToCreator Send email notifications to creator when the case has been finished. Boolean
SendFinishEmailToParties Send email notifications to parties when the case has been finished. If false, no messages of this type will be sent, regardless of NotificationMethods. Boolean
SendRecallEmailToParties Send email notifications to parties when the case has been recalled. Boolean
RequestMessage Custom message used the request to sign notification email. Overrides the system default message. String
RequestMessageSms Custom message used in the request to sign notification SMS. Overrides the system default message. String
FinishedMessage Custom message used in the notification email to parties when all parties have signed. Overrides the system default message. String
FinishedMessageSms Custom message used in the notification SMS to parties when all parties have signed. Overrides the system default messages. String
Culture Culture of case. Will be set to the authenticated user's culture if omitted. String
SignInSequence Enforce a signing order. When false, parties are notified and can sign simultaneously. Boolean
AccessControl Define whether parties must provide additional credentials to access the case. String (default, sms or electronicid)
IdentityCheck Party is required to take a photo of ID before signing. Boolean
IsEditable Indicates that documents in this case (provided that they contain form fields) can be edited by agent or party prior to first signature. Boolean
MergeOnSend For cases where IsEditable is enabled, this setting will merge and make the document(s) read-only when the case is sent. Boolean
UseGroupNames Display the group name fields (known as Company Name in the UI) for each party. If true, group name for each party must be set before the case can be sent. Boolean
ExpireAfterDays Signing deadline, relative to when the case is sent. ExpireOn overrides this property. Default when omitted is 0. Number
ExpireOn Absolute signing deadline. If set, the case will expire on this date and time. Date specified in UTC format YYYY-MM-DDThh:mm:ss. DateTime
RemindAfterDays A reminder will be sent automatically to parties that haven't signed after the specified number of days. Default when omitted is 0. Number
RemindOn A reminder will be sent on this date and time. Date specified in UTC format YYYY-MM-DDThh:mm:ss. DateTime
CreatedOn When the case was created. Date specified in UTC format YYYY-MM-DDThh:mm:ss. DateTime
TemplateId If based on a template, this is a reference to the template. Guid
ApprovalRequired Approval from a manager is required to send the case. When set, cases must be sent using /api/v2/requestapproval. Boolean
ApprovalType Approval requirements that must be met. When set, cases must be sent using /api/v2/requestapproval. String (requireall or requireany)
Approvers Approvers are notified that the case must be reviewed and approved before being sent. List of StakeholderModels
ApprovalRequestedOn Set if and when the request for approval is made. Date specified in UTC format YYYY-MM-DDThh:mm:ss. DateTime
SentOn When the case was sent for signing. Date specified in UTC format YYYY-MM-DDThh:mm:ss. DateTime
ReminderSentOn When the latest reminder was sent. Date specified in UTC format YYYY-MM-DDThh:mm:ss. DateTime
Hash Once the case is signed, this property contains the compound hash for the case. String
AgentUrl Agents can edit and follow the progress of this case at this URL. Requires login. String
EventCallback We'll send a server side callback when one of your subscribed events occur. CaseEventSubscription
Procedure process defaults String (default, form, payload or batch)
Rejected Rejection reason if case has status rejected Rejection
DisablePartyQuestion Determines if parties can ask questions Boolean
SendRejectNotification Determines if email notifications are sent to creator when the case has been rejected. Boolean
TemporaryId An ephemeral ID that can be used for quick lookups, valid for 24 hours after the case is created. Number
AllowEditApprover Allow agents to change approver details if this is true. When set, cases must be sent using /api/v2/requestapproval. Boolean

DocumentModel

Represents a Document in a Case.
Property Description Type Required
Id String
Filename String
Data Base64 content of file. When creating a case either this or the Hash property must be set. When retrieving a case, this property will be set as empty. You should use 'Retrieve a document' request to get document data. String
ContentType File content type, such as 'application/pdf' String
Size File size in bytes. Number
Hash Hexadecimal SHA2-512 hash of file. When creating a case, either this or the Data property must be set. When retrieving a case, this field will have value set but not the Data property. String
Type Originals are what you add. 'Receipt' is the signed document (a document that contains a merge of all originals and the verification page). String (original, receipt, hash, batchfile, unsealedreceipt or partyattachment)
FormFields Form field data from the document. If the case is editable, data in this dictionary is synchronized with form fields in the document. Key/value dictionary
Order When a case has multiple documents, their order can be specified (optional) Number
Title PartyAttachments: Optional title of a Party Attachment field String
IsRequired PartyAttachments: Require the Party Attachment field to have an attachment before case can be signed. Boolean

LiveIdEventSubscription

Subscribe to events related to the authentication attempt. See the Events property for available events.
Property Description Type Required
Events The registered URL will receive notifications for these events. List of strings (started, verified or failed)
Url When one of the listed events occur, the event data will be posted to this URL. String

NotificationStatus

Represents statuses of notifications sent to the Party.
Property Description Type Required
Email Delivery Status of the email sent to the party. Values: Pending: When email sending is pending in case of SigninSequence; Sent: When email is sent and delivery notification is not received yet; Delivered: When email delivered notification is received from email service provider; Undeliverable: When email bounced or complaint notification is received from email service provider. String (pending, sent, delivered or undeliverable)

PartyModel

Represents a signing party in a case.
Property Description Type Required
Id Id of this party. Unique within the case to which this party belongs. String
Name Full name of the party. String
GroupName Indicates that party is part of a group or company, for example 'Acme Inc'. String
EmailAddress Email address. Notifications are sent to this address. String
SocialSecurityNumber Social security number. 8-digits with optional dash continued with last 4 digits for the Swedish number (YYYYMMDD[-]NNNN), 11-digits and letters for the Finnish number (DDMMYY[+, - or A]ZZZQ) and 10 with an optional dash (DDMMYY[-]SSSS) for the Danish number. String
EidSerialNumber eID serial number for the providers that do not support national ID/Social security number. String
SignedOn Date when party signed. Date specified in UTC format YYYY-MM-DDThh:mm:ss. DateTime
SignatureData If signed with an Electronic Id, this property contains the signature certificate data. String
PartyUrl Party can review and sign the case at this URL. Will be sent to party if notifications are enabled. String
MobilePhone Format: +4671234567 (phone number with country code included and is required). Used for SMS Notifications, SMS Signatures and SMS Access Codes. If omitted, this Party can use any number. String
Culture Overrides the default culture of this case. Notifications and signing instructions will be in the specified language. String
AnyoneCanSign If true, the party remains open and information such as e-mail, group name and name can be added/modified by the party prior to signing. Boolean
IpAddress IP Address of the party String
Provider Readonly. The method that was used to sign. If the party has not yet been signed ‘Unknown’ will be returned. Provider Names: ‘Sbid’ for BankID, ‘Telia’ for Telia e-leg, ‘Touch’, ‘Sbid_mobil’ for Mobilt BankID, ‘Sms’, ‘PhysicalVerified’ for Hand signature, ‘Tupas’, ‘TapAndHold’ for QuickIntent, ‘Mobiilivarmenne’, ‘NemId’ for Nem ID, ‘VrkCertificate’ for Vrk-FINeID, ‘NBid’ for Norwegian BankID, ‘NBidMobile’ for Norwegian BankID Mobile. String
SignatureType Readonly. Signature type that was used to sign. If the party has not yet been signed ‘Unknown’ will be returned. String (electronicid, touch, sms or quickintent)
ShowInternalInformation Whether the party should be able to view the internal information of the case before signing. Boolean
Assignable Whether this party is assignable by another party. Requires SignInSequence to be enabled and cannot be enabled for the first party. Can not be used with signing groups. Boolean
SignsAs The signing order of parties when SignInSequence is enabled. Parties who have the same SignsAs are in the same signing order group. Groups can not be used with Assignable. Number
NotificationStatus Statuses of notifications sent to the party. See NotificationStatus subtype for more information. NotificationStatus
Reviewed Whether the party has reviewed a case or not. Boolean

Rejection

Information about why a party rejected the case if the case is rejected
Property Description Type Required
PartyId Id of the party who rejected the case. String
Message The reason why the party rejected the case String
Date Date and time when the party rejected the case DateTime

StakeholderModel

Represents a stakeholder in a case. Stakeholders are able to access the signed document.
Property Description Type Required
Id Id of this stakeholder. Unique within the case. String
Name Full name of the stakeholder. String
EmailAddress E-mail Address of the stakeholder. String
MobilePhone Used for SMS Notifications and SMS Access Codes. String
NationalID National ID number, for example a Swedish personnummer. String
EidSerialNumber eID serial number for the providers that do not support national ID number. String
Culture Overrides the default culture of this case. Notifications will be in this language String
StakeholderUrl Stakeholder can use this URL to view the case. If notifications are enabled, they will be sent to stakeholder once the case is finished. String
ApprovalReview If stakeholder is an approver on a case, ApprovalReview will contain their response. See StakeholderCaseApprovalReview subtype for more information. StakeholderCaseApprovalReview

Error handling

Failed requests return a HTTP 400 status code and a descriptive error message. Unexpected errors will return HTTP 500. In some cases, 500 errors will include a "hint" to the problem in the JSON response body.

Error code Message
E000 Internal error.
E001 File is empty.
E002 Filename is missing.
E004 Invalid e-mail address.
E005 E-mail is already registered.
E007 Password must be between 15 and 64 characters long.
E008 FileInfo must be supplied.
E009 E-mail addresses are duplicated.
E010 E-mail already belongs to another user.
E011 User must be authenticated to invoke this command.
E012 User must be validated to invoke this command.
E013 Name is required.
E014 Validation code is not valid.
E015 Account name is required.
E016 Invalid VAT number.
E017 Account already exists.
E018 User must have administrative rights for the specified account to invoke this command.
E019 Invalid account identifier.
E020 User is already mapped to the account.
E021 User is not mapped to the account.
E022 User may not remove himself from the account.
E023 User may not change himself on the account.
E024 Invalid SAML response.
E025 Invalid party code.
E026 Invalid case id.
E027 Assigned agents must be removed first.
E028 Invalid document id.
E029 Message cannot be empty.
E030 User is not creator of case.
E031 User does not belong to case.
E032 User has signed the case.
E033 User is not allowed to view case.
E034 Invalid hash code.
E035 Invalid content type.
E036 Signing canceled by user.
E037 Invalid password.
E038 Invalid address.
E039 User is not registered.
E040 Case has status finished.
E041 At least one signer is required.
E042 Only draft cases can be sent.
E043 A Transaction cannot result in Balance dropping below zero.
E044 When Amount is 0, the TransactionType must be FreeSignature.
E045 Transaction deposit amount must be positive.
E046 Transaction withdrawal amount must be zero or negative.
E047 Transaction refund must be positive.
E048 Payment not found.
E049 Payment has already been authorized.
E050 Payment has already been settled.
E051 Payment has not been authorized yet.
E052 Receipt not found.
E053 Only draft cases can be modified.
E054 Not a party of this case.
E055 That string can't be NULL.
E056 Invalid reference id.
E057 At least one document must be added to the case.
E058 No more documents can be added to the case
E059 A signature is required.
E060 Password must be repeated exactly.
E061 Invalid password reset code.
E062 Invalid web URL.
E063 Document is required.
E065 Only supported for one party.
E066 Invalid signature type.
E067 No signature type selected.
E068 IP-Address not authorized.
E069 Case is not finished.
E070 Case is not sent.
E071 User must have Operation Officer privileges to invoke this command.
E072 InviteCode may be invalid, expired, accepted or rejected.
E073 The template is not public.
E074 Case is not publicly available.
E075 Party has not signed the case yet.
E076 All assigned parties must have names.
E077 All assigned parties must have email addresses.
E078 All assigned parties must have valid email addresses.
E079 All parties must have group names if group names are enabled.
E080 Party is read only.
E081 Hash and document data cannot be used simultaneously.
E082 It is not allowed to have multiple names with the same name.
E083 Mobile phone number is not valid.
E084 SMS code is not valid.
E085 SMS code has expired.
E086 At least one administrator must be connected to the account.
E087 Date time is out of range.
E088 Maximum SMS code attempts reached.
E090 Invalid user id.
E091 A plan already exists for that name.
E092 Temporary offline.
E093 Invalid plan identifier.
E094 Account doesn't have required feature.
E096 Party has an invalid national id-number
E097 Invalid form field name.
E098 Only pending or sent cases can be downloaded.
E098 Invalid culture.
E099 Only editable cases can be downloaded.
E099 Case has no payload.
E100 Case is already sent.
E101 All assigned parties must have mobile phone numbers
E102 The specified email address does not belong to any user in the system.
E103 All stakeholders must have valid email addresses.
E104 Batch document is required.
E105 Batch document must contain valid case information.
E106 Batch file must be of valid file type.
E107 The requested case is not a batch send cases case.
E108 All merge parties must have valid email.
E109 All merge parties must have names.
E110 All merge parties must have group names.
E111 All merge parties must have valid cell phone numbers.
E112 A batch file is already uploaded to the case.
E113 The batch file contains more than one identical header.
E114 The batch file doesn't contain any headers.
E115 Print job could not be found.
E116 Cannot chain multiple levels of accounts.
E117 Case cannot be made editable.
E118 Party has already signed.
E119 Template not found.
E119 Not Authorized.
E120 Agent not found.
E121 That string can't be empty.
E122 Login Required.
E123 Content Type not allowed.
E124 This file type is not supported.
E125 Permission Denied.
E130 Key already exists.
E131 Key cannot be empty.
E132 Invalid Format.
E133 File extension not allowed.
E134 Role not found
E134 Case has wrong status.
E135 Role is required.
E135 Case is not yet digitally sealed.
E136 EmailAddress is required.
E136 Case is not allowed to delete
E138 A PDF version of one of the documents in the case is not converted.
E139 Case is deleted.
E140 Signing party social security number does not match with original party.
E141 Invalid E-Sign protocol URL.
E142 Invalid AccessControl Method.
E143 Case name can max be 255 characters.
E144 Party name can max be 255 characters.
E145 Company name can max be 255 characters.
E146 File name can max be 255 characters. (includes file extension)
E147 Template name/name alias can max be 255 characters.
E148 Case is not pending approval
E149 At least one approver is required.
E150 All approvers must have a valid email address or mobile phone number.
E151 Invalid email or phone number
E152 Case does not require approval
E153 User is not allowed to web login.
E154 The e-mail is primary address for an user.
E155 The case has already been signed by a party.
E156 The case is not in status to allow uploading of party attachaments.
E157 The document type is not party attachment.
E158 The party attachament is already uploaded.
E159 The party attachament title is longer than 255 characters.
E160 The case has multiple parties without following signature order.
E161 Only the first party of a case can edit party attachments.
E162 All required party attachments must be uploaded before signing.
E163 Maximum document size allowed is 100 MB.
E164 Multiple parties of a case with party attachments should follow signature order.
E165 At least one document or required party attachment must be added to the case.
E166 It's not your turn to sign yet.
E168 This operation is already in progress. Please wait.
E169 The uploaded batch file contains too many cases, limit is 25 cases per batch.
E170 Invite is not for current user.
E172 Account has expired or is disabled
E171 Invalid Pdf Document.
E172 The country is not supported.
E173 Assignable parties are not supported within signing groups.
E174 Complete pending email verification before adding a new email.
E175 Requested resource could not be found.
E176 Something went wrong. We will address it soon.
E178 The account could not be found.
E179 Name is not valid.
E180 Company name is not valid.
E181 The combined size of all documents in the case can not exceed 500 MB.
E182 Maximum document size allowed is 15 MB.
E184 JsonPatchDocument is null or has invalid schema.
E189 Role exists in pending invitation. Delete the invitation first.
E190 Case is not eligible for removing signing deadline. Sent date is null
E191 Case does not have expire time set
E192 Maximum SMS length is 300 characters.
E194 Approval required.
E195 Approval required is turned off.
E196 There are no approvers to approve the case
E198 Stakeholder mobile phone number is incorrect.
E199 Stakeholder national id number is incorrect.
E201 Stakeholder already exists.
E202 Sort order number is not valid.
E203 Password protected PDFs are not supported.
E204 This password is too easy to guess. Please choose a different one.
E205 Password should not contain contextual info like e-mail, name, account name
E206 Two-factor authentication can only be enabled for accounts with username and password login.
EX400 Bad Request, Verify request structure.
EX401 Access unauthorized, login required.
EX404 Not Found.