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. You can find details about these APIs in the API reference, which includes information about operations, parameters, and responses.

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 isn't set up, select Enable.

   When you enable the APIs, you create a primary and secondary subscription key for your environment that you use in the API requests. To regenerate the keys, select 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 automatically populates.

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 by 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 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. You can find all library source code and sample applications 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 about 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 by using your existing Azure app registration.

2. After you authenticate and acquire a token, construct a new HttpClient or use an existing one. Set the DefaultRequestHeaders "Authorization" to Bearer "access token" and set Ocp-Apim-Subscription-Key to the subscription key from your Customer Insights - Data environment.

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

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 you prefer access to the underlying Microsoft.Rest.HttpOperationResponse, 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 you need more information about the request, use the http message methods to access the raw response object.

Node.js package

Use the Node.js 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/