Work with Customer Insights APIs

Dynamics 365 Customer Insights provides APIs to build your own applications based on your data in Customer Insights.

Important

Details of these APIs are listed on the Customer Insights APIs reference. They include additional information about operations, parameters, and responses.

This article describes how to access the Customer Insights APIs, create an Azure App Registration, and get started with client libraries.

Get started trying the Customer Insights APIs

  1. Sign in to Customer Insights. If you don't have a subscription yet, sign up for a trial of Customer Insights.

  2. To enable APIs on your Customer Insights environment, go to Admin > Security. You'll need admin permissions to do so.

  3. Go to the APIs tab and select the Enable button.

    Enabling the APIs creates a primary and secondary subscription key for your instance that gets used in the API requests. You can regenerate the keys by selecting the Regenerate primary or Regenerate secondary on Admin > Security > APIs.

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

  2. Choose an API operation and select Try it.

  3. 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 will be automatically populated.

  4. Optionally, add all necessary query parameters.

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

The HTTP response will soon appear below.

Create a new app registration in the Azure portal

These steps help you get started with using the Customer Insights APIs in an Azure application using delegated permissions. Make sure to complete the Getting started section first.

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

  2. On the left, select App registrations.

  3. 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.

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

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

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

  7. Select Add permissions. If you need to access the API without a user signing in, review the Server-to-server application permissions section.

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

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 more information about MSAL, see Overview of Microsoft Authentication Library (MSAL).

For more information about app registration in Azure, see Register an application.

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

Server-to-server application permissions

The app registration section outlines how to register an app that requires a user to sign in for authentication. Learn how to 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 CustomerInsights.Api.All 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.

  1. To conclude, we have to add the name of the app registration as a user in Customer Insights.

    Open Customer Insights, go to Admin > Security and select Add user.

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

Sample queries

We've compiled a short list of OData sample queries to work with the APIs: OData query examples.

Customer Insights client libraries

This section helps you get started using the client libraries available for the Customer Insights APIs. All library source code and sample applications can be found on the Customer Insights GitHub page.

C# NuGet

Learn how to get started using the C# client libraries from NuGet.org. For more information on the NuGet package, see Microsoft.Dynamics.CustomerInsights.Api. Currently, this package targets the netstandard2.0 and netcoreapp2.0 frameworks.

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 environment.

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

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

  1. 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.

  2. The response will likely be of type object because the method can return multiple types (for example, IList<InstanceInfo> and ApiErrorResult). To check the return type, you 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/