Work with Customer Insights - Data APIs

Dynamics 365 Customer Insights - Data provides APIs to build your own applications based on your data in Customer Insights. Details of these APIs are listed on the API reference. They include additional information about operations, parameters, and responses.

Note

Customer Insights - Data tables can also be accessed using Dataverse APIs. We recommend you use Dataverse APIs to query Customer Insights data as they offer more extensive filtering, greater throughput, and lower latency. For more information, see Dataverse APIs for Customer Insights.

Get started trying the APIs

An admin must enable API access to your data. Once access is enabled, any user can use API with the subscription key.

1. Sign in to Customer Insights - Data or sign up for a trial of Customer Insights.

2. Go to Settings > Permissions and select the APIs tab.

3. If API access to the environment has not been set up, select Enable.

   Enabling the APIs creates a primary and secondary subscription key for your environment that gets used in the API requests. To regenerate the keys, select the Regenerate primary or Regenerate secondary on the APIs tab.

4. Select Explore our APIs to try out the APIs.

5. Search for and select an API operation and select Try it.

   

6. In the side pane, set the value in the Authorization dropdown menu to implicit. The Authorization header gets added with a bearer token. Your subscription key is automatically populated.

7. Optionally, add all necessary query parameters.

8. Scroll to the bottom of the side pane and select Send.

   The HTTP response displays at the bottom of the pane.

Create a new app registration in the Azure portal

Create a new app registration to use the APIs in an Azure application using delegated permissions.

1. Complete the Getting started section.

2. Sign in to the Azure portal with the account that can access the Customer Insights data.

3. Search for and then select App registrations.

4. Select New registration, provide an application name and choose the account type.

   Optionally, add a redirect URL. http://localhost is sufficient for developing an application on your local computer.

5. Select Register.

6. On your new App registration, go to API permissions.

7. Select Add a permission and select Dynamics 365 AI for Customer Insights in the side pane.

8. For Permission type, select Delegated permissions and then select the user_impersonation permission.

9. Select Add permissions.

10. Select Grant admin consent for... to complete the app registration.

11. To access the API without a user signing in, go to Set server-to-server application permissions.

You can use the Application/Client ID for this app registration with the Microsoft Authentication Library (MSAL) to obtain a bearer token to send with your request to the API.

For information on using the APIs in our client libraries, see Customer Insights client libraries.

Set server-to-server application permissions

Create an app registration that doesn't need user interaction and can be run on a server.

1. On your App registration in the Azure portal, go to API permissions.

2. Select Add a permission.

3. Select the APIs my organization uses tab and choose Dynamics 365 AI for Customer Insights from the list.

4. For Permission type, select Application permissions and then select the api.access permission.

5. Select Add permissions.

6. Go back to API permissions for your app registration.

7. Select Grant admin consent for... to complete the app registration.

8. Add the name of the app registration as a user in Customer Insights - Data.

   1. Open Customer Insights - Data, go to Settings > Permissions and select Add users.

   2. Search for the name of your app registration, select it from the search results, and select Save.

Sample queries

For a short list of OData sample queries to work with the APIs, see OData query examples.

Customer Insights client libraries

Get started using the client libraries available for the Customer Insights - Data APIs. All library source code and sample applications can be found on a GitHub repo.

C# NuGet

Use the C# client libraries from NuGet.org. Currently, the package targets the netstandard2.0 and netcoreapp2.0 frameworks. For more information on the NuGet package, see Microsoft.Dynamics.CustomerInsights.Api.

Add the C# client library to a C# project

1. In Visual Studio, open the NuGet Package Manager for your project.

2. Search for Microsoft.Dynamics.CustomerInsights.Api.

3. Select Install to add the package to the project.

   Alternatively, run this command in the NuGet Package Manager Console: Install-Package -Id Microsoft.Dynamics.CustomerInsights.Api -Source nuget.org -ProjectName <project name> [-Version <version>]

Use the C# client library

1. Use the Microsoft Authentication Library (MSAL) to get an AccessToken using your existing Azure app registration.

2. After successfully authenticating and acquiring a token, construct a new or use an existing HttpClient with the DefaultRequestHeaders "Authorization" set to Bearer "access token" and Ocp-Apim-Subscription-Key set to the subscription key from your Customer Insights - Data environment.

   Reset the Authorization header when appropriate. For example, when the token expired.

3. Pass this HttpClient into the construction of the CustomerInsights client.

4. Make calls with the client to the "extension methods", for example, GetAllInstancesAsync. If access to the underlying Microsoft.Rest.HttpOperationResponse is preferred, use the "http message methods", for example, GetAllInstancesWithHttpMessagesAsync.

5. The response is likely object type because the method can return multiple types (for example, IList<InstanceInfo> and ApiErrorResult). To check the return type, use the objects in the response types specified on the API details page for that operation.

   If more information on the request is needed, use the http message methods to access the raw response object.

NodeJS package

Use the NodeJS client libraries available through NPM: https://www.npmjs.com/package/@microsoft/customerinsights

Python package

Use the Python client libraries available through PyPi: https://pypi.org/project/customerinsights/