Xpand Portal API

Xpand Portal features its own RESTful web service application programming interface (API) (conforms to the Representational state transfer (REST) architectural style) with JSON Web Token (JWT) authentication that can be utilized by external applications, such as Power BI, to send queries and retrieve data from the portal as well as send data to the portal.
The SWAGGER UI and Postman API tools are used as examples of API client applications to visualize interaction with the Xpand Portal API’s resources to retrieve/send data from/to Xpand Portal.

To be able to utilize Xpand Portal API, it must be configured first.

Methods

Xpand Portal API supports the following methods:

Method Description Learn more
HEAD: /api/1.0/Entities  Used to test connection and ensure that Xpand Portal API is configured properly.  Learn more
GET: /api/1.0/Entities/Info  Returns information about a known portal entity(ies). Learn more
GET: /api/1.0/Entities/Setup  Returns detailed information about entity setup, including setup values. Learn more
POST: /api/1.0/Entities/Data/{page}  Returns data from a portal grid page. Learn more
POST: /api/1.0/Entities/DataById/{query}/{page}  Returns data from a record on a portal grid page. Learn more
POST: /api/1.0/Entities/Update/{page}  Updates data in a specific record in Xpand Portal.  Learn more
PUT: /api/1.0/Entities/Create/{page} Creates a record in Xpand Portal.  Learn more
DELETE: /api/1.0/Entities/Remove/{page}  Deletes a record in Xpand Portal. Only data created by you can be deleted. Learn more
POST: /api/1.0/Entities/Sync/Store  Updates multiple records of an entity specified in the query. Learn more
POST: /api/1.0/Entities/Sync/Get  Returns records of an entity based on the specified query. Learn more

Response codes

If successful, the methods return the 200 OK response code. 

List of HTTPS status codes that you can get: 

Error Code  Error Message 
200 OK
400 Bad request
401 Unauthorized
403 Forbidden

Method descriptions

The following methods are available:

HEAD: /api/1.0/Entities

This operation can be used to test connection and ensure that Xpand Portal API is configured properly.

HTTP request

HEAD https://<Your Portal Name>/api/1.0/Entities 

Request headers

Header Parameter Type Data Type Mandatory
сlient_id Header String Yes
  • client_id – Specifies the ID of a registered client. This ID is required to test connection and verify API configuration.

Request body

The request body is not required for this method.

GET: /api/1.0/Entities/Info

This operation returns the following information about a known portal entity(ies):  

  • Name of entity(ies) 
  • List of entity fields including their configuration (such as lookup settings) 
  • Entity setup path

HTTP request

GET https://<Your Portal Name>/api/1.0/Entities/Info

Request headers

Header Parameter Type Data Type Mandatory
сlient_id Header String Yes
accept Header String No
  • client_id – Specifies the ID of a registered client. This ID is required to test connection and verify API configuration.
  • accept – Specifies the type of response content type. To use response directly in browsers, the application/json content type is recommended. Available content types: 
    • application/json 
    • application/xml 
    • text/json 
    • text/xml

Request parameters

Parameter Parameter Type Data Type Mandatory
filter.entity  Query String No
filter.loadFields Query Boolean No
filter.loadSetup Query Boolean No

  • filter.entity – Specifies the alias/name of a known portal entity that will be used as a filter to retrieve information only about that entity. You can leave it empty to retrieve information about all known portal entities.
  • filter.loadFields – Specifies whether information about all known entity fields will be returned. 
  • filter.loadSetup – Specifies whether information about entity setup path will be returned.

Request body

The request body is not required for this method.

GET: /api/1.0/Entities/Setup 

This operation returns detailed information about entity setup, including setup values. 

HTTP request 

GET https://<Your Portal Name>/api/1.0/Entities/Setup/{page} 

Request headers

Header Parameter Type Data Type Mandatory
сlient_id Header String Yes
accept Header String No
  • client_id – Specifies the ID of a registered client. This ID is required to test connection and verify API configuration.
  • accept – Specifies the type of response content type. To use response directly in browsers, the application/json content type is recommended. Available content types: 
    • application/json 
    • application/xml 
    • text/json 
    • text/xml

Request parameters

Parameter Parameter Type Data Type Mandatory
page Path String Yes
  • page – Specifies the setup path to a portal entity for which detailed setup information will be returned. For example: /en-us/contacts/. You can type #root# in this setting to get information about all registered entities. You can get setup paths of known entities using the GET: /api/1.0/Entities/Info operation.

Request body

The request body is not required for this method.

POST: /api/1.0/Entities/Data/{page} 

This operation returns data from a portal grid page.

HTTP request 

POST https://<Your Portal Name>/api/1.0/Entities/Data 

Request headers

Header Parameter Type Data Type Mandatory
сlient_id Header String Yes
accept Header String No
  • client_id – Specifies the ID of a registered client. This ID is required to test connection and verify API configuration.
  • accept – Specifies the type of response content type. To use response directly in browsers, the application/json content type is recommended. Available content types: 
    • application/json 
    • application/xml 
    • text/json 
    • text/xml

Request parameters

Parameter Parameter Type Data Type Mandatory
page Path String Yes
  • page – Specifies the path to a portal grid page, data from which will be returned. For example: /en-us/contacts/.

Request body

{
  "Keywords": "string",
  "Paging": {
    "Index": 0,
    "Size": 0
  },
  "Sort": [
    {
      "Name": "string",
      "Dir": "string",
      "Reverce": true
    }
  ],
  "Filters": [
    {
      "Logic": "string",
      "GroupName": "string",
      "Filters": [
        {
          "Field": "string",
          "Operator": "string",
          "Value": "string",
          "Logic": "string",
          "Type": "string"
        }
      ]
    }
  ],
  "ParentItem": {
    "Page": "string",
    "Id": "00000000-0000-0000-0000-000000000000"
  }
}
  • Keywords – Specifies keywords (like in the portal search box) by which returned data will be filtered.
  • Paging  – Specifies from which grid page data should be returned and the number of records.
  • Sort – Specifies how returned data should be sorted.
  • Filter – Specify filters that will be used to filter data by field values.
  • ParentItem  – Specifies the parent item by which data will be filtered.

POST: /api/1.0/Entities/DataById/{query}/{page}

This operation return data from a specific grid page record by its unique ID.

HTTP request 

POST https://<Your Portal Name>/api/1.0/Entities/DataById

Request headers

Header Parameter Type Data Type Mandatory
сlient_id Header String Yes
accept Header String No
  • client_id – Specifies the ID of a registered client. This ID is required to test connection and verify API configuration.
  • accept – Specifies the type of response content type. To use response directly in browsers, the application/json content type is recommended. Available content types: 
    • application/json 
    • application/xml 
    • text/json 
    • text/xml

Request parameters

Parameter Parameter Type Data Type Mandatory
page Path String Yes
uniqueId Query String Yes
  • page – Specifies the path to a portal grid page, data on which will be updated. For example: /en-us/orders/all.
  • uniqueId – Specifies the unique ID of a record the data from which will be returned.

Request body

The request body is not required for this method.

POST: /api/1.0/Entities/Update/{page} 

This operation updates data in a specific record in Xpand Portal. 

HTTP request 

POST https://<Your Portal Name>/api/1.0/Entities/Update

Request headers

Header Parameter Type Data Type Mandatory
сlient_id Header String Yes
accept Header String No
  • client_id – Specifies the ID of a registered client. This ID is required to test connection and verify API configuration.
  • accept – Specifies the type of response content type. To use response directly in browsers, the application/json content type is recommended. Available content types: 
    • application/json 
    • application/xml 
    • text/json 
    • text/xml

Request parameters

Parameter Parameter Type Data Type Mandatory
page Path String Yes
  • page – Specifies the path to a portal grid page, data on which will be updated. For example: /en-us/orders/all.

Request body

{
  "UniqueId": "string",
  "Fields": [
    {
      "Name": "string",
      "StringValue": "string",
      "Type": "string",
      "Modified": true
    }
  ],
  "Keys": [
    {
      "Name": "string",
      "StringValue": "string",
      "Type": "string",
      "Modified": true
    }
  ],
  "ParentItem": {
    "Page": "string",
    "Id": "00000000-0000-0000-0000-000000000000"
  }
}
  • uniqueId – Specifies the unique ID of the record to be updated.
  • Fields  – Specifies fields where data is to be updated and values the fields should be updated with.
  • Keys – Specifies keys by which data will be filtered. A key is an additional means to identify a record.
  • ParentItem  – Specifies the parent item by which data will be filtered. 

PUT: /api/1.0/Entities/Create/{page} 

This operation creates a record in Xpand Portal. When a record is created through API, the fields are filled in with default value if there are any default value configured on the page.

HTTP request 

PUT https://<Your Portal Name>/api/1.0/Entities/Create 

Request headers

Header Parameter Type Data Type Mandatory
сlient_id Header String Yes
accept Header String No
  • client_id – Specifies the ID of a registered client. This ID is required to test connection and verify API configuration.
  • accept – Specifies the type of response content type. To use response directly in browsers, the application/json content type is recommended. Available content types: 
    • application/json 
    • application/xml 
    • text/json 
    • text/xml 

Request parameters

