5.5 Custom API Messages & Plug-ins That Implement a Custom API

Every plug-in covered so far has hooked into a message Dataverse already defines -- Create, Update, Delete. A Custom API lets you define a message of your own: a new, strongly-typed operation with its own name, its own request parameters, and its own response, callable through the Web API or the Organization service exactly like a built-in message, without writing a classic workflow-based custom action.

What a Custom API Is

A Custom API is configured declaratively, as data -- a Custom API record plus its Custom API Request Parameter and Custom API Response Property child records -- typically authored in a solution through the maker portal's Custom API designer rather than hand-written SDK metadata calls. Key properties on the Custom API record:

Request and response parameters each declare a Name and a Type drawn from the standard SDK type set -- String, Integer, Boolean, DateTime, Decimal, Float, Money, Entity, EntityCollection, EntityReference, Picklist, StringArray, Guid -- giving the message a real, discoverable contract rather than a loosely typed bag of values.

Calling a Custom API

Once published, a Custom API is callable exactly like a built-in message:

• Web API: POST https://org.crm.dynamics.com/api/data/v9.2/new_CalculateShippingCost for an unbound (Global) action, or .../accounts(id)/Microsoft.Dynamics.CRM.new_ApproveAccount for a bound one. A function, bound or unbound, is called with GET instead.
• Organization service: build an OrganizationRequest("new_CalculateShippingCost"), populate its Parameters collection with the declared request parameters, and call service.Execute(request) -- the same pattern used for any SDK message.

The Implementing Plug-in

Unlike a normal step, you don't separately register the plugin type against the message in the Plug-in Registration Tool -- publishing the Custom API record with its Plugin Type set does that automatically. Inside the plugin, the pattern mirrors any other Execute method, but the developer reads each declared request parameter from InputParameters by name and writes each declared response property to OutputParameters by name:

public void Execute(IServiceProvider serviceProvider)
{
    IPluginExecutionContext context =
        (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

    var accountId = (Guid)context.InputParameters["AccountId"];
    var orderTotal = ((Money)context.InputParameters["OrderTotal"]).Value;

    decimal shippingCost = CalculateShipping(orderTotal);

    context.OutputParameters["ShippingCost"] = new Money(shippingCost);
}

Because the request and response shape is declared on the Custom API record itself, both the Web API's $metadata and SDK tooling can describe the operation's contract to callers automatically -- a JavaScript form script (4.3) or a Power Automate flow can discover and call it like any native message.

Custom API vs. Custom Process Action vs. a Plain Plug-in Step

Two comparisons the exam likes to draw:

Custom API vs. classic Custom Process Action. A Custom Process Action, sometimes called a "classic Action," is defined through the legacy process/workflow designer, stored as a workflow definition, and executed through the workflow engine -- heavier weight, and largely a legacy pattern Microsoft has superseded. A Custom API is code-first, lightweight, natively exposed through the Web API without a workflow-engine dependency, and is the recommended approach for new development.

Custom API vs. a plug-in on a standard message. A plug-in step registered on Update subscribes to something that already happens as a side effect of ordinary data entry -- it can't be invoked deliberately on its own. A Custom API instead creates a brand-new, intentionally invoked operation with its own name and contract: use one whenever the requirement is "let a caller explicitly ask the platform to do X," such as approve a record, calculate a value, or kick off a process, rather than "react whenever a record changes." Design-wise, this is the same distinction Domain 1's technical-design guidance draws around code components (1.5): a Custom API is the modern building block for exposing custom server-side logic as its own first-class, callable operation.