API

This document introduces the Web API for eLegere.

The eLegere Web API enables the web clients to request data from eLegere's applications. The returned data depends on the level of authorized access from the user's session: if the user hasn't a specific authorization, the API won't return some data.

Note

The API returns all the responses as either JSON objects or content stream.

Every time your third-party integration requests data through the API, the returned JSON objects encodes the different data types according to specific formats. Check the eLegere Data Types reference to learn about the eLegere data types' format.

Tip

If a method requires the Application Id, check the section Retrieve Application's ID to learn how to retrieve an application's Id.

You can retrieve the Domain Id by accessing the Domain Settings and clicking on the Url button to copy it.

Tip

Certain methods listed below require a Detail's Relation Key as parameter to perform actions on Detail tables. Check the Retrieve a Detail's Relation Key tutorial to learn how to retrieve it.

Note

There are limitations for both the URL requests and the requests' Body in POST:

URL String for the request has the maximum length of 2048 characters.
The API accepts Body size for the request up to 60 Mb.

These limitations are independent from eLegere.

Info

Check the Conventions and HTTP Status Codes to learn about terms conventions and HTTP Status Codes responses.

Warning

In the Header description, SessionToken stands for the access_token in the Request.

Authentication¶

Authentication

The method enables the user to authenticate to the eLegere's environment. The service returns a Session Token with everything required for the access.

Request¶


Method	POST
URL	`{base_url}/identityprovider/connect/token`
Protocols	HTTPS
ContentType	application/x-www-form-urlencoded
Headers	no headers required
Return	JSON Object

Body:¶

client_id=elegereapiv1&username={email}&password={user password}&grant_type=password&scope=openid apiv1 nosession

Examples¶

Create a WEB request to authorize a user's access and obtain a Session Token for them. The JSON contains the Session Token, the expiration time in milliseconds, the type, and the scope.

Raw Request:

POST /identityprovider/connect/token
Content-Type: application/x-www-form-urlencoded
client_id=elegereapiv1&username={email}&password={user password}&grant_type=password&scope=openid apiv1 nosession

Raw Response:

//HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8
{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZC...",
    "expires_in":3600,
    "token-type": "",
    "scope": ""
}

Get Items¶

Data

The method queries an application through the WorkspaceId, ApplicationId, and Session Token to obtain an application's data. Check Filters' Query Composition for more info about the operators and options eLegere supports for the items' queries.

The method requires the Detail Relation Key (&relationKey=445a7899...) only if you must retrieve the Detail rows. Otherwise, remove the &relationKey parameter from the request.

Info

Retrieving Detail rows requires the Detail's Relation Key. Check the Retrieve a Detail's Relation Key tutorial to learn how to retrieve it.

Request¶


Method	POST
URL	`{base_url}/SmartExplorerApi/api/items`
Protocols	HTTPS
ContentType	application/json
Headers	ApplicationId, SessionToken, WorkspaceId
Return	Array of JSON Objects

Body:¶

{"query":"$top=200&$skip=0&$orderby=DT_CREATION desc&$filter=fieldName ODATA_Operator 'value'&relationKey=445a7899..."}

Examples¶

In this case, the request retrieves only the Master rows of an application. The request provides the Session Token for the access, the response file's format, the workspace Id (i.e the Domain) and application's Id for the the API to retrieve the data. The body contains the string with the query. The query provides the parameters for the top, exceptions, and the order and field for the sorting. The returned object contains the retrieved Master rows.

Raw Request:

// POST /SmartExplorerApi/api/items
// Content-Type: application/json
// ApplicationId: "49ed-b7f3-ef6a2d3177f2"
// SessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."
// WorkspaceId: "3a98b7ec-8f6c-49ed-b7f3-ef6a2d3177f2"


{"query":"$top=200&$skip=0&$orderby=DT_CREATION desc$filter=fieldForRequest eq 'API_TEST_RB_1'"}

Raw Response:

// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

