Portals Web API overview

The portals Web API enables a richer user experience inside Power Pages sites. You can use the Web API to perform create, read, update, and delete operations across all Microsoft Dataverse tables from your webpages. For example, you can create a new account, update a contact, without using a form or multistep form by using the portals Web API.

Important

  • Your Power Pages site version must be 9.3.3.x or later for this feature to work.
  • The portals Web API is built for creating a rich user experience inside portal pages. It isn't optimized for third-party services or application integration. Using the portals Web API to integrate with other Power Pages sites is also not supported.
  • Portals Web API operations are limited to tables related to data—for example, accounts, contacts, or your custom tables. Configuring table metadata or portal configuration table data—for example, configuring portals tables such as adx_contentsnippet, adx_entityform, or adx_entitylist—isn't supported with the portals Web API. For a complete list, go to unsupported configuration tables later in this topic.
  • The portals Web API benefits from server-side caching, so subsequent calls to the Web API are faster than the initial calls. Note that clearing the portal server-side cache causes temporary performance degradation.
  • Portals Web API operations require a Power Pages license. For example, Web API calls made by anonymous users are counted towards the anonymous user capacity. Web API calls made by authenticated users (internal or external) are not counted towards page views, but require applicable authenticated user capacity licenses. More information: Power Pages licensing FAQs

Web API operations

The portals Web API offers a subset of capabilities for Dataverse operations that you can do by using the Dataverse API. We've kept the API format as similar as possible to reduce the learning curve.

Note

Web API operations are case-sensitive.

Web API operations available in Power Pages

Note

Calling actions and functions using the portals Web API is not supported.

Site settings for the Web API

You must enable the site setting to enable the portals Web API for your portal. You can also configure the field-level Web API that determines the table fields that can or can't be modified with the portals Web API.

Note

Use the table logical name for these settings (for example account).

Site setting name Description
Webapi/<table name>/enabled Enables or disables the Web API for <table name>.
Default: False
Valid values: True, False
Webapi/<table name>/fields Defines the comma-separated list of attributes that can be modified with the Web API.
Possible values:
- All attributes: *
- Specific attributes: attr1,attr2,attr3
Note: The value must be either an asterisk (*) or a comma-separated list of field names.
Important: This is a mandatory site setting. When this setting is missing, you'll see the error "No fields defined for this entity."
Webapi/error/innererror Enables or disables InnerError.
Default: False
Valid values: True, False
Webapi/<table name>/disableodatafilter Enables or disables the OData filter.
Default: False
Valid values: True, False See known issues for more information. The site setting is available in portal version 9.4.10.74 or later.

Note

Site settings must be set to Active for changes to take effect.

For example, to expose the Web API for the Case table where authenticated users are allowed to perform create, update, and delete operations on this entity, the site settings are shown in the following table.

Site setting name Site setting value
Webapi/incident/enabled true
Webapi/incident/fields attr1, attr2, attr3

Security with the portals Web API

You can configure record-based security to individual records in portals by using table permissions. The portals Web API accesses table (entity) records and follows the table permissions given to users through the associated web role.

You can configure column permissions to further define privileges to individual columns within a table while using the portals Web API.

Authenticating portals Web API requests

You don't need to include an authentication code, because authentication and authorization are managed by the application session. All Web API calls must include a Cross-Site Request Forgery (CSRF) token.

Using EntitySetName

When referring to Dataverse tables using the portals Web API in your code, you need to use the EntitySetName, for example, to access the account table, the code syntax will use the EntitySetName of accounts; /_api/accounts().

Note

Use the table logical name for site settings (for example, account).

You can determine the EntitySetName of specific tables by following these steps:

  1. Go to https://make.powerapps.com

  2. Select the Dataverse tab from the side panel and select the table.

  3. Select the ... (Commands option) and then choose Advanced, Tools, and Copy set name to copy the EntitySetName of the table to your clipboard.

    How to locate EntitySetName of a Dataverse table.

Privacy laws and regulations

All request headers will have a contact ID passed for auditing purposes. For an anonymous user, this will be passed as null.

If audit logging is enabled, a user can see all the audit events in the Office 365 audit log.

Office 365 audit log..

More information:
Enable and use activity logging
Export, configure, and view audit log records

Unsupported configuration tables

Portals Web API can't be used for the following configuration tables:

adx_contentaccesslevel

adx_contentsnippet

adx_entityform

adx_entityformmetadata

adx_entitylist

adx_entitypermission

adx_entitypermission_webrole

adx_externalidentity

adx_pagealert

adx_pagenotification

adx_pagetag

adx_pagetag_webpage

adx_pagetemplate

adx_portallanguage

adx_publishingstate

adx_publishingstatetransitionrule

adx_publishingstatetransitionrule_webrole

adx_redirect

adx_setting

adx_shortcut

adx_sitemarker

adx_sitesetting

adx_urlhistory

adx_webfile

adx_webfilelog

adx_webform

adx_webformmetadata

adx_webformsession

adx_webformstep

adx_weblink

adx_weblinkset

adx_webnotificationentity

adx_webnotificationurl

adx_webpage

adx_webpage_tag

adx_webpageaccesscontrolrule

adx_webpageaccesscontrolrule_webrole

adx_webpagehistory

adx_webpagelog

adx_webrole_systemuser

adx_website

adx_website_list

adx_website_sponsor

adx_websiteaccess

adx_websiteaccess_webrole

adx_websitebinding

adx_websitelanguage

adx_webtemplate

Known issues

Users will get a CDS error if they invoke a GET Web API request for tables that have multiple levels of 1 to many or many to many table permissions when Parental, Contact or Account scopes add additional conditions to the query.

To resolve this issue, the recommended solution is to use FetchXML in the OData query.

Alternatively, set the site setting Webapi/<table name>/disableodatafilter to True.

Important

Changing the site setting Webapi/<table name>/disableodatafilter to True may result in slower performance for Web API GET calls.

The site setting is available in portal version 9.4.10.74 or later.

Next step

Query data using portals Web API

See also