Action Configuration

Actions define the operations available for each entity. API Builder supports seven action types:

Action Type	HTTP Method	Description
Create	POST	Create new records
Update	PUT	Modify existing records
Read	GET	Retrieve a single record by ID
Delete	DELETE	Remove records
Upload	POST	Upload files/attachments
Download	GET	Download files/attachments
Process	POST	Execute custom actions

Route structure

Each action's route is /{module}/{entity-logical-name}/{endpoint-name} (create/process) or /{module}/{entity-logical-name}/{id}/{endpoint-name} (read/update/delete/upload/download), lowercased. There is no built-in /api/ prefix — any prefix comes from how you host the app. See Entities → Generated API Endpoints.

Common Action Components

All actions share these configuration components:

Definition

Property	Required	Description
Endpoint Name	Yes	The URL path segment for this action

Documentation

Property	Required	Description
Title	Yes	Short, descriptive name for the action
Description	No	Detailed explanation of what the action does

Inputs

Inputs define the parameters accepted by the API endpoint.

Property	Description
Name	Parameter identifier
Type	Data type (String, Integer, Money, DateTime, Entity Reference, etc.)
Required	Whether the parameter must be provided
Default Value	Value used if parameter is not provided
Validation	Validation rules (min/max, pattern, etc.)
Description	Documentation for API consumers

Data Fetcher

The Data Fetcher allows you to execute queries before the main action. This is useful when the action depends on data that must be retrieved first.

Property	Description
Query Name	Identifier for referencing the fetched data
Query Definition	The query to execute (can reference inputs)
Result Variable	Variable name to store the query result

Use Cases for Data Fetcher:

Validate that a referenced record exists
Retrieve default values from a related record
Check business rules against existing data
Fetch configuration values needed for the action

Access Control

See Access Control for complete details on Authorization Policy and Pre-conditions.

Create Action

The Create Action exposes an endpoint for creating new records of the entity.

Create Action Structure

┌──────────────────────────────────────────────────────────────────────┐
│                      CREATE ACTION STRUCTURE                         │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐     │
│  │ DEFINITION                                                   │    │
│  │   • Endpoint Name (URL path)                                │     │
│  └─────────────────────────────────────────────────────────────┘     │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐     │
│  │ DOCUMENTATION                                                │    │
│  │   • Title                                                    │    │
│  │   • Description                                              │    │
│  └─────────────────────────────────────────────────────────────┘     │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐     │
│  │ INPUTS                                                       │    │
│  │   • Input parameters from API request                        │    │
│  └─────────────────────────────────────────────────────────────┘     │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐     │
│  │ DATA FETCHER                                                 │    │
│  │   • Pre-fetch queries for dependent data                     │    │
│  └─────────────────────────────────────────────────────────────┘     │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐     │
│  │ ACCESS CONTROL                                               │    │
│  │   • Authorization Policy                                     │    │
│  │   • Pre-conditions                                           │    │
│  └─────────────────────────────────────────────────────────────┘     │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐     │
│  │ ENTITY PROPERTIES                                            │    │
│  │   • Field bindings with inputs                               │    │
│  └─────────────────────────────────────────────────────────────┘     │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

Entity Properties

Entity Properties define how inputs map to the Dataverse entity fields when creating the record.

Property	Description
Entity Field	The Dataverse field name
Binding	The input parameter, fetched data, or expression to use
Transform	Optional transformation applied before saving

API Request Example

POST /sales/account/create
Content-Type: application/json
Authorization: Bearer {token}

{
  "name": "Contoso Ltd",
  "email": "info@contoso.com",
  "phone": "+1-555-0100",
  "categoryCode": 1,
  "primaryContact": "contact-guid-here",
  "creditLimit": 50000.00
}

API Response

Success (200 OK):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Update Action

The Update Action exposes an HTTP PUT endpoint for modifying an existing record. The record id is taken from the route, and the supplied fields are written to the Dataverse record according to the action's entity-property bindings.

Update Action Features

HTTP PUT: The update action is emitted as a PUT endpoint (PATCH is not generated)
Field bindings: Only the fields mapped in Entity Properties are written
Data Validation: Pre-conditions can validate business rules before updates
Audit Trail: Changes can be tracked through Dataverse audit

API Request Example

PUT /sales/account/a1b2c3d4-e5f6-7890-abcd-ef1234567890/update
Content-Type: application/json
Authorization: Bearer {token}

{
  "name": "Contoso Corporation",
  "email": "info@contoso.com",
  "phone": "+1-555-0200",
  "creditLimit": 75000.00
}

API Response

Success (200 OK):

HTTP/1.1 200 OK
Content-Length: 0

Note: Update operations return an empty response body on success.

Read Action

The Read Action exposes an endpoint for retrieving a single record by its identifier.

Read Action Configuration

Property	Required	Description
Endpoint Name	Yes	URL path segment (e.g., `get`, producing `/{module}/{entity}/{id}/get`)
Retrieve Attachment List	No	Include list of attachments in response

Properties Configuration

Properties define which fields are returned in the API response:

Property Attribute	Description
Field Name	The Dataverse field to include
API Name	The name used in the JSON response
Type	Data type for serialization
Expand	For lookups, which related fields to include
Computed	Calculated values derived from other fields

Retrieve Attachment List

When enabled, the response includes metadata about all attachments:

{
  "accountId": "...",
  "name": "Contoso Ltd",
  "attachments": [
    {
      "attachmentId": "note-guid-1",
      "fileName": "contract.pdf",
      "fileSize": 245678,
      "mimeType": "application/pdf",
      "createdOn": "2024-01-15T10:30:00Z",
      "createdBy": "John Smith"
    }
  ]
}

