younifyd
Menu

Connectors

Business Central

Work with Microsoft Dynamics 365 Business Central sales and purchase documents — customers, vendors, items, invoices, orders, and their lines — through the automation API. Covers OAuth auth, the company_id and If-Match requirements, and OData response shapes.

On this page

Connecting Business Central

Every action needs a Business Central connection configured with OAuth 2.0 (Microsoft Entra ID) credentials for an app registration that has the Financials.ReadWrite.All permission and access to your environment. The token is sent as a Bearer token automatically.

Set the Base URL for your tenant. Every action has a Base URL dropdown offering a production and a sandbox host, but neither includes your Entra tenant id. In practice, pick Custom in that dropdown and enter:

https://api.businesscentral.dynamics.com/v2.0/<tenant-id>/<environment>/api/v1.0

where <environment> is your BC environment name (e.g. Production, Sandbox).

How Business Central actions are structured

Each action is one operation of the Business Central automation API (api/v1.0). They all appear under a single Business Central group in the action picker (plus a Generic Request group); this page organizes them by entity — Companies, Items, Customers, Vendors, Sales Invoices, Sales Invoice Lines, Sales Orders, Sales Order Lines, Purchase Invoices, Purchase Invoice Lines — for readability. Names read like "List Customers", "Get Customer", "Post Customer" (create), "Patch Customer" (update), "Delete Customer".

Common fields on every action:

  • company_id — path parameter present on almost every action (Companies is the exception). It's the BC company GUID; a "List Companies" step (reference listCompanies) exposes it at {{listCompanies.response.data.value[0].id}}. All business data lives under a company.
  • Other path parameters — the entity's own id, e.g. customer_id, item_id, salesInvoice_id. Line-item ids (salesInvoiceLine_id etc.) are string keys and appear quoted in the path.
  • Request Body — a structured field for Post/Patch, plus an Override Request Body toggle and Request Body (Raw) text field. BC entities have many properties; Override Request Body with hand-written JSON is often the practical choice.
  • Additional Query Parameters — OData v4 system query options go here: $filter, $select, $expand, $top, $skip, $orderby. e.g. $filter = number eq 'C00010'.
  • Additional Headers — Update and Delete require an If-Match header. Set If-Match to * to update/delete unconditionally, or to the record's @odata.etag (from a prior Get) for optimistic concurrency. Without it BC returns 428 Precondition Required.
  • Forward All Headers — as on every connector.

Reading the response

Every action's result is at {{<stepReference>.response...}} (see Step Reference): {{<stepReference>.response.status}}, {{<stepReference>.response.statusText}}, {{<stepReference>.response.headers.<name>}}, and {{<stepReference>.response.data.<field>}} for the body. BC's OData v4 shapes:

  • A list — {{<stepReference>.response.data.value}} is the array (e.g. {{<stepReference>.response.data.value[0].displayName}}). Page with $top / $skip via Additional Query Parameters, or follow {{<stepReference>.response.data['@odata.nextLink']}} when present.
  • A single record / create / update — the entity's fields are directly under data, e.g. {{<stepReference>.response.data.id}} (GUID), {{<stepReference>.response.data.number}}, {{<stepReference>.response.data.displayName}}, plus {{<stepReference>.response.data['@odata.etag']}} — keep the etag to pass as If-Match on a later update.
  • A delete — 204 No Content; confirm with {{<stepReference>.response.status}}.
  • A bound action (the Microsoft.NAV.* operations — Post, Send, Cancel, Ship and Invoice, …) — usually 204, or the affected document; check {{<stepReference>.response.status}}.

A non-2xx response does not fail the step — it's returned with the real status code and BC's error body ({{<stepReference>.response.data.error.code}}, {{<stepReference>.response.data.error.message}}) under data.

Standard entity actions

For Items, Customers, Vendors, Sales Invoices, Sales Orders, Purchase Invoices (and the line-item entities), every module has:

  • List <entity> — GET /companies({company_id})/<entities>.
  • Post <entity> — POST /companies({company_id})/<entities>. Body: the entity's writable properties.
  • Get <entity> — GET /companies({company_id})/<entities>({<entity>_id}).
  • Patch <entity> — PATCH /companies({company_id})/<entities>({<entity>_id}). Requires If-Match.
  • Delete <entity> — DELETE /companies({company_id})/<entities>({<entity>_id}). Requires If-Match.

The module sections below note only what's extra.

Companies

  • List Companies — GET /companies. Returns {{<stepReference>.response.data.value}}; each company has id (the GUID you use as company_id everywhere else), name, displayName, systemVersion.
  • Get Company — GET /companies({company_id}).

This is the only module without a company_id requirement on List — run it first to discover the company GUID.

Items

Standard entity actions on /companies({company_id})/items, path parameter item_id. Key properties: number, displayName, type (Inventory / Service / Non-Inventory), unitPrice, unitCost, baseUnitOfMeasureId, itemCategoryId, inventory, blocked.

Customers

Standard entity actions on /companies({company_id})/customers, path parameter customer_id. Key properties: number, displayName, email, phoneNumber, taxRegistrationNumber, currencyCode, paymentTermsId, paymentMethodId, blocked, address (an object: street, city, state, countryLetterCode, postalCode).

Vendors

Standard entity actions on /companies({company_id})/vendors, path parameter vendor_id. Same property shape as Customers (number, displayName, email, address, currencyCode, paymentTermsId, blocked, …).

Sales Invoices

Standard entity actions on /companies({company_id})/salesInvoices, path parameter salesInvoice_id. Key properties: number, customerId (or customerNumber), invoiceDate, dueDate, currencyCode, status (Draft, Open, Paid, Canceled, Corrective), totalAmountIncludingTax. Create the header first, then add lines via Sales Invoice Lines.

Bound actions (all POST /companies({company_id})/salesInvoices({salesInvoice_id})/Microsoft.NAV.<action>, no body):

  • Post (postActionSalesInvoices) — post the draft invoice to the ledger.
  • Post and Send (postAndSendActionSalesInvoices) — post, then email it to the customer.
  • Send (sendActionSalesInvoices) — email an already-posted invoice.
  • Cancel (cancelActionSalesInvoices) / Cancel and Send (cancelAndSendActionSalesInvoices) — cancel a posted invoice (creates a corrective credit memo).
  • Make Corrective Credit Memo (makeCorrectiveCreditMemoActionSalesInvoices).

Sales Invoice Lines

Two ways to address lines — nested under an invoice, or flat:

  • Nested: GET|POST /companies({company_id})/salesInvoices({salesInvoice_id})/salesInvoiceLines and GET|PATCH|DELETE .../salesInvoiceLines('{salesInvoiceLine_id}').
  • Flat: GET|POST /companies({company_id})/salesInvoiceLines and GET|PATCH|DELETE /companies({company_id})/salesInvoiceLines('{salesInvoiceLine_id}') — use $filter = documentId eq <invoiceGuid> to scope the flat list.

Line properties: lineType (Item / Account / Comment / …), lineObjectNumber (the item number), quantity, unitPrice, discountPercent, taxCode, amountIncludingTax.

Sales Orders

Standard entity actions on /companies({company_id})/salesOrders, path parameter salesOrder_id. Key properties: number, customerId, orderDate, currencyCode, status, totalAmountIncludingTax, fullyShipped.

Bound action: Ship and Invoice (shipAndInvoiceActionSalesOrders, POST .../Microsoft.NAV.shipAndInvoice) — post a shipment and an invoice for the order in one call.

Sales Order Lines

Same nested/flat addressing as Sales Invoice Lines, under salesOrders / salesOrderLines, path parameter salesOrderLine_id. Extra properties over invoice lines: shippedQuantity, invoicedQuantity, shipmentDate.

Purchase Invoices

Standard entity actions on /companies({company_id})/purchaseInvoices, path parameter purchaseInvoice_id. Key properties: number, vendorId (or vendorNumber), vendorInvoiceNumber, invoiceDate, dueDate, currencyCode, status, totalAmountIncludingTax.

Bound action: Post (postActionPurchaseInvoices, POST .../Microsoft.NAV.post) — post the draft purchase invoice.

Purchase Invoice Lines

Same nested/flat addressing as the other line entities, under purchaseInvoices / purchaseInvoiceLines, path parameter purchaseInvoiceLine_id. Line properties mirror Sales Invoice Lines (lineType, lineObjectNumber, quantity, directUnitCost, discountPercent, amountIncludingTax).

Generic Request

Five actions — Generic GET / POST / PUT / PATCH / DELETE Request — for the parts of the automation API the dedicated actions don't cover: general ledger, journals, customer/vendor payments, bank accounts, dimensions, sales quotes, credit memos, aged reports, PDF documents, and so on.

  • path — required, relative to the base URL (.../api/v1.0), e.g. /companies(<company_id>)/salesQuotes, /companies(<company_id>)/customerPayments, /companies(<company_id>)/journals.
  • Request Body (Raw) — the JSON body for write methods. If-Match (via Additional Headers) is still required for PATCH / DELETE.

Example

Generic GET Request, path /companies(<company_id>)/salesInvoices, Additional Query Parameters $filter = status eq 'Open' and $orderby = invoiceDate desc — list open sales invoices (equivalent to List Sales Invoices with filtering).

