DEXPRO AWF External Approvals — API Integration Guide

~~Provisioning…~~Audience: Developers building custom approval interfaces or integrations that consume the DEXPRO AWF External Approvals API directly.
Looking for the SharePoint / Teams reference implementation? See SETUP-GUIDE.md (admin setup) and SHAREPOINT-CONTRACT.md (SharePoint list contract).

Overview

The External Approvals API exposes pending approval entries directly as OData resources inside Business Central's standard API V2 framework. Any system that can make HTTPS calls — a custom portal, a mobile app, a third-party notification service, an Azure Function — can:

Poll for approvals assigned to specific people or groups
Display record context to the approver
Submit approve / reject decisions with an optional comment
Handle group (claim-based) approvals

No SharePoint setup required. The API works independently of the SharePoint integration toggle (SP Approvals Enabled). As long as the DEXPRO AWF extension is installed and external approvers are configured in BC, the API pages are live.

When to use the API vs. the SharePoint integration

	API Integration	SharePoint Integration
Setup	None beyond BC API access	App registration, SP site, wizard
Notification	Your system handles it	Power Automate → Teams Adaptive Card
Response collection	Your UI calls the BC API directly	Approver responds in Teams; PA writes to SP; BC polls SP
Licence needed (approver)	Paid BC user licence (see licensing note)	Paid BC user licence, plus M365 for Teams (see licensing note)
Good for	Custom portals, mobile apps, vendor self-service	Quick Teams rollout, minimal dev effort

Licensing — customer/partner responsibility: Acting on Business Central data — whether directly via the API or indirectly through the SharePoint relay — requires each approver to hold an appropriate paid Business Central user licence. A Microsoft 365 licence alone does not grant API or write access to BC, and routing actions through a service account does not remove the per-user requirement (Microsoft's multiplexing / indirect-access terms). A Team Member licence may be sufficient for approval-only use, but Microsoft restricts Team Member to designated scenarios and this is not guaranteed for custom or third-party interfaces — a full Essentials/Premium user may be required. DEXPRO makes no licensing representation. The customer and their Microsoft licensing partner are solely responsible for determining and maintaining correct licensing; verify against the current Microsoft Dynamics 365 Licensing Guide.

Prerequisites

Requirement	Details
Business Central	DEXPRO AWF extension installed, BC 25 or later
Entra App Registration	An Entra ID app with `Financials.ReadWrite.All` (or a delegated user flow) for BC API access
BC permission set	The API caller's service account needs a permission set that grants read access to `DXP AWF Ext. Approval Entry` and write access for the bound actions (`approve`, `reject`, `claim`, `releaseClaim`, `markNotified`, `setTeamsMessageId`). The DXP AWF Admin set covers this. No explicit Execute permission on the API page is required — it is granted automatically via the page's inherent entitlements.
External Approvers	At least one external approver configured in BC (AWF Setup → External Approvers)

Authentication

The BC API V2 uses OAuth 2.0 with Microsoft Entra ID. Obtain a bearer token from:

POST https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token

grant_type=client_credentials
&client_id={clientId}
&client_secret={clientSecret}
&scope=https://api.businesscentral.dynamics.com/.default

Include the token on every request:

Authorization: Bearer {access_token}

Note: Client Credentials flow is suitable for backend service integrations. For user-delegated flows (e.g. a web portal where each approver authenticates as themselves), use Authorization Code + PKCE instead — the token then carries the user's identity, which is useful for audit purposes.

Base URL

https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environmentName}/api/dexpro/advancedWorkflow/v1.0

All examples below use {baseUrl} as a shorthand for this full base URL.

To find your company ID (a GUID required in most requests):

GET {baseUrl}/companies

Response (abbreviated):

{
  "value": [
    {
      "id": "5e9f4c3a-0001-ef11-9f8a-6045bd028c9f",
      "name": "CRONUS International Ltd.",
      ...
    }
  ]
}

Use the id value as {companyId} in subsequent requests.

Entities

Three read-only entity sets are available. All use SystemId (a platform-assigned GUID, exposed as id) as the OData key — the standard BC API V2 convention and a requirement for Power Automate / Power Apps compatibility.

Entity set	OData URL segment	OData key field	Description
Approval entries	`externalApprovalEntries`	`id` (SystemId)	The actionable entries — one per approver per approval request. Main entity for integrations.
Approvers	`externalApprovers`	`id` (SystemId)	The registered external approver records. Useful for bootstrap / pre-population.
Group members	`externalApproverMembers`	`id` (SystemId)	Members of external approver groups.
Entry document	`externalApprovalEntryDocuments`	`id` (SystemId)	Source document record as JSON. Separate endpoint — only fetched on demand.
Entry attachments	`externalApprovalEntryAttachments`	`id` (SystemId)	Standard BC document attachments for the source record. Separate endpoint — only fetched on demand.

Why GUIDs, not integers? The entryNo integer field is still present in the response body for display and correlation, but it is not the OData key. Using SystemId (GUID) as the key follows Microsoft's official BC API guidance and ensures compatibility with Power Automate, Power Apps, and Logic Apps connectors. Always use id in URL paths.

Working with Approval Entries

List all pending entries for one approver

GET {baseUrl}/companies({companyId})/externalApprovalEntries
    ?$filter=approverEmail eq 'john.doe@contoso.com' and status eq 'Pending'
    &$orderby=createdDateTime asc

Response:

{
  "@odata.context": "...",
  "value": [
    {
      "id": "b9f3a2c1-0001-ef11-bf8d-6045bd028c9f",
      "entryNo": 42,
      "approvalEntryNo": 17,
      "workflowInstanceId": "a1b2c3d4-0000-0000-0000-000000000001",
      "templateCode": "PURCHASE-APPROVAL",
      "stageCode": "EXT-REVIEW",
      "stageDescription": "External Review",
      "documentNo": "PO-00123",
      "documentType": "Order",
      "approverEmail": "john.doe@contoso.com",
      "approverDisplayName": "John Doe",
      "status": "Pending",
      "isGroupApproval": false,
      "isRelatedApproval": false,
      "description": "Fabrikam Inc.",
      "recordDescription": "Purchase Order PO-00123",
      "amount": 15000.00,
      "dueDate": "2026-05-15",
      "senderUserId": "PROCUREMENT",
      "languageCode": "ENU",
      "processed": false,
      "createdDateTime": "2026-05-04T09:12:33Z",
      "errorMessage": "",
      "spListItemId": "",
      "spAttachmentsUrl": ""
    }
  ]
}

Retrieve a single entry

GET {baseUrl}/companies({companyId})/externalApprovalEntries(b9f3a2c1-0001-ef11-bf8d-6045bd028c9f)

Common filter patterns

# All pending entries for an approver (individual + group)
$filter=approverEmail eq 'jane@contoso.com' and processed eq false and status ne 'Cancelled'

# All pending entries for a group (show to all members before one claims)
$filter=extApproverGroupCode eq 'FINANCE-GROUP' and status eq 'Pending'

# Entries with processing errors (for admin monitoring)
$filter=errorMessage ne '' and processed eq false

# All actionable entries for a group member (pending or claimed by them)
$filter=approverEmail eq 'jane@contoso.com'
    and (status eq 'Pending' or status eq 'Notified' or status eq 'Claimed')
    and processed eq false

Bound Actions

Actions are called as OData bound actions via POST. The URL pattern is:

POST {baseUrl}/companies({companyId})/externalApprovalEntries({id})/Microsoft.NAV.{actionName}
Content-Type: application/json

{id} is the id field (SystemId GUID) from the entry. A successful call returns 200 OK with the updated entry in the response body.

approve

Records an approval decision and advances the BC workflow.

POST {baseUrl}/companies({companyId})/externalApprovalEntries(b9f3a2c1-0001-ef11-bf8d-6045bd028c9f)/Microsoft.NAV.approve
Content-Type: application/json

{
  "approverEmail": "john.doe@contoso.com",
  "comment": "Looks good. Approved as per Q2 budget."
}

approverEmail is required — pass the email of the user who actually performed the approval. This is recorded in the BC audit log and on the approval entry. Since the API is typically called by a backend service (client credentials), BC has no other way to know the real actor's identity.

comment is optional. Omit or pass "" to approve without a comment.

Response 200 OK:

{
  "id": "b9f3a2c1-0001-ef11-bf8d-6045bd028c9f",
  "entryNo": 42,
  "approverEmail": "john.doe@contoso.com",
  "status": "Approved",
  "responseComment": "Looks good. Approved as per Q2 budget.",
  "responseDateTime": "2026-05-04T10:35:12Z",
  "processed": true,
  "processedDateTime": "2026-05-04T10:35:12Z",
  ...
}

reject

Records a rejection decision and drives the BC rejection flow (including reassignment for related approvals).

POST {baseUrl}/companies({companyId})/externalApprovalEntries(b9f3a2c1-0001-ef11-bf8d-6045bd028c9f)/Microsoft.NAV.reject
Content-Type: application/json

{
  "approverEmail": "john.doe@contoso.com",
  "comment": "Amount exceeds departmental authority. Escalate to CFO."
}

approverEmail is required for the same reasons as approve.

Response 200 OK:

{
  "id": "b9f3a2c1-0001-ef11-bf8d-6045bd028c9f",
  "entryNo": 42,
  "approverEmail": "john.doe@contoso.com",
  "status": "Rejected",
  "responseComment": "Amount exceeds departmental authority. Escalate to CFO.",
  "responseDateTime": "2026-05-04T10:38:44Z",
  "processed": true,
  ...
}

markNotified

Call this after your system has successfully delivered the approval notification to the approver (e.g. sent an email, shown the card in your portal). Transitions status from Pending → Notified. This is optional but recommended — it allows BC admins to distinguish between entries that were never delivered and entries awaiting a response.

POST {baseUrl}/companies({companyId})/externalApprovalEntries(b9f3a2c1-0001-ef11-bf8d-6045bd028c9f)/Microsoft.NAV.markNotified
Content-Type: application/json

{}

Response 200 OK:

{
  "id": "b9f3a2c1-0001-ef11-bf8d-6045bd028c9f",
  "entryNo": 42,
  "status": "Notified",
  ...
}

Only effective when current status is Pending. A no-op on any other status.

setTeamsMessageId

Call this instead of markNotified when your transport can later need to update/close the posted message (e.g. a Microsoft Teams adaptive card). It does everything markNotified does (Pending → Notified) and stores the transport's message identifier on the entry (BC field Teams Message ID) and mirrors it onto the SharePoint column TeamsMessageId. The Power Automate v2 flow uses this so a peer claim/decision can replace (close) other group members' still-open cards via Update an adaptive card.

POST {baseUrl}/companies({companyId})/externalApprovalEntries(b9f3a2c1-0001-ef11-bf8d-6045bd028c9f)/Microsoft.NAV.setTeamsMessageId
Content-Type: application/json

{ "teamsMessageId": "1700000000000" }

Response 200 OK:

{
  "id": "b9f3a2c1-0001-ef11-bf8d-6045bd028c9f",
  "entryNo": 42,
  "status": "Notified",
  "teamsMessageId": "1700000000000",
  ...
}

Pass the message identifier your transport returns when it posts the message — for the Teams connector's Post card in a chat or channel action that is body/id. Empty input is ignored (the entry is still marked Notified). Calling it with the same id again is a no-op.

claim (group approvals only)

Claims a group approval entry. This is the "first wins" step: once claimed, all other group members' entries for the same approval request are cancelled, and only the claimer can then approve or reject.

POST {baseUrl}/companies({companyId})/externalApprovalEntries(c4e7d1a2-0002-ef11-bf8d-6045bd028c9f)/Microsoft.NAV.claim
Content-Type: application/json

{
  "claimerEmail": "jane.smith@contoso.com"
}

claimerEmail is required — pass the email of the user who is claiming the entry. This is recorded in the audit log and written back to the BC approval entry as the claimer's identity.


