> For the complete documentation index, see [llms.txt](https://docs.digibee.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digibee.com/documentation/connectors-and-triggers/connectors/web-protocols/odata.md).

# OData

The **OData** connector enables integrations with any service compliant with [OData](https://www.odata.org/) (v4 or v2), such as SAP, Microsoft Dynamics 365, Business Central, Salesforce, and public OData feeds, extending the platform’s REST engine.

It builds standards-based requests to query and manipulate an OData **entity set** (collection), including CRUD, server-driven query options (`$filter`, `$select`, `$orderby`, `$top`, `$skip`, `$expand`, `$count`), bound/unbound **actions and functions**, and `$batch`.

Use this connector when:

* You need to read or write data in an OData service that has no dedicated Digibee connector.
* You want explicit control over the OData request (entity set, key, query options, actions, `$batch`).
* You are integrating SAP OData / SAP S/4HANA, Business Central, or a custom OData API.

{% hint style="info" %}

#### **OData vs. vendor-specific connectors**

For Microsoft Dynamics 365, use the [**Dynamics 365**](/documentation/connectors-and-triggers/connectors/enterprise-applications/dynamics-365.md) (Customer Engagement/Dataverse) or [**Dynamics 365 Finance & Operations**](/documentation/connectors-and-triggers/connectors/enterprise-applications/dynamics-365-finance-and-operations.md) connector instead. Both are specialized versions of the OData engine with product-specific defaults and guided entity discovery.
{% endhint %}

## **Concepts**

The terms below appear throughout the connector's parameters, so it helps to understand them before configuring a request. Each concept maps to a specific field you'll fill in later.

<table><thead><tr><th width="160">Term</th><th>Meaning</th></tr></thead><tbody><tr><td><strong>Entity Set</strong></td><td>The collection you're addressing, for example <code>Customers</code>. It becomes the first path segment: <code>/Customers</code>.</td></tr><tr><td><strong>Entity Key</strong></td><td>Identifies a single record. It can be a single value (<code>42</code>, <code>guid'…'</code>) or a <strong>composite</strong> key (<code>id1=val1,id2=val2</code>). Rendered as <code>/Customers(42)</code> or <code>/Customers(id1=val1,id2=val2)</code>.</td></tr><tr><td><strong>Query options</strong></td><td>Server-driven parameters: <code>$filter</code>, <code>$select</code>, <code>$orderby</code>, <code>$top</code>, <code>$skip</code>, <code>$expand</code>, and <code>$count</code>.</td></tr><tr><td><strong>Action / Function</strong></td><td>Server-side operations. A <strong>bound</strong> operation targets a specific entity or collection; an <strong>unbound</strong> operation applies to the service as a whole. Actions use <code>POST</code>; functions use <code>GET</code>.</td></tr><tr><td><strong>OData version</strong></td><td><code>4.0</code> (default) or <code>2.0</code>. It determines the request headers and how the response is parsed: <code>value</code>, <code>@odata.count</code>, and <code>@odata.nextLink</code> for v4, or <code>d</code> and <code>d.results</code> for v2.</td></tr></tbody></table>

## **Parameters**

The table below lists all configuration parameters for the connector. Parameters that support [Double Braces expressions](/documentation/connectors-and-triggers/double-braces/overview.md) are marked with ✅ in the **Supports DB** column.

{% tabs %}
{% tab title="General" %}

<table><thead><tr><th width="112">Parameter</th><th width="231">Description</th><th width="100">Type</th><th width="110">Supports DB</th><th width="150">Default</th></tr></thead><tbody><tr><td><strong>Alias</strong></td><td>A name for this connector's output, so you can reference it later in the flow with <a href="/pages/cijmbAfZNYu7oJBb7Kd7#referencing-previous-steps-using-previous-steps-access">Double Braces</a>.</td><td>String</td><td>✅</td><td><code>odata-01</code></td></tr><tr><td><strong>Fail On Client Error (4xx)</strong></td><td>Interrupt the pipeline on a 4xx response.</td><td>Boolean</td><td>❌</td><td><code>false</code></td></tr><tr><td><strong>Fail On Server Error (5xx)</strong></td><td>Interrupt the pipeline on a 5xx response.</td><td>Boolean</td><td>❌</td><td><code>false</code></td></tr></tbody></table>
{% endtab %}

{% tab title="Authentication" %}

<table><thead><tr><th width="112">Parameter</th><th width="200">Description</th><th width="83">Type</th><th width="81">Supports DB</th><th width="120">Default</th><th width="125">Visible when</th></tr></thead><tbody><tr><td><strong>Base URL</strong></td><td>OData service root URL. Trailing slash is normalized.</td><td>String</td><td>✅</td><td><code>https://services.odata.org/V4/Northwind/Northwind.svc</code></td><td>—</td></tr><tr><td><strong>Use Dynamic Account</strong></td><td>If enabled, the connector resolves the account at runtime. If disabled, it uses the account configured statically below.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td>—</td></tr><tr><td><strong>Scoped</strong></td><td>If enabled, isolates the stored account from other sub-processes. Not available for accounts referenced in headers or in the request body. To learn more, read the <a href="/spaces/jvO5S91EQURCEhbZOuuZ/pages/cbkYqH3fxzeL7zOKNawz">Dynamic Accounts documentation</a>.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td><strong>Use Dynamic Account</strong> is enabled</td></tr><tr><td><strong>Account Name</strong></td><td>Name of the account defined in the <a href="/pages/0kxlZ011XP4A2T43v9kh"><strong>Store Account</strong></a> connector.</td><td>String</td><td>✅</td><td>N/A</td><td><strong>Use Dynamic Account</strong> is enabled</td></tr><tr><td><strong>Account</strong></td><td>Account used to authenticate the request. Supported types: <strong>Azure Key</strong>, <strong>Basic</strong>, <strong>API Key</strong>, <strong>OAuth Bearer</strong>, <strong>OAuth 2.0</strong>, <strong>AWS V4</strong>, <strong>custom auth header</strong> (and others available in the platform). Learn more about <a href="/spaces/jvO5S91EQURCEhbZOuuZ/pages/fS1QLzAg8rGSSJFwtrvy">Accounts</a>.</td><td>Account</td><td>—</td><td>N/A</td><td><strong>Use Dynamic Account</strong> is disabled</td></tr></tbody></table>

{% hint style="info" %}
**Azure Key** performs the OAuth 2.0 client-credentials flow with Azure AD (Microsoft Entra ID) and injects the resulting token as a `Bearer` header.

The token is cached per combination of client, tenant, and scope.
{% endhint %}
{% endtab %}

{% tab title="OData API" %}

### **Base parameters**

These parameters define the foundation of the request, the entity set, OData version, and operation. The operation you choose here determines which additional parameters appear next.

<table><thead><tr><th width="112">Parameter</th><th width="231">Description</th><th width="100">Type</th><th width="110">Supports DB</th><th width="150">Default</th></tr></thead><tbody><tr><td><strong>OData Version</strong></td><td><code>4.0</code> or <code>2.0</code>. Determines request headers and response parsing.</td><td>Select</td><td>❌</td><td><code>4.0</code></td></tr><tr><td><strong>Entity Set</strong></td><td>OData collection name, such as <code>Customers</code>.</td><td>String</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Operation</strong></td><td>The action to perform. It shapes the request. See the supported operations below.</td><td>Select</td><td>❌</td><td><code>Query</code></td></tr></tbody></table>

#### **Supported operations**

The **Operation** parameter maps to an OData request as follows:

<table><thead><tr><th width="112">Operation</th><th width="105">HTTP</th><th width="148">Path</th><th width="124">Body</th><th>Notes</th></tr></thead><tbody><tr><td><strong>Batch</strong></td><td><code>POST</code></td><td><code>/$batch</code></td><td>multipart/JSON</td><td>Batches multiple operations in one request.</td></tr><tr><td><strong>Create</strong></td><td><code>POST</code></td><td><code>/{EntitySet}</code></td><td>JSON</td><td>Creates a record.</td></tr><tr><td><strong>Custom Query</strong></td><td><code>GET</code></td><td><code>/{EntitySet}?{$query}</code></td><td>—</td><td>Same as Query. Use it when combining raw and structured query parameters.</td></tr><tr><td><strong>Delete</strong></td><td><code>DELETE</code></td><td><code>/{EntitySet}({key})</code></td><td>—</td><td>Deletes a record.</td></tr><tr><td><strong>Get by ID</strong></td><td><code>GET</code></td><td><code>/{EntitySet}({key})</code></td><td>—</td><td>Reads a single record by key.</td></tr><tr><td><strong>Invoke Action</strong></td><td><code>POST</code></td><td><code>/{EntitySet}({key})/{Action}</code> or <code>/{Action}</code></td><td>JSON</td><td>Invokes a bound action (with key and entity set) or an unbound action.</td></tr><tr><td><strong>Invoke Function</strong></td><td><code>GET</code></td><td><code>/{EntitySet}({key})/{Function}</code> or <code>/{Function}</code></td><td>—</td><td>Invokes a bound or unbound function.</td></tr><tr><td><strong>Query</strong></td><td><code>GET</code></td><td><code>/{EntitySet}?{$query}</code></td><td>—</td><td>Reads the collection with query options.</td></tr><tr><td><strong>Update</strong></td><td><code>PATCH</code>/<code>PUT</code></td><td><code>/{EntitySet}({key})</code></td><td>JSON</td><td>Updates a record, partially (<code>PATCH</code>) or fully (<code>PUT</code>).</td></tr></tbody></table>

### **Common parameters**

Like the base parameters above, these apply no matter which operation you choose. They're grouped here for clarity, even though they appear after the operation-specific fields in the connector's configuration.

<table><thead><tr><th width="112">Parameter</th><th width="231">Description</th><th width="100">Type</th><th width="110">Supports DB</th><th width="150">Default</th></tr></thead><tbody><tr><td><strong>Output Format</strong></td><td>Controls the shape of the response returned to the pipeline. <strong>Values Only</strong> unwraps and returns only the <code>value</code> array. <strong>Full Response</strong> returns the entire response, including <code>@odata.*</code> fields. <strong>Single Entity</strong> returns the first or only entity.</td><td>Select</td><td>❌</td><td><code>Values Only</code></td></tr><tr><td><strong>Headers</strong></td><td>Additional request headers, as key/value pairs.</td><td>Key/Value</td><td>✅</td><td>N/A</td></tr></tbody></table>

### **Operation-specific parameters**

The remaining parameters only appear for certain operations, grouped below by purpose.

**Entity Key** — used by **Delete**, **Get by ID**, **Invoke Action**, **Invoke Function**, and **Update**.

<table><thead><tr><th width="112">Parameter</th><th width="231">Description</th><th width="100">Type</th><th width="110">Supports DB</th><th width="150">Default</th></tr></thead><tbody><tr><td><strong>Entity Key</strong></td><td>Single or composite key.</td><td>String</td><td>✅</td><td>N/A</td></tr></tbody></table>

**Action / Function Name** — used by **Invoke Action** and **Invoke Function**.

<table><thead><tr><th width="112">Parameter</th><th width="231">Description</th><th width="100">Type</th><th width="110">Supports DB</th><th width="150">Default</th></tr></thead><tbody><tr><td><strong>Action / Function Name</strong></td><td>OData action or function name. Bound when an <strong>Entity Set</strong> is set, unbound otherwise.</td><td>String</td><td>✅</td><td>N/A</td></tr></tbody></table>

**Body** — used by **Batch**, **Create**, **Invoke Action**, and **Update**.

<table><thead><tr><th width="112">Parameter</th><th width="231">Description</th><th width="100">Type</th><th width="110">Supports DB</th><th width="150">Default</th></tr></thead><tbody><tr><td><strong>Body</strong></td><td>JSON payload for Create and Update, action parameters for Invoke Action, or the <code>$batch</code> payload.</td><td>JSON</td><td>✅</td><td><code>{}</code></td></tr></tbody></table>

**Query parameters** — used by **Custom Query** and **Query**.

<table><thead><tr><th width="112">Parameter</th><th width="231">Description</th><th width="100">Type</th><th width="110">Supports DB</th><th width="150">Default</th></tr></thead><tbody><tr><td><strong>Filter (<code>$filter</code>)</strong></td><td>OData filter expression, for example <code>Age gt 18 and City eq 'NY'</code>.</td><td>String</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Select (<code>$select</code>)</strong></td><td>Comma-separated fields to include in the response.</td><td>String</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Order By (<code>$orderby</code>)</strong></td><td>Sorts the results by one or more properties, in ascending or descending order. For example, <code>Name asc, Created desc</code>.</td><td>String</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Expand (<code>$expand</code>)</strong></td><td>Related entities to include inline.</td><td>String</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Top (<code>$top</code>)</strong></td><td>Maximum number of records to return. No artificial cap.</td><td>Number</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Skip (<code>$skip</code>)</strong></td><td>Records to skip (pagination).</td><td>Number</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Include Count (<code>$count</code>)</strong></td><td>Include the total count in the response.</td><td>Boolean</td><td>❌</td><td><code>false</code></td></tr></tbody></table>
{% endtab %}

{% tab title="Advanced Settings" %}

<table><thead><tr><th width="112">Parameter</th><th width="231">Description</th><th width="83">Type</th><th width="81">Supports DB</th><th width="100">Default</th><th width="125">Visible when</th></tr></thead><tbody><tr><td><strong>Request Timeout (seconds)</strong></td><td>Maximum time for the HTTP request.</td><td>Number</td><td>❌</td><td><code>30</code></td><td>—</td></tr><tr><td><strong>Custom Query String</strong></td><td>Raw extra query parameters appended verbatim (for example, <code>cross-company=true</code>).</td><td>String</td><td>✅</td><td>N/A</td><td>—</td></tr><tr><td><strong>Update Method</strong></td><td><code>PATCH</code> for a partial update, or <code>PUT</code> for a full replacement.</td><td>Select</td><td>❌</td><td><code>PATCH</code></td><td>Operation is <strong>Update</strong></td></tr></tbody></table>
{% endtab %}

{% tab title="Documentation" %}

<table><thead><tr><th width="112">Parameter</th><th width="231">Description</th><th width="100">Data type</th><th width="110">Supports DB</th><th width="150">Default value</th></tr></thead><tbody><tr><td><strong>Documentation</strong></td><td>Optional field to describe the connector configuration and any relevant business rules.</td><td>String</td><td>❌</td><td>N/A</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## **Response handling**

* **OData v4:** The connector reads the collection from `value`, the total count from `@odata.count`, and pagination links from `@odata.nextLink`.
* **OData v2:** The connector reads the collection from `d.results` (or `d`).
* **Output Format:** Determines which part of this response reaches the pipeline. See the [**Output Format**](#common-parameters) parameter in OData API for the available values.

## **Examples**

### **Query with filter and select (v4)**

**Input** (connector parameters):

```
Base URL   = https://services.odata.org/V4/Northwind/Northwind.svc
Entity Set = Products
Operation  = Query
Select     = ProductName,UnitPrice
Filter     = UnitPrice gt 20
Top        = 2
```

**Output** (when the **Output Format** is set to `Values Only`):

```json
[
  { "ProductName": "Chai", "UnitPrice": 21.0 },
  { "ProductName": "Chang", "UnitPrice": 25.0 }
]
```

### **Create**

```
Entity Set = Customers
Operation  = Create
Body       = { "CompanyName": "Acme", "Country": "US" }
```

### **Invoke a bound action**

```
Entity Set  = accounts
Entity Key  = 00000000-0000-0000-0000-000000000001
Operation   = Invoke Action
Action Name = Recalculate
Body        = { }
```

**Resulting request:**

```html
POST /accounts(00000000-0000-0000-0000-000000000001)/Recalculate
```

## **Known limitations**

* The connector doesn't paginate automatically. To retrieve additional pages, follow `@odata.nextLink` yourself (for example, with a Loop) or control paging manually with `$top` and `$skip`.
* `$batch` payloads must be well-formed according to the target service's OData version.
* Entity and field auto-discovery from `$metadata` is available only in the guided Dynamics connectors. In the generic OData connector, Entity Set is a free-text field.

## **Common errors**

<table><thead><tr><th width="145">Status</th><th>Cause</th></tr></thead><tbody><tr><td><code>400</code></td><td>Malformed <code>$filter</code> expression or invalid key syntax.</td></tr><tr><td><code>401</code> / <code>403</code></td><td>Missing or invalid account credentials, or insufficient scope for the request.</td></tr><tr><td><code>404</code></td><td>Wrong entity set name or key.</td></tr></tbody></table>

Enable **Fail On Client Error (4xx)** or **Fail On Server Error (5xx)** to have the connector stop the pipeline when these errors occur.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.digibee.com/documentation/connectors-and-triggers/connectors/web-protocols/odata.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.