Also applies here

Step Name

What it's for

Every step in a workflow gets a name — either one you set or a default based on the connector and action (e.g. "Get Order Details", "Send Welcome Email"). It's shown throughout the UI and in your execution history, and it's also the source for the step's Reference — a camelCase identifier auto-generated from the name (e.g. "Get Order Details" → getOrderDetails) — which is what you actually use in {{...}} expressions to read this step's output from later steps. See Step Reference.

Rules

  • Must be at least 2 characters, and 50 characters or fewer.
  • Must be unique within the workflow — reusing a name that's already taken will be rejected, with a suggested alternative (e.g. "Get Order Details 2").
  • Can't be empty.

Tips

  • Prefer a descriptive, human-readable name over a generic one — "Get Order Details" is easier to work with later than "HTTP Request 2", especially once a workflow has a dozen steps.
  • Renaming a step updates every reference to it elsewhere in the workflow automatically.

Step Reference

Syntax

Any input field can reference earlier data using {{expression}}. The expression is evaluated as JSONata — so simple dot-paths and more advanced queries (filters, functions) both work.

Referencing a step's output

Use the step's Reference — a camelCase identifier auto-generated from its Name (e.g. "Get Order Details" → getOrderDetails), shown read-only wherever the step's fields are configured — followed by the field path. Elsewhere in these docs this general pattern is written as {{<stepReference>.field.path}}:

{{getOrderDetails.response.data.id}}
{{getOrderDetails.response.status}}

The raw display name won't work here even though it's what you see in the UI — {{Get Order Details.response.data.id}} isn't valid, since a bare name containing spaces isn't a single JSONata identifier. Always use the camelCase Reference.

You can also reference steps by position instead of by reference:

{{steps[0].response.data.id}}

Referencing trigger data

{{trigger.headers.authorization}}
{{trigger.body.customerId}}
{{trigger.query.page}}
{{trigger.params.orderId}}
{{trigger.method}}
{{trigger.path}}

Referencing workflow variables

{{variables.myVariable}}

See Variables for the full list of variable types and more examples, including connection-type variables.

Referencing runtime variables

A separate, mutable namespace written by the Variable connector while a run is in progress — not the same as the workflow-level variables above:

{{runtimeVariables.myVariable}}

Notes

  • If an expression can't be resolved (a typo in a step name, a field that doesn't exist), it resolves to an empty string rather than failing the workflow — check your execution history if a value comes through blank.
  • Object values are automatically JSON-stringified when interpolated into a string field.

Execution Settings

Fire-and-forget

When enabled, the workflow doesn't wait for this step to complete before moving to the next one. Use it for steps whose result nothing downstream depends on — logging, analytics, notifications — so they don't add latency to the steps that matter.

Continue on error

When enabled, a failure in this step doesn't stop the workflow — execution continues to the next step. The failure is still recorded in the execution history; this just controls whether it's fatal.

Combine the two for steps that are genuinely optional to the outcome: fire-and-forget so they don't add latency, continue-on-error so a failure in them (e.g. an analytics endpoint being briefly down) doesn't take down an otherwise-successful workflow run.

Caching

What it does

When enabled, a step's result is cached for a configurable TTL (time-to-live, in seconds). If the step runs again with the same effective cache key before the TTL expires, the cached result is returned instead of re-running the step.

Configuring it

  • Enabled — turn caching on or off for this step.
  • TTL — how long (in seconds) a cached result stays valid.
  • Cache key template — an expression (supporting the same {{...}} step reference syntax used elsewhere) that determines what counts as "the same call". By default this is based on the step's resolved input; a custom template lets you cache more narrowly or broadly than that.

When to use it

Good candidates are steps that call something slow or rate-limited but return the same answer for the same input within a short window — a lookup against a rarely-changing external system, for example. Skip it for steps whose result must always be fresh (anything involving live inventory, pricing, or payment state).

Locking

What it does

When enabled, only one execution of this step (for a given lock key) can run at a time. If a second execution tries to run the same step while a lock is held, it waits until the lock is released or the hold period elapses.

Configuring it

  • Enabled — turn locking on or off for this step.
  • Lock key — an expression (supporting the same {{...}} step reference syntax used elsewhere) that determines what counts as "the same resource". By default the lock is scoped to the step itself; a custom key lets you lock per-customer, per-order, or any other identifier that needs serialized access.
  • Period — how long (in seconds) the lock is held before it's automatically released, in case an execution doesn't complete normally.

When to use it

Use it whenever concurrent executions could race on the same resource — e.g. two workflow runs both trying to update the same order's status at once. A lock key scoped to the order id ensures only one of them proceeds at a time.

Business Central — younifyd