Response `200 OK`:
```json
{
  "id": "c4e7d1a2-0002-ef11-bf8d-6045bd028c9f",
  "entryNo": 43,
  "status": "Claimed",
  "claimedByEmail": "jane.smith@contoso.com",
  "claimedByDisplayName": "Jane Smith",
  "claimedDateTime": "2026-05-04T10:41:02Z",
  ...
}

Race condition: If two group members call claim simultaneously, only one wins. The loser receives 400 Bad Request with the error body: "This entry was already claimed by jane.smith@contoso.com." Your UI should catch this and refresh the entry for the losing caller.

releaseClaim (group approvals only)

Releases a previously claimed entry, returning it to Notified status so another group member can claim it.

POST {baseUrl}/companies({companyId})/externalApprovalEntries(c4e7d1a2-0002-ef11-bf8d-6045bd028c9f)/Microsoft.NAV.releaseClaim
Content-Type: application/json

{}

Response 200 OK:

{
  "id": "c4e7d1a2-0002-ef11-bf8d-6045bd028c9f",
  "entryNo": 43,
  "status": "Notified",
  "claimedByEmail": "",
  "claimedByDisplayName": "",
  ...
}

Status State Machine

                   ┌───────────────────────────────────┐
                   │                                   │
     BC creates    ▼                                   │
  entry ──────► Pending ──── markNotified ──────► Notified
                   │                                   │
                   │           (group only)            │
                   └──────────────────── ──────────────┘
                                        │
                                        ▼ claim
                                     Claimed ◄──── releaseClaim ──┐
                                        │                          │
                                        └──────────────────────────┘
                   │                    │
      approve ─────┤                    │ approve / reject
      reject ──────┤                    │
                   ▼                    ▼
               Approved / Rejected  (same)
                   │
              [processed = false, BC runs workflow engine]
                   │
              [processed = true]
                   │
               ────┘

Status	Meaning	Actionable?
`Pending`	Created, not yet delivered to the approver	`markNotified`, `approve`, `reject`, `claim`
`Notified`	Your system confirmed the approver was notified	`approve`, `reject`, `claim`
`Claimed`	A group member has claimed this entry	`approve`, `reject` (claimer only), `releaseClaim`
`Approved`	Approver approved; BC may still be processing	—
`Rejected`	Approver rejected	—
`Cancelled`	Cancelled by BC (peer claimed/decided, workflow reassigned, or document re-opened)	—

processed vs. status: status is the approver's decision. processed = true means BC's workflow engine has successfully consumed the decision. An entry can be status = Approved with processed = false if the workflow engine call failed — check errorMessage for details. BC admins can retry from the External Approval Entries page.

Group Approvals

When an approval stage targets an External Approver Group, BC creates one externalApprovalEntry for each group member. They share the same workflowInstanceId and approvalEntryNo but have different id, approverEmail, and externalApproverCode values.

isGroupApproval = true on all of them.

Integration flow for group approvals

Notify all members — query entries by extApproverGroupCode + status eq 'Pending'. Show each member their own entry and store the entry's id for subsequent action calls.
Member claims — when a member taps "Claim", call Microsoft.NAV.claim on their entry's id. BC cancels the other members' entries automatically.
Claimer decides — show the approver their claimed entry. They call approve or reject on the same id they claimed.
Poll for cancellations — after a claim, entries belonging to other group members transition to Cancelled. Your UI should handle this gracefully (e.g. "This approval has been claimed by Jane Smith").

Detecting peer cancellations

GET {baseUrl}/companies({companyId})/externalApprovalEntries
    ?$filter=approverEmail eq 'bob@contoso.com' and status eq 'Cancelled' and processed eq false
    &$orderby=createdDateTime desc
    &$top=50

Entries in Cancelled state that have processed = false were cancelled because a peer claimed or decided first (not because the workflow was revoked by a BC user).

Single-member groups

BC auto-claims single-member group entries at creation time — status is already Claimed when first fetched and claimedByEmail is pre-populated. Skip the claim step and go straight to approve / reject.

Field Reference — externalApprovalEntry

JSON field	Type	Description
`id`	GUID	OData key. SystemId — use this in all action URLs and single-record GETs.
`entryNo`	Integer	Internal BC sequence number. Useful for display, correlation, and reading related SharePoint items (`BCEntryNo` column). Not the OData key.
`approvalEntryNo`	Integer	Key of the linked BC standard Approval Entry.
`workflowInstanceId`	GUID	BC workflow instance. Shared by all entries (including related lines) in the same workflow run.
`templateCode`	String	AWF Workflow Template code.
`stageCode`	String	AWF Workflow Stage code.
`stageDescription`	String	Human-readable stage description. Show to the approver.
`documentTableId`	Integer	BC table ID of the source record (e.g. `38` for Purchase Header, `36` for Sales Header). Useful for routing or rendering table-specific UI in your portal.
`documentNo`	String	Document number being approved (e.g. `PO-00123`).
`documentType`	String	Document type enum caption (e.g. `Order`, `Invoice`, `""` for custom tables).
`externalApproverCode`	String	Code of the External Approver record in BC.
`extApproverGroupCode`	String	Code of the External Approver Group, if this is a group approval. Empty for individual approvals.
`approverEmail`	String	Email of the approver assigned to this specific entry. Use for routing.
`approverDisplayName`	String	Display name of the assigned approver.
`status`	String	See Status State Machine above.
`isGroupApproval`	Boolean	Whether this is part of a claim-based group approval.
`claimedByEmail`	String	Email of the group member who claimed the entry. Empty on individual approvals.
`claimedByDisplayName`	String	Display name of the claimer.
`claimedDateTime`	DateTime	When the entry was claimed (UTC).
`processed`	Boolean	Whether BC's workflow engine has successfully consumed this decision.
`processedDateTime`	DateTime	When BC processed the decision (UTC).
`errorMessage`	String	Non-empty if `processed = false` after an Approved/Rejected decision — the workflow engine call failed.
`description`	String	Contextual description (e.g. vendor name, customer name). Good for display in a card or list.
`recordDescription`	String	Full record identifier (e.g. `"Table 38 (Purchase Header): Order, PO-00123"`). Use for detailed display.
`amount`	Decimal	Approval amount.
`dueDate`	Date	Approval due date (ISO 8601 date, e.g. `2026-05-15`).
`senderUserId`	String	BC User ID of the person who sent the document for approval.
`languageCode`	String	BC language code of the assigned approver (e.g. `ENU`, `DEU`). Use to localise your notification.
`responseComment`	String	Comment entered by the approver. Populated after approve/reject.
`responseDateTime`	DateTime	When the approver responded (UTC).
`isRelatedApproval`	Boolean	True for line-level (related) entries linked to a header approval.
`createdDateTime`	DateTime	When BC created this entry (UTC).
`spListItemId`	String	SharePoint list item ID. Only populated when SP Approvals is enabled. Ignore for pure API integrations.
`spAttachmentsUrl`	String	SharePoint sharing link for document attachments. Only populated when SP Approvals is enabled and attachments were uploaded.

Field Reference — externalApprover

JSON field	Type	Description
`id`	GUID	OData key. SystemId.
`code`	String	Internal BC approver code (Code[20]).
`displayName`	String	Full name.
`email`	String	Email / UPN.
`languageCode`	String	BC language code for notifications.
`entraObjectId`	GUID	Entra ID object ID (populated for Entra-synced approvers).
`blocked`	Boolean	Blocked approvers cannot receive new entries.

Field Reference — externalApproverMember

JSON field	Type	Description
`id`	GUID	OData key. SystemId.
`groupCode`	String	The External Approver Group code.
`lineNo`	Integer	Line number within the group (informational only).
`externalApproverCode`	String	Member's approver code.
`displayName`	String	Member's display name.
`email`	String	Member's email.

Complete Example: Individual Approval Flow

The following sequence implements a minimal approval portal for individual approvers.

Step 1 — Authenticate and get pending entries

GET {baseUrl}/companies({companyId})/externalApprovalEntries
    ?$filter=approverEmail eq 'john.doe@contoso.com'
        and status ne 'Cancelled'
        and processed eq false
    &$select=id,entryNo,documentNo,description,stageDescription,amount,dueDate,status,isGroupApproval,createdDateTime
    &$orderby=createdDateTime asc

Step 2 — Show entry details to the approver

Use description, stageDescription, amount, dueDate, and senderUserId to build an approval card. Store the entry's id GUID — you need it for action calls.

Step 3 — Mark as notified

After showing the card to the approver:

POST {baseUrl}/companies({companyId})/externalApprovalEntries(b9f3a2c1-0001-ef11-bf8d-6045bd028c9f)/Microsoft.NAV.markNotified
Content-Type: application/json

{}

Step 4 — Collect decision

Approver clicks Approve with a comment:

POST {baseUrl}/companies({companyId})/externalApprovalEntries(b9f3a2c1-0001-ef11-bf8d-6045bd028c9f)/Microsoft.NAV.approve
Content-Type: application/json

{
  "approverEmail": "john.doe@contoso.com",
  "comment": "Within budget allocation, approved."
}

Complete Example: Group Approval Flow

Step 1 — Notify all group members

Fetch entries for the group, one per member:

GET {baseUrl}/companies({companyId})/externalApprovalEntries
    ?$filter=extApproverGroupCode eq 'FINANCE-GROUP'
        and (status eq 'Pending' or status eq 'Notified')
        and processed eq false

Send each member a notification that includes their entry's id.

Step 2 — Member claims

Jane opens the portal and taps "Claim" (using the id from her own entry):

POST {baseUrl}/companies({companyId})/externalApprovalEntries(c4e7d1a2-0002-ef11-bf8d-6045bd028c9f)/Microsoft.NAV.claim
Content-Type: application/json

{
  "claimerEmail": "jane.smith@contoso.com"
}


BC cancels all sibling entries (the other group members' entries for this same approval).

**Handle the race:** If the entry was already claimed by someone else, BC returns `400 Bad Request`:

```json
{
  "error": {
    "code": "Internal",
    "message": "This entry was already claimed by bob.smith@contoso.com. CorrelationId: ..."
  }
}

Refresh and show "This approval was claimed by Bob Smith" to Jane.

Step 3 — Claimer decides

Jane calls approve using the same id:

POST {baseUrl}/companies({companyId})/externalApprovalEntries(c4e7d1a2-0002-ef11-bf8d-6045bd028c9f)/Microsoft.NAV.approve
Content-Type: application/json

{
  "approverEmail": "jane.smith@contoso.com",
  "comment": "Reviewed line items, all within policy."
}

Error Handling

HTTP status codes

Code	When
`200 OK`	Action succeeded. Response body contains the updated entry.
`400 Bad Request`	Business logic error (entry already processed, already claimed by someone else, not in a claimable state). Read `error.message` for details.
`401 Unauthorized`	Missing or expired bearer token.
`403 Forbidden`	The API caller's BC user lacks the required permission set.
`404 Not Found`	Entry not found in this company, or wrong `id` GUID.

Idempotency

approve and reject are guarded: calling them on an already-processed entry returns 400 with "This external approval entry has already been processed…". Safe to retry only if the previous call returned a non-200 response.
markNotified is a no-op when status is not Pending — safe to call multiple times.
claim is not idempotent by design: calling it twice from two different callers is the race condition you need to handle.

SharePoint/Teams race condition

When SharePoint integration is active, the entry may have been decided via Teams between your last poll and your approve/reject/claim call. The API syncs live SP state before processing (SyncFromSPIfNeeded), so a now-closed entry is rejected with 400 and one of the actual guard messages:

