Use Microsoft Dynamics 365 web services

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Web services provide APIs that you’ll use when you write programs for Microsoft Dynamics 365 (online & on-premises). This topic introduces available web services and provides basic information to understand and compare them.

In this topic

Web API

Organization service

Organization Data service

Discovery web services

Deployment web service

Web API

The Web API is new for Microsoft Dynamics 365 (online & on-premises) and will provide parity with the Organization service.

Compared to the Organization service, the Web API provides better compatibility across a wide variety of programming languages, platforms, and devices. The Web API implements the OData (Open Data Protocol) v4. OData is an OASIS standard for building and consuming RESTful APIs over rich data sources. You can learn more at the OData protocol and the OASIS standard websites.

Because the Web API is built on open standards, you aren’t required to use client libraries specific to Microsoft Dynamics 365. You can choose to compose HTTP requests for specific operations or use third-party libraries to generate classes for whatever language or platform you want to use. View a list of available libraries.

Eventually the Web API will replace the Organization service and Organization Data service but both of these existing web services will be available to enable a gradual transition to a single Web API. The Web API should be your first choice for new development that will support Microsoft Dynamics 365 and future versions of Microsoft Dynamics 365 (online). Use the Web API for any projects that access Microsoft Dynamics 365 data with code that doesn’t run on the server, including XmlHttpRequests from web resources and form scripts that run in Microsoft Dynamics 365 application clients. At this time you can’t easily use the Web API for code that runs on the server, such as in plug-ins or workflow assemblies.

More information: Use the Microsoft Dynamics 365 Web API.

Organization service

The Organization service, also sometimes known as the “SOAP endpoint,” has been available since Microsoft Dynamics CRM 2011. It’s the web service that most developers working with Microsoft Dynamics 365 are already familiar with. The Organization service is optimized for use with .NET. The Microsoft Dynamics 365 SDK provides a set of assemblies and tools to allow you to generate strongly typed classes and proxies that streamline the development process and enjoy a better development experience using Microsoft Visual Studio. If you’re a .NET developer with no requirements to support other platforms, you don’t have to move to the Web API right away. You’ll need to use the Organization service to support any functionality you want to deploy to organizations using versions of Microsoft Dynamics 365 released before Microsoft Dynamics 365.

Business logic that runs in plug-ins or workflow assemblies on the server expect to use the Organization service. Input and output parameters use specific classes defined with the assemblies that support the Organization service.

More information: Use the Microsoft Dynamics 365 Organization service

Organization Data service

The Organization Data service, also sometimes known as the “OData” or “REST” endpoint has also been available since Microsoft Dynamics CRM 2011. This service implemented the OData v2 standard. While this service will continue to be available as-is for years to come, we are deprecating it with Microsoft Dynamics 365. The Organization Data service has always been limited to performing create, read, update, and delete operations and never supported the ability to call specialized messages used in the Organization service, so it could never reach parity with the functionality of the Organization service. Changes implemented in the OData standards between v2 and v4 do not allow for upgrading the service to meet the requirements of a service that has parity with the Organization Services. We were able to apply a lot of the feedback we received about the Organization Data Service and apply it to make the Web API better.

This release of the Microsoft Dynamics 365 SDK does not include information about the Organization Data Service. You can find information about the Organization Data Service in the documentation for the Microsoft Dynamics CRM 2015 release at Use the OData endpoint with web resources.

Discovery web services

Microsoft Dynamics 365 is a multi-tenant application. This means that a single deployment can host multiple instances of Dynamics 365, each with its own data, each available via a different URL. Additionally, especially when Microsoft Dynamics 365 servers are hosted in a data center, the specific server can change as resources are moved or load balanced. Discovery web services provide a way for a client to detect which servers and organizations are available for a user to connect to based on their user account. You can choose to use either the Web API Discovery service or the IDiscoveryService web service. The Web API Discovery service provides the same benefits as the Web API, it is easier to consume for a wider range of programming languages, platforms, and devices.

More information: Discover the URL for your organization using the Web API or Discover the URL for your organization using the Organization Service

Deployment web service

For Dynamics 365 (on-premises) you can perform actions to manage your deployment programmatically using the Deployment web service. These are essentially the same operations you can perform on the server using the Deployment manager tool client installed on the server. You can create, import, or delete organizations as well as apply certain settings in code. This may be useful when you want to automate certain processes if you are providing a hosting service or if you want to automate creation of environments for testing.

More information: Introduction to the deployment web service.

See Also

Connect to Microsoft Dynamics 365
Authenticate users in Microsoft Dynamics 365
Use Microsoft Dynamics 365 web services
Build Windows client applications using the XRM tools
Write mobile and modern apps

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright