Setting Lookup Values Through the Dynamics Web API

When working with Microsoft Dynamics 365, setting lookup values via the Web API can be a common task and trick task. Lookups are essentially references to other records, and setting them correctly ensures data integrity and proper relationships between entities. In this blog post, we’ll walk through the steps to set lookup values using the Dynamics Web API and some of the quirks that go along with it.

Prerequisites

Before we dive in, make sure you have the following:

• Access to a Dynamics 365 instance.
• Necessary permissions to perform CRUD operations.
• Basic understanding of RESTful APIs and JSON.

Step-by-Step Guide

1. Understand the Lookup Field Structure

Lookup fields in Dynamics 365 are represented as navigation properties. For example, if you have a contact entity with a lookup to an account, the lookup field is named parentcustomerid.

2. Get the GUID of the Target Record

To set a lookup value, you need the GUID of the record you want to reference. You can retrieve this GUID through a query to the Web API.

Example get request for a GUID;

GET [your_dynamics_organization_uri]/api/data/v9.2/accounts?$select=accountid&$filter=name eq 'Nike'

3. Construct the JSON Payload

Once you have the GUID, you need to construct the JSON payload for your request. The lookup field is set using the @odata.bind annotation.

{
  "[email protected]": "/accounts(00000000-0000-0000-0000-000000000000)"
}

Be careful! If you create a custom relationship between entities, than you must use the schema name of that lookup. Not the logical name. If you have a lookup from Employee to Manager and the schema name is dev_Manager, but the logical name is dev_manager, you will have to use the schema name of dev_Manager for the odata annotation. You can avoid this ‘quirk’ by ensuring that your schema name is use all lower case letters during field creation, which would effectively make the logical name and the schema name the same. The rest of the JSON payload remains the same. Example below:

{
  "[email protected]": "/accounts(00000000-0000-0000-0000-000000000000)"
}

Replace the GUID in the example with the actual GUID of your target record.

4. Send the HTTP Request

You can use any HTTP client to send the request. Here’s an example using fetch in JavaScript with bearer authentication:

const url = "[Organization URI]/api/data/v9.2/contacts(00000000-0000-0000-0000-000000000000)";
const payload = {
  "[email protected]": "/accounts(00000000-0000-0000-0000-000000000000)"
};

fetch(url, {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + accessToken
  },
  body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Replace the GUIDs and accessToken with your actual values.

5. Verify the Update

After sending the request, verify that the lookup value has been set correctly by retrieving the record and checking the lookup field.

GET [Organization URI]/api/data/v9.2/contacts(00000000-0000-0000-0000-000000000000)?$select=parentcustomerid_account

Conclusion

Setting lookup values through the Dynamics Web API involves understanding the structure of lookup fields, retrieving the necessary GUIDs, constructing the appropriate JSON payload, and sending the HTTP request. With these steps, you can ensure that your data relationships are correctly maintained.

Feel free to reach out if you have any questions or need further assistance!

Reach out to Beringer today!

Do you need assistance with the Dynamics Web API? Contact us today!

Beringer Technology Group, a Microsoft Solutions Partner for Business Applications,  specializing in Microsoft Dynamics 365 and CRM for Distribution, also provides expert Managed IT Services, Backup and Disaster Recovery.