Skip to content
Skills Library
Programming · Building & coding

d365-webapi

/d365-webapi

Correct Dataverse Web API (OData v4) requests in any language - TypeScript, JavaScript, C#, PowerShell, Python or raw HTTP. Covers paging with odata.maxpagesize and @odata.nextLink, FetchXML paging cookies, $select/$filter/$expand, formatted values and annotations, setting lookups with @odata.bind (including customer and owner polymorphic lookups), upsert with alternate keys, If-Match/ETag concurrency, $batch and the bulk messages. Use this skill whenever code calls /api/data/v9.x, builds an OData query against Dynamics 365 or Dataverse, gets "An undeclared property was found in the payload",

Repository
d365-skills ↗
Licence
MIT
Last repository change
30.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
10
Deprecation

No signals detected. Repository changed on 30.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Correct Dataverse Web API (OData v4) requests in any language - TypeScript, JavaScript, C#, PowerShell, Python or raw HTTP. Covers paging with odata.maxpagesize and @odata.nextLink, FetchXML paging cookies, $select/$filter/$expand, formatted values and annotations, setting lookups with @odata.bind (including customer and owner polymorphic lookups), upsert with alternate keys, If-Match/ETag concurrency, $batch and the bulk messages. Use this skill whenever code calls /api/data/v9.x, builds an OData query against Dynamics 365 or Dataverse, gets "An undeclared property was found in the payload",

Triggers from the description

An undeclared property was found in the payload
Original author description

Correct Dataverse Web API (OData v4) requests in any language - TypeScript, JavaScript, C#, PowerShell, Python or raw HTTP. Covers paging with odata.maxpagesize and @odata.nextLink, FetchXML paging cookies, $select/$filter/$expand, formatted values and annotations, setting lookups with @odata.bind (including customer and owner polymorphic lookups), upsert with alternate keys, If-Match/ETag concurrency, $batch and the bulk messages. Use this skill whenever code calls /api/data/v9.x, builds an OData query against Dynamics 365 or Dataverse, gets "An undeclared property was found in the payload",

How it works

  1. Reading
  2. Writing
  3. Errors to handle on every call
  4. Output
  5. References in this skill
  6. Sources (Microsoft Learn)
Original SKILL.md headings · 80 lines, 621 words
SKILL.md preview
---
name: d365-webapi
description: Correct Dataverse Web API (OData v4) requests in any language - TypeScript, JavaScript, C#, PowerShell, Python or raw HTTP. Covers paging with odata.maxpagesize and @odata.nextLink, FetchXML paging cookies, $select/$filter/$expand, formatted values and annotations, setting lookups with @odata.bind (including customer and owner polymorphic lookups), upsert with alternate keys, If-Match/ETag concurrency, $batch and the bulk messages. Use this skill whenever code calls /api/data/v9.x, builds an OData query against Dynamics 365 or Dataverse, gets "An undeclared property was found in the payload", only returns 5,000 rows, writes an integration or sync with Dataverse, or uses Xrm.WebApi - even if the user just says "pull the accounts from Dynamics".
---

# Dataverse Web API, done right

Most Web API bugs are silent: the call succeeds and returns the wrong amount of data, or writes a
lookup to nowhere. The rules below target those silent failures first.

## Reading

1. **Always `$select`.** Without it you get every column, which is slow and can time out.
   The primary key comes back anyway.
2. **Page with the header, not with `$top`.** Send `Prefer: odata.maxpagesize=N` (N up to 5,000)
   and follow `@odata.nextLink` until it is absent. `$skip` is not supported. `$top` together with
   maxpagesize is ignored.
3. **Do not touch the nextLink.** Use it exactly as returned, with the same maxpagesize. The
   `$skiptoken` inside is opaque.
4. **Order deterministically.** Include a unique column (the primary key) at the end of `$orderby`.
   Paging over a non-unique sort can skip or repeat rows.
5. **FetchXML paging:** use `count`, `page` and the returned `paging-cookie`. Never combine with
   `top`. Simple paging (no cookie) stops at 50,000 rows. Elastic tables page at 500.
6. **Ask for annotations when you show values to people:**
   `Prefer: odata.include-annotations="*"` returns `@OData.Community.Display.V1.FormattedValue`
   for choices, lookups, money and dates. Do not rebuild option labels by hand.
7. **Read lookups through `_name_value`.** For polymorphic lookups (`customerid`, `ownerid`,
   `regardingobjectid`) also read `@Microsoft.Dynamics.CRM.lookuplogicalname` to know the table.
8. **`$count=true` caps at 5,000.** For larger totals use an aggregate query.

## Writing

1. **Set lookups with the single-valued navigation property + `@odata.bind`:**
   `"parentcustomerid_account@odata.bind": "/accounts(<guid>)"`. The navigation property name is
   case-sensitive and often differs from the column name. Polymorphic lookups have one property per
   target table (`parentcustomerid_account`, `parentcustomerid_contact`). Confirm the name in
   `$metadata` or in the relationship's `ReferencingEntityNavigationPropertyName`. Never guess.