[
  {
    "Id": 1,
    "Field1": "Value 1",
    "Field2": 2,
    "Field3": true,
    "CT_ATTACHMENTS": null,
    "DT_CREATION": null,
    "DT_LAST_UPDATE": null,
    "ROW_ORDER": null,
    "TIMESTAMP": "AAAAAQ==",
    "USER_ID_CREATION": null,
    "USER_ID_LAST_UPDATE": null
  }
]

In this other case, the request retrieves the Detail rows. The request provides the Session Token for the access, the response file's format, the workspace Id (i.e the Domain) and application's Id for the the API to retrieve the data. The body contains the string with the query. The query provides the parameters for the top, exceptions, and the order and field for the sorting. The returned object contains the retrieved Detail rows.

Raw Request:

// POST /SmartExplorerApi/api/items
// Content-Type: application/json
// ApplicationId: "49ed-b7f3-ef6a2d3177f2"
// SessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."
// WorkspaceId: "3a98b7ec-8f6c-49ed-b7f3-ef6a2d3177f2"


{"query":"$top=200&$skip=0&$orderby=DT_CREATION desc$filter=fieldForRequest eq 'API_TEST_RB_1'&relationKey=304c9015-fbe0-4438-b6bf-f92419f3b9c5"}

Raw Response:

// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

[
  {
    "Id": 1,
    "Field1": "Value 1",
    "Field2": 2,
    "Field3": true,
    "CT_ATTACHMENTS": null,
    "DT_CREATION": null,
    "DT_LAST_UPDATE": null,
    "ROW_ORDER": null,
    "TIMESTAMP": "AAAAAQ==",
    "USER_ID_CREATION": null,
    "USER_ID_LAST_UPDATE": null
  }
]

Get Items Count¶

Data

The method queries an application through the WorkspaceId, ApplicationId, and Session Token to count the exact number of items in the application satisfying the criteria.

The method requires the Detail Relation Key (&relationKey=445a7899...) only if you must count Detail rows. Otherwise, remove the &relationKey parameter from the request.

Info

Counting Detail rows requires the Detail's Relation Key. Check the Retrieve a Detail's Relation Key tutorial to learn how to retrieve it.

Request¶


Method	POST
URL	`{base_url}/SmartExplorerApi/api/items`
Protocols	HTTPS
ContentType	application/json
Headers	ApplicationId, SessionToken, WorkspaceId
Return	JSON Object

Body:¶

{"query":"$inlinecount=allpages&relationKey=445a7899..."}

Examples¶

The request provides the Session Token for the access, the response file's format, the workspace Id (i.e the Domain) and application's Id for the the API to retrieve the info. The response reports the number of items according to the criteria specified in the body.

Raw Request:

// POST /SmartExplorerApi/api/items
// Content-Type: application/json
// ApplicationId: "49ed-b7f3-ef6a2d3177f2"
// SessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."
// WorkspaceId: "3a98b7ec-8f6c-49ed-b7f3-ef6a2d3177f2"

{ "query": "$inlinecount=allpages" }

Raw Response:

// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

{
  "Timestamp": 637534770772767600,
  "Items": [
    {
      "_FieldCount_": 876
    }
  ]
}

Save¶

Data

The method queries an application through the WorkspaceId, ApplicationId, and Session Token to create or update a row on the application's table.

If you want to create a new row, insert a negative progressive number as row's Id and the Storage fields as keys with their values. Assign the null value to the key corresponding to the Storage's Identity field and the TIMESTAMP key; the service will handle it.

E.g. If you save three new rows, insert -1 as Id of the first row, -2 for the second, and so on. The service will assign a proper database Id after the save. Leave the TIMESTAMP key and Storage's Identity field with null values.

If you want to update an item:

1) Call the Get Items API method to retrieve the information of the rows to update.

2) Recover the TIMESTAMP key value from the retrieved objects for the rows to be updated.

3) Call the Save method; insert in TIMESTAMP keys the values from step (2) in the objects to save the rows.