"This external approval entry has already been processed by Business Central and cannot be acted on again."
"This external approval entry has been cancelled (a peer in the group decided first, or the workflow was reassigned). Refresh the list to see the current state."

This is not a retryable error — treat it like a Cancelled state and refresh the entry list for the user.

Entries that disappear

An entry's status can transition to Cancelled at any time due to external events:

A BC user reassigns or cancels the underlying approval entry
The document is re-opened (cancels the whole workflow)
A peer in the same group claimed first (only for group entries)

Always check for Cancelled status before showing an entry to the approver, and handle 400 responses gracefully with a refresh.

Polling Recommendations

There is no webhook or push mechanism — your integration polls the API. Recommended intervals:

Use case	Interval
Notification delivery (fetch new `Pending` entries)	1–5 minutes
Approval portal refresh (logged-in user)	On demand (user refresh) + on page load
Group membership refresh	Query `externalApproverMembers` on each portal login

To detect newly created entries since the last poll, filter on createdDateTime:

GET {baseUrl}/companies({companyId})/externalApprovalEntries
    ?$filter=status eq 'Pending' and createdDateTime gt 2026-05-04T09:00:00Z
    &$orderby=createdDateTime asc

Record JSON

Each approval entry has a corresponding externalApprovalEntryDocuments endpoint that returns the full JSON representation of the source document record — the actual BC table row being approved (e.g. the Purchase Order, Sales Quote, or custom record).

This is a separate endpoint from externalApprovalEntries. It is only fetched when explicitly called, keeping list queries fast.

GET {baseUrl}/companies({companyId})/externalApprovalEntryDocuments(b9f3a2c1-0001-ef11-bf8d-6045bd028c9f)

The id is the same SystemId GUID as the corresponding externalApprovalEntry. Example response:

{
  "id": "b9f3a2c1-0001-ef11-bf8d-6045bd028c9f",
  "entryNo": 42,
  "documentNo": "PO-00123",
  "recordJson": "{\"No_\":\"PO-00123\",\"Document_Type\":\"Order\",\"Buy-from_Vendor_No_\":\"V00010\",\"Buy-from_Vendor_Name\":\"Fabrikam Inc.\",\"Amount\":15000.00,\"Amount_Including_VAT\":17850.00,\"Due_Date\":\"2026-05-15\",\"TableNo\":38,\"TableName\":\"Purchase Header\",\"TableCaption\":\"Purchase Header\",\"Company\":\"CRONUS International Ltd.\", ...}"
}

recordJson is a JSON string (not a nested object) — parse it with JSON.parse() in your client.

What the JSON contains

The JSON object is produced by DXP Json Helper.Rec2Json and includes:

All table fields — field captions (with spaces replaced by _) as keys, values serialized to their JSON-native types
Metadata fields automatically added by the helper:
- TableNo — numeric table ID
- TableName — internal table name
- TableCaption — localized table caption
- Company — company name
- RecordId — BC RecordId string
- SysLink — SystemId + TableNo composite

Performance note

recordJson is computed on every record read — it navigates to the source document and serializes all its fields. Since it lives on a dedicated endpoint, it is only fetched when you explicitly call externalApprovalEntryDocuments. Use the entries endpoint for list queries and only call the documents endpoint when you need the full record:

# Fast list — no document lookup
GET {baseUrl}/companies({companyId})/externalApprovalEntries
    ?$filter=approverEmail eq 'john@contoso.com' and status eq 'Pending'

# On-demand — fetch the full record only for the entry the approver opened
GET {baseUrl}/companies({companyId})/externalApprovalEntryDocuments({id})

Fallback

If the source document was deleted or the Approval Entry link is missing, recordJson returns "{}" (an empty JSON object string) rather than an error.

Record Attachments

Each approval entry has a corresponding externalApprovalEntryAttachments endpoint that returns all standard BC document attachments for the source record as a JSON array. Each element includes the file metadata and the full file content as a Base64 string, ready to render or download client-side.

This is a separate endpoint from externalApprovalEntries. It is only fetched when explicitly called.

GET {baseUrl}/companies({companyId})/externalApprovalEntryAttachments(b9f3a2c1-0001-ef11-bf8d-6045bd028c9f)

Example response:

{
  "id": "b9f3a2c1-0001-ef11-bf8d-6045bd028c9f",
  "entryNo": 42,
  "documentNo": "PO-00123",
  "recordAttachmentsJson": "[{\"fileName\":\"PO-00123 Specification\",\"fileExtension\":\"pdf\",\"attachedDate\":\"2026-05-03T14:22:00Z\",\"attachedBy\":\"Alice Johnson\",\"lineNo\":0,\"contentBase64\":\"JVBERi0xLjQK...\"},{\"fileName\":\"Vendor Quote\",\"fileExtension\":\"xlsx\",\"attachedDate\":\"2026-05-03T14:23:00Z\",\"attachedBy\":\"Alice Johnson\",\"lineNo\":0,\"contentBase64\":\"UEsDBBQA...\"}]"
}

recordAttachmentsJson is a JSON string — parse it with JSON.parse().

Attachment object fields

Field	Type	Description
`fileName`	String	File name without extension.
`fileExtension`	String	File extension without dot (e.g. `pdf`, `xlsx`, `png`).
`attachedDate`	DateTime	When the file was attached (UTC).
`attachedBy`	String	BC user ID of the person who attached the file.
`lineNo`	Integer	`0` for document-level (header) attachments; non-zero for line-level attachments.
`contentBase64`	String	Full file content, Base64-encoded. Empty string if the file has no content. Decode with `atob()` in a browser or your platform's Base64 decoder.

Client-side decode example (JavaScript)

const attachments = JSON.parse(entry.recordAttachmentsJson);
attachments.forEach(a => {
  const bytes = Uint8Array.from(atob(a.contentBase64), c => c.charCodeAt(0));
  const blob  = new Blob([bytes], { type: mimeTypeFor(a.fileExtension) });
  const url   = URL.createObjectURL(blob);
  // render download link or open inline
});

Performance note

recordAttachmentsJson reads and Base64-encodes every attachment for the source document on every record read. Since it lives on a dedicated endpoint, it is only fetched when you explicitly call externalApprovalEntryAttachments:

# Fast list — no attachment loading
GET {baseUrl}/companies({companyId})/externalApprovalEntries
    ?$filter=approverEmail eq 'john@contoso.com' and status eq 'Pending'

# On-demand — fetch attachments only when the approver opens an entry
GET {baseUrl}/companies({companyId})/externalApprovalEntryAttachments({id})

Fallback

Returns "[]" (empty JSON array string) if the source document has no attachments, or if the document was deleted.

Document	Purpose
`SETUP-GUIDE.md`	Admin setup guide for the SharePoint / Teams integration
`SHAREPOINT-CONTRACT.md`	Contract for integrations that read/write the SharePoint list directly
`POWERAUTOMATE-DEV-GUIDE.md`	Internal guide for maintaining the Power Automate reference flow

DEXPRO AWF External Approvals — API Integration Guide

Overview

When to use the API vs. the SharePoint integration

Prerequisites

Authentication

Base URL

Entities

Working with Approval Entries

List all pending entries for one approver

Retrieve a single entry

Common filter patterns

Bound Actions

approve

reject

markNotified

setTeamsMessageId

claim (group approvals only)

releaseClaim (group approvals only)

Status State Machine

Group Approvals

Integration flow for group approvals

Detecting peer cancellations

Single-member groups

Field Reference — externalApprovalEntry

Field Reference — externalApprover

Field Reference — externalApproverMember

Complete Example: Individual Approval Flow

Step 1 — Authenticate and get pending entries

Step 2 — Show entry details to the approver

Step 3 — Mark as notified

Step 4 — Collect decision

Complete Example: Group Approval Flow

Step 1 — Notify all group members

Step 2 — Member claims

Step 3 — Claimer decides

Error Handling

HTTP status codes

Idempotency

SharePoint/Teams race condition

Entries that disappear

Polling Recommendations

Record JSON

What the JSON contains

Performance note

Fallback

Record Attachments

Attachment object fields

Client-side decode example (JavaScript)

Performance note

Fallback

Related Documentation