{"title":"Business Central web services","url":"https://jonas-paprotka.de/docs/dev-itpro/webservices/web-services/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/web-services, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/web-services","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Compare the features of REST APIs, SOAP, and OData web services and know how to create and maintain these services.","date":"2024-02-28","meta":{"topic":"reference"},"outline":[{"level":1,"title":"Business Central web services","slug":"business-central-web-services","at":0,"chars":13139},{"level":2,"title":"Web service telemetry, performance, troubleshooting, and security","slug":"web-service-telemetry-performance-troubleshooting-and-security","at":1203,"chars":1832},{"level":3,"title":"Web service telemetry","slug":"web-service-telemetry","at":1432,"chars":399},{"level":3,"title":"Web service performance","slug":"web-service-performance","at":1831,"chars":252},{"level":3,"title":"Web service security","slug":"web-service-security","at":2083,"chars":324},{"level":3,"title":"Troubleshooting web services","slug":"troubleshooting-web-services","at":2407,"chars":410},{"level":3,"title":"Web services best practices","slug":"web-services-best-practices","at":2817,"chars":218},{"level":2,"title":"The OData standard","slug":"the-odata-standard","at":3035,"chars":1185},{"level":2,"title":"Compare REST APIs, SOAP, and OData web services","slug":"compare-rest-apis-soap-and-odata-web-services","at":4220,"chars":1445},{"level":2,"title":"REST API web services","slug":"rest-api-web-services","at":5665,"chars":481},{"level":2,"title":"OData web services","slug":"odata-web-services","at":6146,"chars":551},{"level":2,"title":"SOAP web services","slug":"soap-web-services","at":6697,"chars":796},{"level":2,"title":"Publish pages, queries, or codeunits as web services","slug":"publish-pages-queries-or-codeunits-as-web-services","at":7493,"chars":2581},{"level":3,"title":"Web services based on a page","slug":"web-services-based-on-a-page","at":7887,"chars":1452},{"level":3,"title":"Web services based on a codeunit","slug":"web-services-based-on-a-codeunit","at":9339,"chars":355},{"level":3,"title":"Web services based on a query","slug":"web-services-based-on-a-query","at":9694,"chars":380},{"level":2,"title":"Manage timezones in web services","slug":"manage-timezones-in-web-services","at":10074,"chars":418},{"level":2,"title":"Web Services and Regional Settings (for on-premises)","slug":"web-services-and-regional-settings-for-on-premises","at":10492,"chars":1035},{"level":2,"title":"Web Services in Multitenant Deployments (for on-premises)","slug":"web-services-in-multitenant-deployments-for-on-premises","at":11527,"chars":1079},{"level":2,"title":"Related information","slug":"related-information","at":12606,"chars":533}],"text":"# Business Central web services\nBusiness Central supports three types of web services: (REST) API, SOAP, and OData. Web services are a lightweight, industry-standard way to make application functionality available to various external systems and users. You can create and publish functionality as REST API web services for reading and/or writing data back to Business Central.\nUsing REST API web services is the recommended way to develop and consume web services. But you can also publish pages, codeunits, or queries as web services, or enhance a page web service by using an extension codeunit. When you publish Business Central objects as web services, they're immediately available on the network.\nAll Business Central web services are stateless and don't preserve the values of global variables or single-instance codeunits between calls.\n> IMPORTANT\n> Starting October, 2022, the use of access keys (Basic Auth) for web service authentication is deprecated and not supported<../upgrade/deprecated-features-platform#accesskeys> in Business Central online. We recommend that you use OAuth2 instead. See Using OAuth to Authorize Business Central Web Services<authenticate-web-services-using-oauth>.\n## Web service telemetry, performance, troubleshooting, and security\nWhen you work with web service integrations, you need to pay extra attention to the fundamental areas of telemetry, performance, troubleshooting, and security.\n### Web service telemetry\nAll calls to Business Central web services are logged to partner telemetry. Telemetry helps you to monitor which endpoints are being used and the category of the web service, like SOAP, OData, or (REST) API. You can also see possible failures, which are tracked in the HTTP status codes for the calls.\nFor more information web service telemetry, see: web-service-telemetry\n### Web service performance\nThe performance of web services (REST API, OData, or SOAP) depends on both the Business Central server endpoint and the consumer (the client).\nFor more information about web service performance, see web-service-performance.\n### Web service security\nSecurity is an important part of a solution involving web services. One reason is because the client calling the web service endpoint is likely not delivered by Microsoft. Another reason is because the interaction between the client and Business Central is over a network.\nSee web-service-security.\n### Troubleshooting web services\nTroubleshooting web service errors can be tricky because the root cause of the error can be in multiple places:\n It can be in the client that's calling the web service.\n It can be related to the network between the client and the web service endpoint.\n It can be in the code behind the web service endpoint.\nSee Troubleshooting web service errors<web-service-troubleshooting>.\n### Web services best practices\nApart from the articles mentioned previously, you might also want to learn more about best practices when working with web services in Business Central.\nSee web-services-best-practices.\n## The OData standard\nWeb services of type REST API and OData are both based on OData version 4. The OData standard is well suited for web service applications that require a uniform, flexible, general purpose interface for exposing create retrieve update delete \\(CRUD\\) operations on a tabular data model to clients. You can also use OData for applications that are primarily RPC-oriented by using unbound actions. OData supports Representational State Transfer \\(REST\\)-based data services.\nREST-based data services enable resources that are identified using Uniform Resource Identifiers \\(URIs\\) and defined in an abstract data model \\(EDM\\) to be published and edited by web clients within corporate networks and across the Internet using simple Hypertext Transfer Protocol \\(HTTP\\) messages. OData services are lightweight, with functionality often referenced directly in the URI.\nOData is used in other Microsoft products and technologies, for example:\n Microsoft Excel implements OData for its PowerQuery feature.\n Microsoft Power BI can read data from OData services.\n Microsoft SharePoint can expose its list-oriented data with OData.\nSee OData overview<odata-web-services>.\n## Compare REST APIs, SOAP, and OData web services\nDevelopers planning to create Business Central web services might need to decide which type of web service is better suited to their needs.\nThe following table shows how each type of web service is supported in Microsoft connectors.\nConnector|SOAP web services|OData web services|(REST) API web services\nPower BI|No|Yes (but considered a legacy method)|Yes (recommended)\nPower platform|No|No|Yes\nThe following table shows the types of objects you use in AL for each type of web service.\nObject|SOAP web services|OData web services|(REST) API web service\n-|-----------------------|------------------------|------------------------\nPages|Yes: Create, Read, Update, and Delete operations \\(CRUD\\)|Yes: Create, Read, Update, and Delete operations \\(CRUD\\)|Yes: Create, Read, Update, and Delete operations \\(CRUD\\)\nCodeunits|Yes|Yes (through OData unbound actions)|No, not yet\nQueries|No|Yes: Read-only|Yes: Read-only\nBusiness Central supports REST API and OData web services in addition to the SOAP web services, which have been available since Microsoft Dynamics NAV 2009.\n> TIP\n> If the same code needs to run both in the UI but also in the background (in a scheduled task or with a job queue entry) or in a web service call (SOAP/OData/API), then use `if GuiAllowed() then` calls to encapsulate AL code that interact with the user. See ../developer/methods-auto/system/system-guiallowed-method.\n## REST API web services\nThe Business Central API stack is optimized for performance and is the preferred way to integrate Business Central with external systems. Business Central also comes with an extensive list of built-in (REST) APIs that requires no code and minimal setup to use. You can also develop your own custom APIs using the AL object types API pages and API queries.\nFor more information about REST API web services, see REST API web services overview<api-overview>.\n## OData web services\nWith OData web services, you can publish pages, codeunits, and queries as ODataV4 web service endpoints.\nSOAP web services expose a Web Services Description Language (WSDL) document. OData web services expose an Entity Data Model XML (EDMX) document containing metadata for all published web services. The OData implementation in Business Central also supports the JSON format, a less verbose format that might perform better in low-bandwidth environments.\nFor more information about OData web services, see publish-web-service.\n## SOAP web services\nWith SOAP web services, you can publish pages and codeunits as SOAP web service endpoints. The most common type of messaging pattern in SOAP is the Remote Procedure Call (RPC). With RPC, one network node \\(the client\\) sends a request message to another node \\(the server\\), and the server sends a response message to the client.\n> IMPORTANT\n> SOAP is replaced by OData V4. The support for SOAP endpoints will be removed in a later release. We recommend that you migrate integrations to OData V4 or REST API web services as soon as possible. For codeunits published as SOAP web services, you can replace most of them with a similar OData web service using OData unbound actions.\nFor more information about SOAP web services, see SOAP web service overview<soap-web-services>.\n## Publish pages, queries, or codeunits as web services\nBefore REST APIs were available in Business Central, publishing pages, queries, or codeunits as OData or SOAP based web services was the only way to develop integrations to Business Central.\nThe Business Central REST API stack is optimized for performance and is now the preferred way to integrate Business Central with external systems.\n### Web services based on a page\nYou can publish any page as a web service, but page concepts such as FactBoxes aren't included in the web service result. The developer of the page might not know that the page is published as a web service, so they might use AL code to calculate values for the FactBox. This situation is one reason why REST APIs are the recommended and preferred option over publishing a page as a web service.\nPage-based web services offer built-in optimistic concurrency management. Each operation call in a page-based web service is managed as a single transaction.\nYou can use extension codeunits to extend the default set of operations that are available on a page. Adding an extension codeunit to a page is useful if you want to perform operations other than the standard Create, Read, Update, and Delete operations. The benefit of adding an extension codeunit to a page is that you can make the web service complete by adding operations that are logical to that service. Those operations can use the same object identification principle as the basic page operations.\nWhen you expose a page as an OData web service, you can query that data to return a service metadata \\(EDMX\\) document, an AtomPub document, or a JavaScript Object Notation \\(JSON\\) document. You can also write back to the database if the exposed page is writable. See odata-web-services.\nFor more information about page web services, see publish-web-service.\n### Web services based on a codeunit\nCodeunit web services provide you with the most control and flexibility. When you expose a codeunit as a web service, all functions defined in the codeunit are exposed as operations. Both OData and SOAP can be used with codeunit web services.\nFor more information about codeunit web services, see publish-web-service.\n### Web services based on a query\nWhen you expose a Business Central query as an OData web service, you can query that data to return a service metadata \\(EDMX\\) document or an AtomPub document. For more information about how to create and use Business Central queries, see ../developer/devenv-query-object.\nFor more information about query web services, see publish-web-service.\n## Manage timezones in web services\nFor fields of type datetime, the time part of the data needs clarification when the Business Central environment is located in a different timezone than the connect app (the one that consumes data from Business Central web services).\nTo learn more about how timezones work in the Business Central web services stack for this type of data, see managing-time-zones-with-web-services.\n## Web Services and Regional Settings (for on-premises)\nData is formatted according to the value of the Services Language setting for the relevant Business Central Server instance. The default value is en-us. This means that Business Central Server interprets all incoming data as the specified culture, such as dates and amounts.\nIf you know that the Services Language setting is always en-us, for example, your code can be based on that assumption. In a multilanguage environment, you see more predictable transformations of data if data that is transmitted through web services is in a consistent culture.\nSimilarly, you can use the ServicesOptionFormat setting to specify how Business Central Server must understand option values. If you set the ServicesOptionFormat setting to OptionString, Business Central Server understand option values as the name of the option value, which is always en\\-us. If you set the setting to OptionCaption, web service data is interpreted in the language specified by the Services Language setting.\n## Web Services in Multitenant Deployments (for on-premises)\nIf your Business Central solution is used in a multitenant deployment architecture, you must make sure that any code that generates or consumes a web service specifies the relevant tenant. Web services are set up in the application, but typically you want to consume company-specific and tenant-specific data.\nIf you use the GETURL method, the generated URL is automatically applied to the user's tenant ID. See ../developer/methods-auto/system/system-geturl-clienttype-string-objecttype-integer-recordref-boolean-method.\nThe URL for accessing a web service in a multitenant deployment must specify the tenant ID in one of two ways: As a query parameter, or as a host name. If you use host names for tenants, the host name must be specified as an alternative ID.\nFor example, the following URL consumes the Customer ODATA web service for a specific tenant:\n```\nhttps://localhost:7048/BC230/ODataV4/Company('CRONUS-International-Ltd.')/Customer?Tenant=Tenant1\n```\nSee ../deployment/multitenant-deployment-architecture.\n## Related information\n web-service-telemetry\n web-service-performance\n web-service-security\n Troubleshooting web service errors<web-service-troubleshooting>\n web-services-best-practices\n OData overview<odata-web-services>\n REST API web services overview<api-overview>\n SOAP web service overview<soap-web-services>\n publish-web-service\n Multitenant Deployment Architecture (on-premises)<../deployment/multitenant-deployment-architecture>\n Configuring Business Central Server (on-premises)<../administration/configure-server-instance>"}