Microsoft Dynamics endpoints and permissions

This article provides an overview of the key endpoints, their purposes, required permissions, and data fields involved in integrating Influ2 with Microsoft Dynamics.

1. Authentication and Authorization

Endpoint: https://login.microsoftonline.com
Purpose: Handles the OAuth authentication process to obtain an access token for accessing Microsoft Dynamics APIs.

Fields Used:

  • client_id (string): Identifies the application.
  • client_secret (string): Secret key for authenticating the application.
  • scope (string): The requested permissions.
  • code (string): Authorization code from the OAuth flow.
  • grant_type (string): Grant type (e.g., authorization_code).
  • redirect_uri (string): Callback URL where the authorization server redirects the user.

Permissions Required:

Access to an Azure AD app with appropriate Dynamics scopes (e.g., user_impersonation).

Frequency:

Executed during OAuth connection establishment or refresh.

2. User Information Retrieval

a. Fetch User Details

Endpoint: api/data/v9.2/systemusers
Purpose: Fetch detailed information about a specific user.

Fields Collected:

  • UserID (string): Unique identifier of the user.
  • Other attributes based on the API response.

Permissions Required: API access to read user information in Dynamics (systemusers entity).

Frequency: As needed.

b. Identify Current User

Endpoint: api/data/v9.2/WhoAmI
Purpose: Retrieves the User ID of the authenticated user.

Fields Collected:

  • UserID (string): Unique identifier of the current user.

Permissions Required: API access to the WhoAmI endpoint.

Frequency: Typically executed during initialization.

3. Company Search

Endpoint: api/data/v9.2/accounts
Purpose: Searches for companies in Dynamics using filters.

Fields Collected:

  • ID (string): Company’s unique identifier.
  • CompanyID (string): External identifier.
  • Name (string): Company name.
  • Website (string): Website URL.
  • Industry (string): Industry classification.
  • OwnerID (string): Owner’s ID.
  • CreatedAt (timestamp): Record creation date.
  • UpdatedAt (timestamp): Last update date.

Permissions Required: Access to the accounts entity in Microsoft Dynamics.

Frequency: As needed.

4. Contact and Leads Search

Endpoints:

  • Contacts: api/data/v9.2/contacts
  • Leads: api/data/v9.2/leads

Purpose: Retrieve contact or lead details using filters.

Fields Collected:

  • ID: Unique identifier.
  • FirstName / LastName: Name details.
  • Email: Email address.
  • Title: Job title.
  • City / Country: Location.
  • Phone / MobilePhone: Contact numbers.
  • Linkedin: LinkedIn profile URL.
  • PhotoURL: Photo URL.
  • AccountName / AccountID: Associated account details.
  • OwnerID: Owner's ID.
  • CreatedAt / UpdatedAt: Record timestamps.

Permissions Required: Access to contacts and leads entities and FetchXML permissions for advanced queries.

Frequency: Regularly for synchronization.

5. Metadata Retrieval

Endpoints:

  • Entity Fields: api/data/v9.2/EntityDefinitions/LogicalName/Attributes
  • Picklist: api/data/v9.2/PicklistAttributeMetadata

Purpose: Retrieve metadata about entities and dropdown values.

Fields Collected:

  • Label: Human-readable name.
  • Type: Data type (e.g., string, number).
  • IsValidForUpdate: Indicates updatability.
  • Picklist: ID and value of dropdown options.

Permissions Required: Access to EntityDefinitions and PicklistAttributeMetadata.

Frequency: As needed.

6. List Members

Endpoint: GET api/data/v9.2/listmembers
Purpose: Retrieve members of specific lists.

Fields Collected:

  • EntityIDValue: Related entity’s ID.
  • EntityType: Type of entity (contact, lead, account).
  • ListID: Associated list’s ID.

Permissions Required: Read access to list members.

Frequency: As needed.

7. Get Lists

Endpoint: GET api/data/v9.2/lists
Purpose: Retrieve audience or marketing lists based on filters.

Fields Collected:

  • ID: List ID.
  • Name: List name.
  • IsActive: Status.
  • Type: List type.
  • MemberType: Member classification.
  • IsSelected: Selection status.
  • IsDeleted: Deletion status.
  • Query: Filters used.
  • CreatedAt: Timestamp.

Permissions Required: Read access to lists.

Frequency: As needed.

8. Get Owners

Endpoint: GET api/data/v9.2/systemusers
Purpose: Retrieve system user information.

Fields Collected:

  • SystemUserID: Unique user ID.
  • FirstName / LastName / FullName: Name details.
  • InternalEmailAddress: Email address.
  • IsDisabled: Status.
  • CreatedAt / UpdatedAt: Timestamps.

Permissions Required: Read access to user records.

Frequency: As needed.