Create a Custom API using the plug-in registration tool

The plug-in registration tool (PRT) includes a designer to create Custom API. The PRT is a Windows client application that is part of the developer tools you can download from NuGet. See Dataverse development tools for information about downloading these tools.

Connect using the Plug-in Registration tool

  1. After you have downloaded the Plug-in registration tool, click the PluginRegistration.exe to open it.

  2. Click Create new Connection to connect to your instance.

  3. Make sure Office 365 is selected.

  4. If you are connecting using a Microsoft account other than one you are currently using, click Show Advanced and enter your credentials. Otherwise, leave Sign-in as current user selected.

  5. If your Microsoft Account provides access to multiple environments, select Display list of available organizations.

    Logging in with the Plug-in registration tool.

  6. Click Login.

  7. If you selected Display list of available organizations, select the organization you would like to connect to and click Login.

  8. After you are connected, you will see any existing registered plug-ins, custom workflow activities and data providers.

    View existing plug-ins an custom workflow activities.

Create a Custom API

In the Register menu, select the Register new Custom API command. This will open the form to create a Custom API.

PRT Custom API form

Use the information in the table below to create the Custom API. For more details, see Custom API table columns

Important

Some options cannot be changed after you save the Custom API. Make sure you understand the purpose of each setting that cannot be changed. If you later need to change this setting, you must delete and re-create the Custom API. This will also delete any request parameters or response properties that are associated with it.

Label Description Can be changed
Display Name A localizable name. Yes
Name A friendly, non-localizable name. Yes
Solution Create a new solution or select an existing one. Setting this value will set the appropriate customization prefix for the Unique Name field. Yes
Unique Name The name of the Custom API. This value should contain only alphanumeric characters and no spaces.
The full name includes the customization prefix determined by selecting the solution.
No
Description A localizable description. For use when the message is exposed to be called in an app. For example, as a ToolTip. Yes
Assembly Optional. Select an assembly that contains a plug-in type that will define what the Custom API does. Yes
Plugin Optional. Select a plug-in type within the selected assembly. You may set this later. Yes
Allowed Custom Processing Step Type Which types of processing steps you will allow. More Information: Select a Custom Processing Step Type No
Binding Type What kind of entity binding. More Information: Select a Binding Type No
Bound Entity Logical Name If you select Binding Type Entity or EntityCollection you should enter the logical name of the table representing that type. No
Execute Privilege Name The name of a privilege that will control whether someone can use the API. This must be a valid Name value from the Privilege table. More information: Secure your Custom API with a privilege Yes
Function Whether to create a Function. More Information: When to create a Function No
Private Whether the Custom API should be private. More Information: When to make your Custom API private Yes

Note

  • The PRT Custom API designer doesn't expose the Enabled For Workflow (WorkflowSdkStepEnabled) property. If you want to create a Custom API that will work for Workflows, you need to use a different method.
  • The PRT Custom API designer doesn't expose the Is Customizable managed property. You can set this in Power Apps. More information Custom API Customization

You can continue to add Request Parameters and Response Properties, or save the Custom API and add them later.

Create Request parameters

A Custom API isn't required to have any request parameters. While creating a Custom API or when editing an existing one, you can create new request parameters by clicking + Add Request Parameter. This will open the Parameter form.

Custom API Request Parameter Create form

Use the information in the table below to create the Request Parameter. For more details see CustomAPIRequestParameter Table Columns

Label Description Can be changed
Display Name Localizable display name. Yes
Name The primary name of the custom API request parameter. This naming convention is recommended to differentiate this parameter from others that share a common Unique Name: {Custom API Unique Name}.{Parameter UniqueName} Yes
Unique Name This will be the name of the parameter when you call the Custom API. No
Type Select the type of the parameter.
Boolean
DateTime
Decimal
Entity
EntityCollection
EntityReference
Float
Integer
Money
Picklist
String
StringArray
Guid
No
Logical Entity Name When Entity, EntityCollection, or EntityReference is selected as the Type, you can specify the table. No
Description Localizable description. Yes
Is Optional Whether a value for the parameter is required by the caller. No

Create Response properties

A Custom API for an action isn't required to have any response properties. While creating a Custom API or when editing an existing one, you can create new response properties by clicking + Add Response Parameter. This will open the Parameter form.

Custom API Response Property Create form

Use the information in the table below to create the Response Property. For more details see CustomAPIResponseProperty Table Columns

Label Description Can be changed
Display Name Localizable display name. Yes
Name The primary name of the custom API response property. This naming convention is recommended to differentiate this parameter from others that share a common Unique Name: {Custom API Unique Name}.{Property UniqueName} Yes
Unique Name This will be the name of the property returned when you call the Custom API. No
Type Select the type of the property.
Boolean
DateTime
Decimal
Entity
EntityCollection
EntityReference
Float
Integer
Money
Picklist
String
StringArray
Guid
No
Logical Entity Name When Entity or EntityReference are selected as the Type, you can specify the table. You cannot specify a Logical Entity Name when you choose EntityCollection as the Type. No
Description Localizable description. Yes

View a list of Custom API

To view a list of Custom API, from the View menu select the Display by Message command.

The Display by Message command will show Custom API

Any messages that were created as Custom API will be prefixed by (Custom API).

Delete Custom API

When viewing a list of Custom API, select the one you want to delete and click the Unregister command.

Delete a Custom API

Or right-click the item and select Unregister from the context menu.

Update Custom API Request Parameters or Response Properties

In the list of Request parameters or Response properties, select this column to edit:

Column to edit parameter

Delete Custom API Request Parameters or Response Properties

In the list of Request parameters or Response properties, select this column to delete:

Column to delete parameter

Next steps

If you haven't set the IsPrivate property for your Custom API, after you have created your Custom API you can retrieve the service definition from the CSDL $metadata document using a GET request, even from your browser. If the url for your environment is https://yourorg.crm.dynamics.com, you can type this URL in your browser address field to retrieve the $metadata: https://yourorg.crm.dynamics.com/api/data/v9.1/$metadata.

Search the result to find the name of the Custom API and you will find the Action or Function created together with any related ComplexType to represent the return value. For example:

<ComplexType Name="sample_CustomAPIExampleResponse">
    <Property Name="StringProperty"
        Type="Edm.String"
        Unicode="false"/>
</ComplexType>
<Action Name="sample_CustomAPIExample">
    <Parameter Name="StringParameter"
        Type="Edm.String"
        Nullable="false"
        Unicode="false"/>
    <ReturnType Type="mscrm.sample_CustomAPIExampleResponse"
        Nullable="false"/>
</Action>

Even if you haven't set a Plugin for your Custom API, you can test it to verify the signature. Any response properties will return their default values because there is no plug-in to set the values. More information: Invoking Custom APIs

If you will add a plug-in, you must write it and register the assembly. Then update your Custom API to set the Assembly and Plugin to specify what code to run in response to your Custom API. More information: Write a Plug-in for your Custom API

See also

Create and use Custom APIs
Create a Custom API in Power Apps
Create a Custom API with code
Create a Custom API with solution files
Create your own messages
Custom API table columns