Add an object for each Detail on which you want to save rows to the "Details" key's array. Each object related to a Detail must have the following characteristics:

1) The "RelationKey" key with the value of the Detail's relation key.

2) The "Rows" key: an array containing the objects of each row to save on that specific Detail.

If there are no Detail rows to save, leave the "Details" key empty.

Info

Adding Detail rows to either an existing Master row or a new Master row requires the Detail's Relation Key. Check the Retrieve a Detail's Relation Key tutorial to learn how to retrieve it.

Request¶


Method	POST
URL	`{base_url}/SmartExplorerApi/api/items/save`
Protocols	HTTPS
ContentType	application/json
Headers	ApplicationId, SessionToken, WorkspaceId
Return	Array of JSON Objects

Body:¶

{
  "Rows": [
    {
      "Row": {
        "Name": "John",
        "Surname": "Doe",
        "Id": -1,
        "IdRow": null,
        "TIMESTAMP": null
      },
      "Details": [
        {
          "RelationKey": "a5637422-8d21-48e7-a032-c9eba7713d9f",
          "Rows": [
            {
              "Id": -1,
              "field": "Field Value"
            }
          ]
        }
      ]
    }
  ]
}

Examples¶

In this case, the request saves a single Master row. The request contains the row's information as object: each row's field and value corresponds to an object's key. The response provides an object detailing if the saving process was successful (i.e. the key "IsSaveSuccessfully"), what has been saved, created, edited or deleted, and a link to the Master's row (i.e. the key "MasterRowLink" in the object). Note that there are two unique fields identifying the row: one is the database's Identity (Id) and the other is the Identity field created in eLegere (IdRow in the example). If the request must update an existing row, you must provide only the exact value of the database's Id key (Id).

Raw Request:

// POST /SmartExplorerApi/api/items/save
// Content-Type: application/json
// ApplicationId: "65abe727-93bc-47e0-a372-21f399c37e69"
// SessionToken: "eyJhbGciOiJSUzI1NiIsImtpZCI6IjM..."
// WorkspaceId: "87bab64d-f1ad-4496-b66a-25748206458c"

{
  "Rows": [
    {
      "Row": {
        "Name": "John",
        "Surname": "Doe",
        "Id": -1,
        "IdRow": null,
        "TIMESTAMP": null
      },
      "Details": []
    }
  ]
}

Raw Response:

// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

{
  "IsSaveSuccessfully": true,
  "ReturnStates": [],
  "ReturnData": {
    "PrimaryKeyData": {
      "-1": {
        "newKeys": {
          "7acaf2c9-aa5b-424b-88f1-018d30d867e9": "12"
        }
      }
    }
  },

  "MasterToRecalculate": [],
  "CreatedItems": 1,
  "UpdatedItems": 0,
  "DeletedItems": 0,
  "LockedItems": 0,
  "MasterRowLink": "https://...",
  "RowIdentifier": "IdRow",
  "StorageName": "sStorageExample",
  "SavedItems": null
}

In the following case, the request edits an existing row while attaching also a new Detail row. The Master's row object must contain just the fields to be updated with the new values. The method requires just the database's Id obtained with the GetItems method to identify the row and update it. When updating, no need to specify values for the Storage's Identity field. Remember to specify in the object the row's TIMESTAMP value obtained through the Response from Add a row object in the "Details" key's array for each Detail row to add. The Detail row must have -1 for the database's Id and null for the eLegere's Identity field, since they're new rows to be added. Like any new row, assign the null value to the TIMESTAMP key, the service handles that as well.

Raw Request:

// POST /SmartExplorerApi/api/items/save
// Content-Type: application/json
// ApplicationId: "65abe727-93bc-47e0-a372-21f399c37e69"
// SessionToken: "eyJhbGciOiJSUzI1NiIsImtpZCI6IjM..."
// WorkspaceId: "87bab64d-f1ad-4496-b66a-25748206458c"

{
  "Rows": [
    {
      "Row": {
        "Name": "Daniel",
        "Surname": "Doe",
        "TIMESTAMP": 20251211
      },
      "Details": [
        {
          "RelationKey": "a5637422-8d21-48e7-a032-c9eba7713d9f",
          "Rows": [
            {
              "Address:": "via Fratelli Cuzio 42",
              "City:": "Pavia",
              "ZIP": "27100",
              "IdRow": null,
              "Id": -1,
              "TIMESTAMP": null
            }
          ]
        }
      ]
    }
  ]
}

Raw Response:

// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

{
  "IsSaveSuccessfully": true,
  "ReturnStates": [],
  "ReturnData": {
    "PrimaryKeyData": {
      "-1": {
        "newKeys": {
          "8acaf3c4-aa0b-424b-88f1-018d99d867e9": "12"
        }
      }
    }
  },

  "MasterToRecalculate": [],
  "CreatedItems": 1,
  "UpdatedItems": 1,
  "DeletedItems": 0,
  "LockedItems": 0,
  "MasterRowLink": "https://...",
  "RowIdentifier": "IdRow",
  "StorageName": "sStorageExample",
  "SavedItems": null
}

Delete¶

Data

The method queries an application through the WorkspaceId, ApplicationId, and Session Token to delete a row from the application's table.

Delete a row by inserting in the Id in the object's Id key and its Timestamp in the TIMESTAMP key. The method deletes the row with that particular Id and Timestamp.

Add the Detail's Relation Key to the "RelationKey" key to delete a Detail row. Otherwise, leave the null value assigned to "RelationKey".

Info

Removing Detail rows requires the Detail's Relation Key. Check the Retrieve a Detail's Relation Key tutorial to learn how to retrieve it.

Request¶


Method	POST
URL	`{base_url}/SmartExplorerApi/api/items/delete`
Protocols	HTTPS
ContentType	application/json
Headers	ApplicationId, SessionToken, WorkspaceId
Return	Array of JSON Objects

Body:¶

[
    {
        "RelationKey": null,
        "Rows": [
            {
                "Row": {
                    "Id": 4,
                    "TIMESTAMP": 20251120145011
                }
            }
        ]
    }
]

Examples¶

The following case involves deleting some Master rows. The request contains the row's Id and its Timestamp. These two values are essential to identify the row to be deleted. No Detail's Relation key required since the requests deletes Master rows.

After the deletion, the Response object reports if the operation has been successful through the IsSaveSuccessfully key's value.

Raw Request:

// POST /SmartExplorerApi/api/items/delete
// Content-Type: application/json
// ApplicationId: "65abe727-93bc-47e0-a372-21f399c37e69"
// SessionToken: "eyJhbGciOiJSUzI1NiIsImtpZCI6IjM..."
// WorkspaceId: "87bab64d-f1ad-4496-b66a-25748206458c"

[
  {
    "RelationKey": null,
    "Rows": [
      {
        "Row": {
          "Id": 55,
          "TIMESTAMP": 20251212113011
        }
      },
      {
        "Row": {
          "Id": 56,
          "TIMESTAMP": 20251212113012
        }
      }
    ]
  }
]

Raw Response:

// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

{
    "IsSaveSuccessfully": true,
    "ReturnStates": [],
    "MasterToRecalculate": [],
    "CreatedItems": 0,
    "UpdatedItems": 0,
    "DeletedItems": 1,
    "LockedItems": 0,
    "MasterRowLink": null,
    "RowIdentifier": null,
    "StorageName": null,
    "SavedItems": null
}

The following case involves deleting a Master row and a Detail. The request contains the rows' Ids and their Timestamp. These two values are essential to identify the row to be deleted. In the second object, the Detail's Relation Key has been added to identify where to delete the row.

After the deletion, the Response object reports if the operation has been successful through the IsSaveSuccessfully key's value.

Raw Request:

