Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
This collection of sample code snippets demonstrates how to perform basic CRUD (Create, Retrieve, Update, and Delete) and associative operations by using the Microsoft Dataverse Web API. These language-specific versions implement the same operations:
- Web API Basic Operations Sample (C#)
- Web API Basic Operations Sample (PowerShell)
- Web API Basic Operations Sample (client-side JavaScript)
This article describes a common set of operations that each sample snippet in this group implements. It describes the HTTP requests and responses, and text output that each sample performs without the language-specific details. For details about how these operations are performed, see the language-specific descriptions and the individual samples.
Demonstrates
This sample is divided into the following sections. Each section contains Dataverse Web API operations that are discussed in greater detail in the specified associated conceptual articles.
Note
For brevity, the sample omits less pertinent HTTP headers. The URLs of the records vary with the base organization address and the ID of the row assigned by your Dataverse server.
Section 1: Basic create and update operations
This section creates a single contact then performs a series of updates on that instance. The response header OData-EntityId contains the URL to this newly created row, which parenthetically includes the unique ID for this record.
Create a new contact, named Rafel Shillo.
Request:
POST [Organization Uri]/api/data/v9.2/contacts HTTP/1.1 OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/json { "firstname": "Rafel", "lastname": "Shillo" }Response:
HTTP/1.1 204 NoContent OData-Version: 4.0 OData-EntityId: [Organization Uri]/api/data/v9.2/contacts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)Console output:
Contact URI: [Organization Uri]/api/data/v9.2/contacts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee) Contact relative Uri: contacts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)The properties available for each type are defined within the metadata document and are also documented for each type in the Web API Entity Type Reference section. For more general information, see Web API types and operations.
Update the contact with values for annual income ($80,000) and job title (Junior Developer).
Request:
PATCH [Organization Uri]/api/data/v9.2/contacts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee) HTTP/1.1 If-Match: * OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/json { "annualincome": 80000, "jobtitle": "Junior Developer" }Response:
HTTP/1.1 204 NoContent OData-Version: 4.0 OData-EntityId: [Organization Uri]/api/data/v9.2/contacts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)Console output:
Contact 'Rafel Shillo' updated with jobtitle and annual incomeRetrieve the contact with its set of explicitly initialized properties. The
fullnameis a read-only property that is calculated from thefirstnameandlastnameproperties, which you explicitly initialized when you created the instance. In contrast, thedescriptionproperty wasn't explicitly initialized, so it retains its default value, anullstring.In addition to the requested values and typical headers, the response also automatically returns the following types of additional information:
- The primary ID for the current table type, here
contactid. - An ETag value, denoted by the
@odata.etagkey, which identifies the specific version of the resource requested. For more information, see Perform conditional operations using the Web API. - The metadata context, denoted by the
@odata.contextkey, provides a way to compare query results to determine if they came from the same query. - A
_transactioncurrencyid_valuethat indicates the local currency of the monetary transaction.
Request:
GET [Organization Uri]/api/data/v9.2/contacts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)?$select=fullname,annualincome,jobtitle,description HTTP/1.1 Prefer: odata.include-annotations="*" OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/jsonResponse:
HTTP/1.1 200 OK ETag: W/"72935648" OData-Version: 4.0 Preference-Applied: odata.include-annotations="*" { "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#contacts(fullname,annualincome,jobtitle,description)/$entity", "@odata.etag": "W/\"72935648\"", "fullname": "Rafel Shillo", "annualincome@OData.Community.Display.V1.FormattedValue": "$80,000.00", "annualincome": 80000.0, "jobtitle": "Junior Developer", "description": null, "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar", "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "transactioncurrencyid", "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "transactioncurrency", "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1", "contactid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee" }Console output:
Contact 'Rafel Shillo' retrieved: Annual income: $80,000.00 Job title: Junior Developer Description:Important
Always use selection and filtering in retrieval operations to optimize performance. For more information, see Query Data using the Web API.
- The primary ID for the current table type, here
Update the contact instance by supplying new values to these same properties.
Request:
PATCH [Organization Uri]/api/data/v9.2/contacts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee) HTTP/1.1 If-Match: * OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/json { "jobtitle": "Senior Developer", "annualincome": 95000, "description": "Assignment to-be-determined" }Response:
HTTP/1.1 204 NoContent OData-Version: 4.0 OData-EntityId: [Organization Uri]/api/data/v9.2/contacts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)Console output:
Contact 'Rafel Shillo' updated: Job title: Senior Developer Annual income: 95000 Description: Assignment to-be-determinedImportant
Only send changed properties in update requests. For more information, see Basic update.
Explicitly set a single property, the primary phone number. This example uses a
PUTrequest and the JSON key namedvaluewhen performing operations on individual properties.Request:
PUT [Organization Uri]/api/data/v9.2/contacts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)/telephone1 HTTP/1.1 OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/json { "value": "555-0105" }Response:
HTTP/1.1 204 NoContent OData-Version: 4.0Console output:
Contact 'Rafel Shillo' phone number updated.Retrieve that same single property, the primary phone number. Again, use the key named
value.Request:
GET [Organization Uri]/api/data/v9.2/contacts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)/telephone1 HTTP/1.1 OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/jsonResponse:
HTTP/1.1 200 OK OData-Version: 4.0 { "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#contacts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)/telephone1", "value": "555-0105" }Console output:
Contact's telephone # is: 555-0105.
Section 2: Create with association
This section creates a new account record named Contoso, Ltd. and associates it to an existing contact, Rafel Shillo, which you created in Section 1. You perform this creation and association in a single POST operation.
Create the Contoso, Ltd. account and set its primary contact attribute to the existing contact Rafel Shillo. The
@odata.bindannotation indicates that you're creating an association. In this case, it binds theprimarycontactidsingle-valued navigation property to an existing contact, Rafel Shillo.Request:
POST [Organization Uri]/api/data/v9.2/accounts HTTP/1.1 OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/json { "name": "Contoso Ltd", "telephone1": "555-5555", "primarycontactid@odata.bind": "contacts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)" }Response:
HTTP/1.1 204 NoContent OData-Version: 4.0 OData-EntityId: [Organization Uri]/api/data/v9.2/accounts(11bb11bb-cc22-dd33-ee44-55ff55ff55ff)Console output:
Account 'Contoso Ltd' created. Account URI: accounts(11bb11bb-cc22-dd33-ee44-55ff55ff55ff)Retrieve the primary contact for the account Contoso, Ltd. Again, use
$expandwith theprimarycontactidsingle-valued navigation property to access the associated contact EntityType record.Request:
GET [Organization Uri]/api/data/v9.2/accounts(11bb11bb-cc22-dd33-ee44-55ff55ff55ff)?$select=name,&$expand=primarycontactid($select=fullname,jobtitle,annualincome) HTTP/1.1 Prefer: odata.include-annotations="*" OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/jsonResponse:
HTTP/1.1 200 OK ETag: W/"72935670" OData-Version: 4.0 Preference-Applied: odata.include-annotations="*" { "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,primarycontactid(fullname,jobtitle,annualincome))/$entity", "@odata.etag": "W/\"72935670\"", "name": "Contoso Ltd", "accountid": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff", "primarycontactid": { "@odata.etag": "W/\"72935663\"", "fullname": "Rafel Shillo", "jobtitle": "Senior Developer", "annualincome@OData.Community.Display.V1.FormattedValue": "$95,000.00", "annualincome": 95000.0, "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar", "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "transactioncurrencyid", "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "transactioncurrency", "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1", "contactid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee" } }Console output:
Account 'Contoso Ltd' has primary contact 'Rafel Shillo': Job title: Senior Developer Annual income: $95,000.00
Section 3: Create related table rows (deep insert)
This section shows how to create a table row and related row in a single POST request. When you use this method, you create all rows new; you don't associate with existing rows. This approach has two advantages. It's more efficient because it replaces multiple simpler creation and association operations with one combined operation. Also, it's atomic, so either the entire operation succeeds and all the related objects are created, or the operation fails and none are created.
This section creates an account, its primary contact, and a set of tasks for that contact in one request.
Create the account
Fourth Coffeeand its primary contactSusie Curtisand their three related tasks in one operation. Note the use of the single-valuedprimarycontactidnavigation property and the collection-valued navigation propertyContact_Tasksto define these relationships, respectively. Single-valued navigational properties take an object value, whereas collection-valued navigation properties take an array value.Request:
POST [Organization Uri]/api/data/v9.2/accounts HTTP/1.1 OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/json { "name": "Fourth Coffee", "primarycontactid": { "firstname": "Susie", "lastname": "Curtis", "jobtitle": "Coffee Master", "annualincome": 48000, "Contact_Tasks": [ { "subject": "Sign invoice", "description": "Invoice #12321", "scheduledstart": "2023-04-19T03:00:00+07:00", "scheduledend": "2023-04-19T04:00:00+07:00", "scheduleddurationminutes": 60 }, { "subject": "Setup new display", "description": "Theme is - Spring is in the air", "scheduledstart": "2023-04-20T03:00:00+07:00", "scheduledend": "2023-04-20T04:00:00+07:00", "scheduleddurationminutes": 60 }, { "subject": "Conduct training", "description": "Train team on making our new blended coffee", "scheduledstart": "2023-04-21T03:00:00+07:00", "scheduledend": "2023-04-21T04:00:00+07:00", "scheduleddurationminutes": 60 } ] } }Response:
HTTP/1.1 204 NoContent OData-Version: 4.0 OData-EntityId: [Organization Uri]/api/data/v9.2/accounts(22cc22cc-dd33-ee44-ff55-66aa66aa66aa)Console output:
Account 'Fourth Coffee created.Selectively retrieve the newly created Fourth Coffee account and its primary contact. An expansion is performed on the single-valued navigation property
primarycontactid.Request:
GET [Organization Uri]/api/data/v9.2/accounts(22cc22cc-dd33-ee44-ff55-66aa66aa66aa)?$select=name&$expand=primarycontactid($select=fullname,jobtitle,annualincome) HTTP/1.1 Prefer: odata.include-annotations="*" OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/jsonResponse:
HTTP/1.1 200 OK ETag: W/"72935710" OData-Version: 4.0 Preference-Applied: odata.include-annotations="*" { "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,primarycontactid(fullname,jobtitle,annualincome))/$entity", "@odata.etag": "W/\"72935710\"", "name": "Fourth Coffee", "accountid": "22cc22cc-dd33-ee44-ff55-66aa66aa66aa", "primarycontactid": { "@odata.etag": "W/\"72935689\"", "fullname": "Susie Curtis", "jobtitle": "Coffee Master", "annualincome@OData.Community.Display.V1.FormattedValue": "$48,000.00", "annualincome": 48000.0, "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar", "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "transactioncurrencyid", "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "transactioncurrency", "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1", "contactid": "2f28bcb4-bb27-ed11-9db1-002248274ada" } }Console output:
Account 'Fourth Coffee' has primary contact 'Susie Curtis': Job title: Coffee Master Annual income: $48,000.00Selectively retrieve the tasks associated with the primary contact retrieved in the previous operation. An expansion is performed on the collection-valued navigation property
Contact_Tasks.Request:
GET [Organization Uri]/api/data/v9.2/contacts(2f28bcb4-bb27-ed11-9db1-002248274ada)?$select=fullname&$expand=Contact_Tasks($select=subject,description,scheduledstart,scheduledend) HTTP/1.1 Prefer: odata.include-annotations="*" OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/jsonResponse:
HTTP/1.1 200 OK ETag: W/"72935689" OData-Version: 4.0 Preference-Applied: odata.include-annotations="*" { "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#contacts(fullname,Contact_Tasks(subject,description,scheduledstart,scheduledend))/$entity", "@odata.etag": "W/\"72935689\"", "fullname": "Susie Curtis", "contactid": "2f28bcb4-bb27-ed11-9db1-002248274ada", "Contact_Tasks": [ { "@odata.etag": "W/\"72935719\"", "subject": "Sign invoice", "description": "Invoice #12321", "scheduledstart@OData.Community.Display.V1.FormattedValue": "4/18/2023 1:00 PM", "scheduledstart": "2023-04-18T20:00:00Z", "scheduledend@OData.Community.Display.V1.FormattedValue": "4/18/2023 2:00 PM", "scheduledend": "2023-04-18T21:00:00Z", "activityid": "3028bcb4-bb27-ed11-9db1-002248274ada" }, { "@odata.etag": "W/\"72935723\"", "subject": "Setup new display", "description": "Theme is - Spring is in the air", "scheduledstart@OData.Community.Display.V1.FormattedValue": "4/19/2023 1:00 PM", "scheduledstart": "2023-04-19T20:00:00Z", "scheduledend@OData.Community.Display.V1.FormattedValue": "4/19/2023 2:00 PM", "scheduledend": "2023-04-19T21:00:00Z", "activityid": "3128bcb4-bb27-ed11-9db1-002248274ada" }, { "@odata.etag": "W/\"72935727\"", "subject": "Conduct training", "description": "Train team on making our new blended coffee", "scheduledstart@OData.Community.Display.V1.FormattedValue": "4/20/2023 1:00 PM", "scheduledstart": "2023-04-20T20:00:00Z", "scheduledend@OData.Community.Display.V1.FormattedValue": "4/20/2023 2:00 PM", "scheduledend": "2023-04-20T21:00:00Z", "activityid": "3228bcb4-bb27-ed11-9db1-002248274ada" } ] }Console output:
Contact 'Susie Curtis' has the following assigned tasks: Subject: Sign invoice, Description: Invoice #12321 Start: 4/18/2023 1:00 PM End: 4/18/2023 2:00 PM Subject: Setup new display, Description: Theme is - Spring is in the air Start: 4/19/2023 1:00 PM End: 4/19/2023 2:00 PM Subject: Conduct training, Description: Train team on making our new blended coffee Start: 4/20/2023 1:00 PM End: 4/20/2023 2:00 PM
Section 4: Associate and disassociate existing entities
This section shows how to associate and disassociate existing table rows. To form an association, use a reference URI and relationship object, and send them in a POST request. To disassociate, send a DELETE request to the reference URI for that association. First, create a one-to-many association between a contact and an account. Then, create a many-to-many association between a competitor and one or more opportunities.
Add Rafel Shillo as a contact to the account Fourth Coffee by using the
contact_customer_accountscollection-valued navigation property. Note the use of the special key@odata.idto specify the associated record.Request:
POST [Organization Uri]/api/data/v9.2/accounts(22cc22cc-dd33-ee44-ff55-66aa66aa66aa)/contact_customer_accounts/$ref HTTP/1.1 OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/json { "@odata.id": "[Organization Uri]/api/data/v9.2/contacts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)" }Response:
HTTP/1.1 204 NoContent OData-Version: 4.0Confirm the previous operation by retrieving the collection of contacts for the account Fourth Coffee. The response contains the array with a single element, the recently assigned contact Rafel Shillo.
Request:
GET [Organization Uri]/api/data/v9.2/accounts(22cc22cc-dd33-ee44-ff55-66aa66aa66aa)/contact_customer_accounts?$select=fullname,jobtitle HTTP/1.1 OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/jsonResponse:
HTTP/1.1 200 OK OData-Version: 4.0 { "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#contacts(fullname,jobtitle)", "value": [ { "@odata.etag": "W/\"72935741\"", "fullname": "Rafel Shillo", "jobtitle": "Senior Developer", "contactid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee" } ] }Console output:
Contact list for account 'Fourth Coffee': Name: Rafel Shillo, Job title: Senior DeveloperRemove the association that you created between account Fourth Coffee and contact Rafel Shillo.
Request:
DELETE [Organization Uri]/api/data/v9.2/accounts(22cc22cc-dd33-ee44-ff55-66aa66aa66aa)/contact_customer_accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)/$ref HTTP/1.1 OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/jsonResponse:
HTTP/1.1 204 NoContent OData-Version: 4.0Create a security role named
Example Security Role.Request:
POST [Organization Uri]/api/data/v9.2/roles HTTP/1.1 OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/json { "businessunitid@odata.bind": "businessunits(38e0dbe4-131b-e111-ba7e-78e7d1620f5e)", "name": "Example Security Role" }Response:
HTTP/1.1 204 NoContent OData-Version: 4.0 OData-EntityId: [Organization Uri]/api/data/v9.2/roles(33dd33dd-ee44-ff55-aa66-77bb77bb77bb)Associate the new security role to your
systemuserrecord.Request:
POST [Organization Uri]/api/data/v9.2/systemusers(4026be43-6b69-e111-8f65-78e7d1620f5e)/systemuserroles_association/$ref HTTP/1.1 OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/json { "@odata.id": "[Organization Uri]/api/data/v9.2/roles(33dd33dd-ee44-ff55-aa66-77bb77bb77bb)" }Response:
HTTP/1.1 204 NoContent OData-Version: 4.0Console output:
Security Role 'Example Security Role' associated with to your user account.Retrieve the Example Security Role by using the
systemuserroles_associationmany-to-many relationship:Request:
GET [Organization Uri]/api/data/v9.2/systemusers(4026be43-6b69-e111-8f65-78e7d1620f5e)/systemuserroles_association?$select=name&$filter=roleid%20eq%20e359feba-bb27-ed11-9db1-002248274ada HTTP/1.1 OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/jsonResponse:
HTTP/1.1 200 OK OData-Version: 4.0 { "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#roles(name)", "value": [ { "@odata.etag": "W/\"72935763\"", "name": "Example Security Role", "roleid": "33dd33dd-ee44-ff55-aa66-77bb77bb77bb" } ] }Console output:
Retrieved role: Example Security RoleDissociate the security role from your user record. This step uses the same general syntax as the removal of a one-to-many association.
Request:
DELETE [Organization Uri]/api/data/v9.2/systemusers(4026be43-6b69-e111-8f65-78e7d1620f5e)/systemuserroles_association(33dd33dd-ee44-ff55-aa66-77bb77bb77bb)/$ref HTTP/1.1 OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/jsonResponse:
HTTP/1.1 204 NoContent OData-Version: 4.0
Section 5: Delete table rows
Delete each element in the collection of row URLs. The first element is a contact record for Rafel Shillo.
Request:
DELETE [Organization Uri]/api/data/v9.2/contacts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee) HTTP/1.1 OData-MaxVersion: 4.0 OData-Version: 4.0 If-None-Match: null Accept: application/jsonResponse:
HTTP/1.1 204 NoContent OData-Version: 4.0Delete the remaining records in subsequent iterations through the collection.
Request:
DELETE [Organization Uri]/api/data/v9.2/accounts(11bb11bb-cc22-dd33-ee44-55ff55ff55ff) HTTP/1.1 . . . DELETE [Organization Uri]/api/data/v9.2/accounts(22cc22cc-dd33-ee44-ff55-66aa66aa66aa) HTTP/1.1 . . . DELETE [Organization Uri]/api/data/v9.2/contacts(2f28bcb4-bb27-ed11-9db1-002248274ada) HTTP/1.1 . . . DELETE [Organization Uri]/api/data/v9.2/roles(33dd33dd-ee44-ff55-aa66-77bb77bb77bb) HTTP/1.1
See also
Use the Dataverse Web API
Create a table row using the Web API
Retrieve a table row using the Web API
Update and delete table rows using the Web API
Associate and disassociate table rows using the Web API
Web API Basic Operations Sample (C#)
Web API Basic Operations Sample (PowerShell)
Web API Basic Operations Sample (client-side JavaScript)