2. **Clear a lookup** by sending the navigation property (without `@odata.bind`) as `null`, or
   `DELETE .../navprop/$ref`.
3. **Update vs upsert is one header.** `PATCH` with `If-Match: *` is a pure update (404 if missing).
   `PATCH` without it is an upsert. `If-None-Match: *` makes it create-only (412 if it exists).
4. **Upsert by alternate key** in the URL: `/contoso_things(contoso_externalid='A-42')`. Do not repeat
   the key columns in the body.
5. **Optimistic concurrency:** send the `@odata.etag` you read in `If-Match`. A 412 means someone
   changed the row. Re-read and decide, do not blindly retry.
6. **Send only changed columns.** Every column in the body counts as "changed" for plug-in filtering
   attributes, flow triggers and auditing.
7. **Bulk:** prefer `CreateMultiple`/`UpdateMultiple`/`UpsertMultiple` for tables that support them
   (each item needs `@odata.type`). One bad record fails the whole call, so validate first.
   Otherwise use `$batch` (up to 1,000 operations, start with ~10) with parallel requests.
   Change sets are atomic. Elastic tables do not honor that atomicity.

## Errors to handle on every call

| Status | Meaning | Do |
|---|---|---|
| 429 | Service protection limit | Wait `Retry-After` seconds, then retry. See `d365-limits-performance`. |
| 412 | ETag or If-None-Match precondition failed | Re-read, merge or report. |
| 404 on PATCH with If-Match | Row gone | Do not recreate silently. |
| 400 "undeclared property" | Wrong navigation property name | Look it up in `$metadata`. |

## Output

When writing or fixing code: return the corrected request (method, URL, headers, body) and the
client code, with paging and 429 handling included. Never put a real org URL, client secret or
token in examples. Read them from configuration.

## References in this skill

- `references/http-cookbook.md` - copy-ready requests: paging loop, lookups, upsert, ETag, batch, bulk.

## Sources (Microsoft Learn)

- Page results with OData: https://learn.microsoft.com/power-apps/developer/data-platform/webapi/query/page-results
- Page results with FetchXML: https://learn.microsoft.com/power-apps/developer/data-platform/fetchxml/page-results
- Select columns and lookup annotations: https://learn.microsoft.com/power-apps/developer/data-platform/webapi/query/select-columns
- Associate and disassociate rows: https://learn.microsoft.com/power-apps/developer/data-platform/webapi/associate-disassociate-table-rows
- Multi-table lookups: https://learn.microsoft.com/power-apps/developer/data-platform/webapi/multitable-lookup
- Upsert a table row: https://learn.microsoft.com/power-apps/developer/data-platform/use-upsert-insert-update-record
- Conditional operations (ETag): https://learn.microsoft.com/power-apps/developer/data-platform/webapi/perform-conditional-operations-using-web-api
- Bulk operation messages: https://learn.microsoft.com/power-apps/developer/data-platform/bulk-operations
- Batch operations: https://learn.microsoft.com/power-apps/developer/data-platform/webapi/execute-batch-operations-using-web-api
- Web API client errors: https://learn.microsoft.com/troubleshoot/power-platform/dataverse/dataverse-web-api-and-sdk/web-api-client-errors
Files in this package (2)
  • SKILL.md 6 KB
  • references/http-cookbook.md 4 KB

Versions

The database has no other skills named d365-webapi.

Database snapshot: 13.11.2026 · package version 5e4dfef4be06 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100odata
    OData 4.x covering Entity Data Model, system query options ($filter, $select, $expand, $orderby, $apply), CSDL metadata, batch requests, functions/actions, and Microsoft/SAP ecosystem integration. Use for \"OData\", \"$filter\", \"$select\", \"$expand\", \"$orderby\",…
  • 100dataverse-web-api
    Use when programmatically creating, modifying, or querying Dataverse schema and metadata via the Web API (OData v4.0). Covers table/column/relationship definitions, solution ALM, form and view XML construction, app module composition, global option sets, business rules, Custom…
  • 100dataverse-data
    Record-level writes to Microsoft Dataverse tables with the Python SDK, the dataverse CLI, or MCP tools: create, update, delete, upsert with alternate keys, bulk CreateMultiple/UpsertMultiple, CSV import, multi-table foreign-key loads, DataFrame write-back, and schema-driven…
  • 90data-operations
    Use for Dataverse row/record DATA and queries - create, read, update, upsert, or delete rows, seed or sync reference/config data, and design and run queries. Trigger on "create a record/row", "read/retrieve this record", "get the value of a field on a row", "list/query the rows…
  • 100dataverse-query
    Reading and analyzing Microsoft Dataverse records with the Python SDK, the dataverse CLI, or MCP tools: filtered reads, paging, lookups and $expand, SQL and FetchXML joins and aggregates, $apply, QueryBuilder, pandas DataFrames, and Jupyter notebook exploration. USE FOR: query…
  • 95integrate-webapi
    Integrates Power Pages Web API into a site's frontend code with proper permissions and deployment. Orchestrates the full integration lifecycle: code integration, table permissions setup, and deployment for Dataverse CRUD operations. Also supports PAC-downloaded non-SPA sites by…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.