// POST /SmartExplorerApi/api/items/delete
// Content-Type: application/json
// ApplicationId: "65abe727-93bc-47e0-a372-21f399c37e69"
// SessionToken: "eyJhbGciOiJSUzI1NiIsImtpZCI6IjM..."
// WorkspaceId: "87bab64d-f1ad-4496-b66a-25748206458c"

[
  {
    "RelationKey": null,
    "Rows": [
      {
        "Row": {
          "Id": 55,
          "TIMESTAMP": 20251212113011
        }
      }
    ]
  },
  {
    "RelationKey": "3a61a076-9eb5-462a-8ce7-a8cac470f8a8",
    "Rows": [
      {
        "Row": {
          "Id": 111,
          "TIMESTAMP": 20251222131010
        }
      }
    ]
  }
]

Raw Response:

// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

{
    "IsSaveSuccessfully": true,
    "ReturnStates": [],
    "MasterToRecalculate": [],
    "CreatedItems": 0,
    "UpdatedItems": 0,
    "DeletedItems": 2,
    "LockedItems": 0,
    "MasterRowLink": null,
    "RowIdentifier": null,
    "StorageName": null,
    "SavedItems": null
}

Get Attachments List¶

Data

The method retrieves the attachments list of a row in an application starting from the row's Id and attachments' folder Id. Add the &relationKey= parameter with the Detail's Relation key in case the request retrieves attachments from Detail rows. In case the request involves only Master rows, remove the &relationKey= parameter.

Note

You can obtain a row's Id through the Get Items method. Replace it in the URL to identify the row's attachments list.

Info

The last part of the URL and FolderId eq FOLDERID is optional. You need the FOLDERID only to retrieve the attachment list if the attachment is nested in a folder within the row's attachments folders' tree. Check Filters' Query Composition for more info about the operators and options eLegere supports for the items' queries.

Info

Adding Detail rows to either an existing Master row or a new Master row requires the Detail's Relation Key. Check the Retrieve a Detail's Relation Key tutorial to learn how to retrieve it.

Request¶


Method	GET
URL	`{base_url}/SmartExplorerApi/api/attachments?$filter=ParentId eq ROWID and FolderId eq FOLDERID&relationKey=...`
Protocols	HTTPS
ContentType	application/json
Headers	ApplicationId, SessionToken, WorkspaceId
Return	Array of JSON Objects

Examples¶

The method retrieves the row's attachments list starting from the row's Id. The array object contains an object for each row's attachment. Each object details the individual attachment's information.

Raw Request:

GET /SmartExplorerApi/api/attachments?$filter=ParentId eq 1 and FolderId eq 4
Content-Type: application/json
ApplicationId: "49ed-b7f3-ef6a2d3177f2"
SessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."
WorkspaceId: "3a98b7ec-8f6c-49ed-b7f3-ef6a2d3177f2"

Raw Response:

// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

[
  {
    "Description": "file.xml",
    "DT_CREATION": 20220713125300,
    "DT_LAST_UPDATE": null,
    "Id": 1242,
    "FolderId": null,
    "IsFolder": false,
    "Name": "file.xml",
    "ParentId": 1,
    "TypeImage": "text/xml",
    "USER_ID_CREATION": "vesenda@elegere.com",
    "USER_ID_LAST_UPDATE": 20230405133245
  }
]

Download Attachment¶

Data

The method accesses through a Session Token and retrieves the desired attachment through its Id on the database.

Note

You can download both individual attachments and folders. If the request points a folder, the API returns a .zip archive with all the folder's attachments.

Note

In the request, the rk is the Relation Key of the Master-Detail relation. Check the Retrieve a Detail's Relation Key tutorial to learn how to retrieve rk. Note thatrk is optional in the request. You must specify rk in the request if and only if you download an attachment from a Detail's row. Otherwise, the request refers to a row on the Master table.

Request¶


Method	POST
URL	`{base_url}/SmartExplorerApi/api/attachments/download`
Protocols	HTTPS
ContentType	application/json
Headers	ApplicationId, SessionToken, WorkspaceId
Return	File Stream

Body:¶

{ "ids": [1], "rk": "46a9a5..." }

Examples¶

The method retrieves an attachment starting from the row's Id. In the example below, the method retrieves the attached XML files from two Master rows.

Raw Request:

// GET /SmartExplorerApi/api/attachment/download
// Content-Type: application/json
// ApplicationId: "49ed-b7f3-ef6a2d3177f2"
// SessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."
// WorkspaceId: "3a98b7ec-8f6c-49ed-b7f3-ef6a2d3177f2"

{ "ids": [1, 2], "rk": "" }

Raw Response:

// HTTP/1.1 200 OK
// Content-Type: application/xml;


Content-Disposition: attachment; filename="file.xml"

Run Action¶

Data

The method launches one of the Custom Actions designed for the chosen application. The method identifies the Custom Action to launch through the action's actionId.

Request¶


Method	POST
URL	`{base_url}/SmartExplorerApi/api/action/run`
Protocols	HTTPS
ContentType	application/json
Headers	ApplicationId, SessionToken, WorkspaceId
Return	JSON Object

Body:¶

{
  "actionId": "GUID",
  "parametersMap": [
    {
      "Name": "ProcedureName",
      "Value": "name of stored procedure"
    },
    {
      "Name": "Parameters",
      "Value": [
        {
          "key": "p1",
          "value": "p1 value"
        },
        {
          "key": "p2",
          "value": "p2 value"
        },
        {
          "key": "pn",
          "value": "pn value"
        }
      ]
    }
  ]
}

Examples¶

The method executes the specified Custom Actions and returns the object reporting the operation's result. If the key IsSuccessful in the object has value true, the Custom Action has run successfully.

Raw Request:

// POST /SmartExplorerApi/api/action/run
// Content-Type: application/json
// ApplicationId: "49ed-b7f3-ef6a2d3177f2"
// SessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."
// WorkspaceId: "b5b1a6ae6b314c4593c112d8d079d6d0"

{
  "actionId": "710333fc-7098-48e4-bb94-008d260a514f",
  "parametersMap": [
    {
      "Name": "Parameters",
      "Value": [
        {
          "key": "Quantity",
          "value": "10"
        }
      ]
    }
  ]
}

Raw Response:

// HTTP/1.1 200 OK
// Content-Type: application/xml;

{
  "Message": "Operation success",
  "IsSuccessful": true,
  "Result": "",
  "IsAsync": false
}

Send Email¶

Utility

The method queries the service to send an email containing the specified recipients, subject, body, and the providerId (optional) in the request. The providerId is a GUID identifying an eLegere installation's email provider configured in the settings. If the request doesn't contain any providerId, the Send Email API uses the default eLegere providerId configured during the installation.

Request¶


Method	POST
URL	`{base_url}/ewebaggregator/api/v1/email/queue`
Protocols	HTTPS
ContentType	application/json
Headers	Authorization, WorkspaceId
Return	No Object Returned

Body:¶

// POST {base_url}/ewebaggregator/api/v1/email/queue

// Content-Type: application/json
// WorkspaceId: [WORKSPACEID]
// Authorization: Bearer [SESSIONTOKEN]

{
  "providerId": "string",
  "to": ["string"],
  "subject": "string",
  "body": "string"
}

Examples¶

The service receives the request with the recipients, subject, and the body information. In the example, the request doesn't contain a providerId: it will use the default eLegere installation's provider.

Raw Request:

// POST myinstallation.elegereapp.com/ewebaggregator/api/v1/email/queue

// Content-Type: application/json
// WorkspaceId: "b5b1a6ae6b314c4593c112d8d079d6d0"
// Authorization: Bearer "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."

{
  "to": ["j.doe@vesenda.com", "d.doe@vesenda.com"],
  "subject": "Send Email API Example",
  "body": "Messages sent with Send Email API."
}

Raw Response:

1	`// Empty Response Body`