API Request

GET /sales/account/a1b2c3d4-e5f6-7890-abcd-ef1234567890/get
Authorization: Bearer {token}

API Response

Success (200 OK):

{
  "accountId": "a1b2c3d4-...",
  "name": "Contoso Ltd",
  "telephone1": "+1-555-0100",
  "emailAddress1": "info@contoso.com",
  "primaryContact": {
    "id": "contact-guid",
    "name": "Jane Doe"
  }
}

Not Found (404): When the record doesn't exist, the Read action returns 404 Not Found with an error body (errorCode: "NOT_FOUND").

Delete Action

The Delete Action exposes an endpoint for removing records. Delete operations typically require the strictest access control.

Delete Action Best Practices

Data Fetcher Considerations:

Verify the record exists before deletion
Check for related records that would be orphaned
Validate business rules (status, ownership, time restrictions)
Gather audit information before deletion

Common Pre-conditions:

Pre-condition Type	Example
Record exists	Return 404 if not found
Record is inactive	Require deactivation before deletion
No dependent records	Prevent orphaning child records
Ownership check	Only owner or admin can delete
Approval status	Cannot delete approved/finalized records

API Request

DELETE /sales/account/a1b2c3d4-e5f6-7890-abcd-ef1234567890/delete
Authorization: Bearer {token}

API Response

Success (200 OK):

HTTP/1.1 200 OK
Content-Length: 0

Upload Action

The Upload Action allows a file to be attached to an entity record. It accepts a single multipart/form-data file in a form field named file. The record id comes from the route.

Upload Configuration

Property	Required	Description
Name	Yes	Endpoint name (URL path segment, e.g. "upload-documents")
Attachment Name	No	Expression that names the created attachment (annotation subject)
Allow Multiple	No	Whether multiple attachments may be created on the record

API Request

POST /support/incident/{caseId}/upload-documents
Content-Type: multipart/form-data
Authorization: Bearer {token}

------WebKitFormBoundary
Content-Disposition: form-data; name="file"; filename="document.pdf"
Content-Type: application/pdf

[file binary data]
------WebKitFormBoundary--

API Response

Success (200 OK):

HTTP/1.1 200 OK
Content-Length: 0

If the referenced upload action or record cannot be resolved, the engine returns 404 Not Found or a 400 Bad Request with errorCode: "ARGUMENT_VALIDATION_ERROR".

Download Action

The Download Action retrieves a specific attachment from an entity record. The record id and the attachment id (aid) both come from the route, producing /{module}/{entity}/{id}/{endpoint-name}/{attachmentId}.

Download Configuration

Property	Required	Description
Name	Yes	Endpoint name (URL path segment)

API Request

GET /support/incident/{caseId}/download/{attachmentId}
Authorization: Bearer {token}

API Response

Success (200 OK): Returns the file binary data with appropriate headers:

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="contract.pdf"
Content-Length: 245678

[file binary data]

Not Found (404):

{
  "errorCode": "NOT_FOUND",
  "errorMessage": "The requested attachment was not found"
}

Process Action

Process Actions expose Dataverse custom actions (processes) through the API. They can be either Local (bound to an entity) or Global (unbound).

Process Action Types

Type	URL Pattern	Use Case
Local	`POST /{module}/{entity}/{action}?id={id}`	Entity-bound operations (record `id` passed as a required query parameter)
Global	`POST /{module}/{action}`	Cross-entity or standalone operations

Process Action Binding

Process Input Arguments: Maps API inputs to the custom action's input parameters.

Property	Description
Process Argument	The custom action's input parameter name
Binding	The API input, fetched data, or expression to use

Process Output Arguments: Maps the custom action's output parameters to the API response.

Property	Description
Process Argument	The custom action's output parameter name
Response Field	The field name in the API response
Transform	Optional transformation before returning

API Request Example

POST /sales/account/approve?id={accountId}
Content-Type: application/json
Authorization: Bearer {token}

{
  "approvalNotes": "Credit check passed",
  "creditLimit": 50000.00
}

API Response

Success (200 OK):

{}

Note: Process actions typically return an empty response body on success, or may return output parameters if defined.

Common Action Components​

Definition​

Documentation​

Inputs​

Data Fetcher​

Access Control​

Create Action​

Create Action Structure​

Entity Properties​

API Request Example​

API Response​

Update Action​

Update Action Features​

API Request Example​

API Response​

Read Action​

Read Action Configuration​

Properties Configuration​

Retrieve Attachment List​

API Request​

API Response​

Delete Action​

Delete Action Best Practices​

API Request​

API Response​

Upload Action​

Upload Configuration​

API Request​

API Response​

Download Action​

Download Configuration​

API Request​

API Response​

Process Action​

Process Action Types​

Process Action Binding​

API Request Example​

API Response​

Common Action Components

Definition

Documentation

Inputs

Data Fetcher

Access Control

Create Action

Create Action Structure

Entity Properties

API Request Example

API Response

Update Action

Update Action Features

API Request Example

API Response

Read Action

Read Action Configuration

Properties Configuration

Retrieve Attachment List

API Request

API Response

Delete Action

Delete Action Best Practices

API Request

API Response

Upload Action

Upload Configuration

API Request

API Response

Download Action

Download Configuration

API Request

API Response

Process Action

Process Action Types

Process Action Binding

API Request Example

API Response