Step-by-Step Guide to Building Custom APIs in Dataverse

Custom APIs in Microsoft Dataverse allow developers and architects to create their own reusable, secure, and well-defined service endpoints that extend the standard Dataverse Web API. Instead of relying solely on out-of-the-box messages (like Create, Update, or Retrieve), Custom APIs let you define your own business operations — complete with input and output parameters — that encapsulate complex logic and can be called from Power Automate, Power Apps, or external systems. These APIs are registered once and behave like native Dataverse operations, making them ideal for implementing domain-specific logic, integrating with external services, or simplifying client-side development.

From a technical standpoint, a Custom API can be implemented through a plugin class, where the backend logic is written in C#. Developers can control security through privilege definitions and ensure consistency by centralizing key business rules. Custom APIs are particularly valuable in enterprise environments where modularity, performance, and scalability are essential — offering a clean, service-oriented alternative to using multiple plugin steps or custom workflow activities.  

As a developer working with Microsoft Dataverse, you’ve likely built Plugins, Workflows, or Actions. But have you explored Custom APIs?

Custom APIs provide a clean, reusable, and secure way to expose your business logic to other Dataverse components and even external systems.

In this blog, we’ll dive into the core components of a Custom API, their technical implementation, and provide a step-by-step guide to building one from scratch.

Why Should Developers Care About Custom APIs?

• Reusable Logic – Call your API from Power Automate, Canvas Apps, or external clients.
• Security-Controlled – Follows Dataverse security model.
• Supports Complex Business Rules – Ideal for logic that goes beyond simple CRUD operations.
• Externally Accessible – Available via Web API endpoints.

Core Components of a Custom API (Deep Dive)

Before building, understand what makes up a Custom API:

Custom API Definition

This is the blueprint that defines:

• Name: Unique logical name (e.g., `new_CalculateDiscountAPI`)
• Type: Bound (tied to entity) or Unbound (global)

Allowed HTTP Verb: POST

Action or Function:

• Action → modifies data
• Function → read-only

Developer Tip: Keep it Unbound for APIs serving multiple entities.

Request Parameters

These are the inputs your API expects.

Developer Tip: Always validate parameters in your Plugin code for null or invalid data.

Response Properties

These are the outputs your API returns.

Plugin (C# Business Logic)

Your API will execute a Plugin written in C#.

 Access Input Parameters:

var customerId = (EntityReference)context.InputParameters["CustomerId"];

Set Output Parameters:

context.OutputParameters["DiscountPercentage"] = calculatedValue;

Best Practices:

• Use early-bound entities for type safety
• Keep transactions atomic
• Handle exceptions gracefully with `InvalidPluginExecutionException`

Security Roles

• Controls who can execute your API.
• Assign privileges to roles within Dataverse.

Developer Tip: Don’t forget this step – without it, even admins may get “insufficient privilege” errors.

Invoker (Consumers)

Once created, your API can be called from:

•  Power Automate
•  Canvas Apps
•  Model-driven Apps
•  External systems (via Postman or custom HTTP clients)

Step-by-Step Guide: Building a Custom API

Step 1: Create Custom API

1. Go to Power Apps > Solutions > + New > Custom API.

2. Fill in:

• Name: `new_CalculateDiscountAPI`
• Binding: Unbound
• Type: Action

3. Save & Publish.

Step 2: Add Request Parameters

1. Navigate to Custom API Request Parameters > + New.

2. Define inputs like `CustomerId (EntityReference)` and `OrderAmount (Decimal)`.

3. Save & Publish.

Step 3: Add Response Properties

1. Go to Custom API Response Properties > + New.

2. Define output like `DiscountPercentage (Decimal)`.

3. Save & Publish.

Step 4: Write the Plugin Code

Register a Plugin step for your API:

public void Execute(IServiceProvider serviceProvider)

var context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

Step 5: Register Plugin

Use Plugin Registration Tool:

•  Register assembly
•  Register step on your Custom API

Step 6: Test Your API

Test in:

• Power Automate (Call Custom API action)
• Canvas App (Patch with API call)
• Postman (Using Web API endpoint `/api/data/v9.1/new_CalculateDiscountAPI`)

Best Practices for Developers

• Keep business logic inside Plugin – keep API layer thin
• Validate all inputs
• Use Dependency Injection for external dependencies
• Secure APIs via role-based access
• Document API contracts (inputs/outputs)

Key Takeaways

•  Custom APIs allow clean, reusable, and secure business logic.
•  They are developer-friendly for complex integrations.
•  They are accessible across Power Platform and external apps.