Parameter Parameter Type Data Type Mandatory
page Path String Yes
  • page – Specifies the path to a portal grid page, data on which will be created. For example: /en-us/orders/all.

Request body

{
  "UniqueId": "string",
  "Fields": [
    {
      "Name": "string",
      "StringValue": "string",
      "Type": "string",
      "Modified": true
    }
  ],
  "Keys": [
    {
      "Name": "string",
      "StringValue": "string",
      "Type": "string",
      "Modified": true
    }
  ],
  "ParentItem": {
    "Page": "string",
    "Id": "00000000-0000-0000-0000-000000000000"
  }
}
  • uniqueId – Specifies the unique ID of the record to be created.
  • Fields  – Specifies fields where data is to be created and values the fields should be filled in with.
  • Keys – Specifies keys by which data will be filtered. A key is an additional means to identify a record.
  • ParentItem  – Specifies the parent item by which data will be filtered. 

DELETE: /api/1.0/Entities/Remove/{page}

This operation deletes a record in Xpand Portal. Only data created by you can be deleted.

HTTP request 

DELETE https://<Your Portal Name>/api/1.0/Entities/Remove/

Request headers

Header Parameter Type Data Type Mandatory
сlient_id Header String Yes
accept Header String No
  • client_id – Specifies the ID of a registered client. This ID is required to test connection and verify API configuration.
  • accept – Specifies the type of response content type. To use response directly in browsers, the application/json content type is recommended. Available content types: 
    • application/json 
    • application/xml 
    • text/json 
    • text/xml

Request parameters

Parameter Parameter Type Data Type Mandatory
page Path String Yes
uniqueId Query String Yes
  • page – Specifies the path to a portal grid page, data on which will be deleted. For example: /en-us/orders/all.
  • uniqueId – Specifies the unique ID of a record that will be deleted. 

Request body

The request body is not required for this method.

POST: /api/1.0/Entities/Sync/Store 

This operation updates multiple records of an entity specified in the query.

  Note

To use this method, the Allow multiple records synchronization methods setting must be enabled for the API client and the member.

HTTP request 

POST https://<Your Portal Name>/api/1.0/Entities/Sync/Store 

Request headers

Header Parameter Type Data Type Mandatory
сlient_id Header String Yes
accept Header String No
  • client_id – Specifies the ID of a registered client. This ID is required to test connection and verify API configuration.
  • accept – Specifies the type of response content type. To use response directly in browsers, the application/json content type is recommended. Available content types: 
    • application/json 
    • application/xml 
    • text/json 
    • text/xml 

Request parameters

This method does not have request parameters.

Request body

{
  "Items": [
    {
      "TriggerType": 0,
      "CompanyName": "string",
      "Entity": "string",
      "UniqueId": "string",
      "Fields": [
        {
          "Name": "string",
          "StringValue": "string",
          "Type": "string",
          "Modified": true
        }
      ]
    }
  ]
}
  • TriggerType – Specify the type of operation: ['0', '1', '2',] where 0 = Insert, 1 = Delete, and 2 = Modify.
  • CompanyName - Specify the name of the company where data will be updated.
  • Entity - Specify the entity where data will be updated.
  • UniqueId - Specify the ID of the record where data will be updated. 
  • Fields - Specify the field and field value that will be modified. 

 

POST: /api/1.0/Entities/Sync/Get

This operation returns records of an entity based on the specified query.

 

  Note

To use this method, the Allow multiple records synchronization methods setting must be enabled for the API client and the member.

HTTP request 

POST https://<Your Portal Name>/api/1.0/Entities/Sync/Get

Request headers

Header Parameter Type Data Type Mandatory
сlient_id Header String Yes
accept Header String No
  • client_id – Specifies the ID of a registered client. This ID is required to test connection and verify API configuration.
  • accept – Specifies the type of response content type. To use response directly in browsers, the application/json content type is recommended. Available content types: 
    • application/json 
    • application/xml 
    • text/json 
    • text/xml 

Request parameters

This method does not have request parameters.

Request body

{
  "Entity": "string",
  "CompanyName": "string",
  "Keywords": "string",
  "Paging": {
    "Index": 0,
    "Size": 0
  },
  "Sort": [
    {
      "Name": "string",
      "Dir": "string",
      "Reverce": true
    }
  ],
  "Filters": [
    {
      "Logic": "string",
      "GroupName": "string",
      "Filters": [
        {
          "Field": "string",
          "Operator": "string",
          "Value": "string",
          "Logic": "string",
          "Type": "string"
        }
      ]
    }
  ]
}

This query defines the entity the records of which will be returned. You can add strings to sort data, set filters, etc. See the model for information on the parameters that you can specify.

To learn more, see the following topics: