This collection of sample code snippets demonstrate how to perform basic CRUD (Create, Retrieve, Update, and Delete) and associative operations using the Microsoft Dataverse Web API. These language specific versions implement the same operations:
This article describes a common set of operations implemented by each sample snippet in this group. This article describes the HTTP requests and responses and text output that each sample performs without the language specific details. See the language specific descriptions and the individual samples for details about how these operations are performed.
Demonstrates
This sample is divided into the following sections, containing Dataverse Web API operations which are discussed in greater detail in the specified associated conceptual articles.
For brevity, less pertinent HTTP headers are omitted. 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 upon that instance. The response header OData-EntityId contains the URL to this newly created row, which parenthetically includes the unique ID for this record.
Contact 'Rafel Shillo' updated with jobtitle and annual income
Retrieve the contact with its set of explicitly initialized properties. The fullname is a read-only property that is calculated from the firstname and lastname properties, which were explicitly initialized when the instance was created. In contrast, the description property wasn't explicitly initialized, so it retains its default value, a null string.
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.
Only send changed properties in update requests. For more information, see Basic update.
Explicitly set a single property, the primary phone number. Note this is a PUT request and that the JSON key named value is used when performing operations on individual properties.
This section creates a new account record named Contoso, Ltd. and associates it to an existing contact, Rafel Shillo, which was created in Section 1. This creation and association is performed in a single POST operation.
Create the Contoso, Ltd. account and set its primary contact attribute to the existing contact Rafel Shillo. The @odata.bind annotation indicates that an association is being created, here binding the primarycontactid single-valued navigation property to an existing contact, Rafel Shillo.
Retrieve the primary contact for the account Contoso, Ltd., again using $expand with the primarycontactid single-valued navigation property to access the associated contact EntityType record.
Section 3: Create related table rows (deep insert)
This section demonstrates how to create a table row and related row, in a single POST request. When you use this method, all rows are newly created; there are no existing rows to associate with. This approach has two advantages. It's more efficient, replacing multiple simpler creation and association operations with one combined operation. Also, it's atomic, where 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 Coffee and its primary contact Susie Curtis and their three related tasks in one operation. Note the use of the single-valued primarycontactid navigation property and the collection-valued navigation property Contact_Tasks to 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
}
]
}
}
Selectively retrieve the newly created Fourth Coffee account and its primary contact. An expansion is performed on the single-valued navigation property primarycontactid.
Selectively 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.
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 demonstrates how to associate and disassociate existing table rows. Forming an association requires the use of a reference URI and relationship object, which are then sent in a POST request. Disassociating requires sending a DELETE request to the reference URI for that association. First a one-to-many association is formed between a contact and an account. Then a many-to-many association is formed between a competitor and one or more opportunities.
Add Rafel Shillo as a contact to the account Fourth Coffee using the contact_customer_accounts collection-valued navigation property. Note the use of the special key @odata.id to specify the associated record.
Confirm 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.