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 – 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 – 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 – 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
{ |
- 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
{ |
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: