API – Adding and Updating Nested Entities

Introduction

When you're dealing with Nested Entities, you may need to expand the parent object to see all of the nested object's information (see API – Expanding Objects). To update that nested information, we similarly need to send a PUT or POST request to the parent object.

The Request

To update a nested entity, you will need to send a PUT request to the uppermost parent entity. For instance, Employer information is nested within Customers. This means that to update the Employer information, you would send a PUT request to the Customer's entity. Likewise, to update that employer's address, you would send the PUT request to the Customer's entity. This may seem a little complex, but it does allow updating the Customer, Employer, and Address entities all in one request — which can be a huge advantage.

Adding and editing this nested information works about the same, but there are some key differences we'll cover as we go.

The Body

Now that we know that the request will be sent to the uppermost parent entity, we need to create the body of the request.

We’re assuming that you’ve run a few GET requests up to this point. You’ve probably noticed that the data comes in with references pointing to each entity (unless you use $expand). As an example, the response from a GET request to the Customer endpoint is in this drop-down:

Expand Full Response
Here's the response from a GET request to the Customer endpoint:
{
"d": {
"__metadata": {
"uri": "https://loanpro.simnang.com/api/public/api/1/odata.svc/Customers(id=1)",
"type": "Entity.Customer"
},
"PrimaryAddress": {
"__deferred": {
"uri": "Customers(id=213)/PrimaryAddress"
}
},
"MailAddress": {
"__deferred": {
"uri": "Customers(id=213)/MailAddress"
}
},
"Employer": {
"__deferred": {
"uri": "Customers(id=213)/Employer"
}
},
"References": {
"__deferred": {
"uri": "Customers(id=213)/References"
}
},
"PaymentAccounts": {
"__deferred": {
"uri": "Customers(id=213)/PaymentAccounts"
}
},
"Phones": {
"__deferred": {
"uri": "Customers(id=213)/Phones"
}
},
"CustomFieldValues": {
"__deferred": {
"uri": "Customers(id=213)/CustomFieldValues"
}
},
"Documents": {
"__deferred": {
"uri": "Customers(id=213)/Documents"
}
},
"CreditScore": {
"__deferred": {
"uri": "Customers(id=213)/CreditScore"
}
},
"Loans": {
"__deferred": {
"uri": "Customers(id=213)/Loans"
}
},
"SocialProfiles": {
"__deferred": {
"uri": "Customers(id=213)/SocialProfiles"
}
},
"id": 1,
"customId": null,
"mcId": null,
"customerType": "customer.type.individual",
"status": "Active",
"firstName": "John",
"lastName": "Doe",
"middleName": "S",
"birthDate": "/Date(232329600)/",
"gender": "customer.gender.male",
"generationCode": "customer.generationCode.none",
"email": "johndoe@nonexistant.com",
"ssn": "111111111",
"driverLicense": "11111111",
"companyName": null,
"contactName": null,
"customerIdType": "customer.idType.ssn",
"customerId": null,
"creditLimit": 0,
"accessUserName": "john.doe2132132",
"accessPassword": null,
"active": 1,
"ofacMatch": 0,
"ofacTested": 0,
"hasAvatar": 0,
"loanRole": null,
"created": "/Date(1458663961)/",
"lastUpdate": "/Date(1465579531)/",
"creditScoreId": 1
}
}

As you can see, we now have all of these nested entity references. This tells us the names of each nested entity we can use.

Let’s continue with our example of updating Employer information for a Customer. We have the Customer information above, so let’s first add, and then update Employer information for that customer.

Adding Nested Entities

Adding is rather simple. We send a PUT request to the URL of the uppermost parent entity. We’ll then send the contents of the nested entity as a JSON object.

Let’s say our customer, John Doe, was just hired at the local high school as a janitor on May 19, 2021 and gets paid $10.50 hour for part-time janitorial work. Their next pay date was reported to be on June 19, 2021. We also know the school’s phone number, and that they get paid bi-weekly. All of this Employer information is stored in a JSON object, and the same request can include other Customer information that's unrelated to the employer. For instance, if we want to add this Employer information and change John’s middle name to “Smith” in the same request, we can do that by sending the following request:

PUT https://loanpro.simnang.com/api/public/api/1/odata.svc/Customers(213)
{
"Employer": {
"phone": "5555555555",
"payDate": "2016-06-19",
"hireDate": "2016-05-19",
"incomeFrequency": "customerEmployer.incomeFrequency.annually",
"payDateFrequency": "customerEmployer.payDateFrequency.biWeekly",
"income": "10500.00",
"companyName": "Local High School",
"title": "Janitor"
},
"__id":213,
"__update":true,
"middleName":"Smith"
}

If you wanted to use a GET request to retrieve that information, you would send it to the following endpoint:

GET https://loanpro.simnang.com/api/public/api/1/odata.svc/Customers(213)?$expand=Employer

Updating Nested Entities

Alright, so we entered John’s employer information, and it’s all going well until we realize that he works at the local junior high school instead. Whoops! Well, we already created the Employer entity, so we can’t just send the same request. We have to instead update the existing employer entity. Luckily, this is fairly easy. All we do is add the two fields described in API – Updating Entities (namely “__id” and “__update”), and then we include the fields that we want to update inside of the nested Employer Entity. Assuming the ID of our employer is 23, our request would be the following :

PUT https://loanpro.simnang.com/api/public/api/1/odata.svc/Customers(213)
{
"Employer": {
"__id":23,
"__update":true,
"companyName": "Local Junior High School"
},
"__id":213,
"__update":true,
"middleName":"Smith"
}

Multi-Nesting Entities

When there are several layers of entities (like a Russian Nesting Doll), the same principles apply. You send a PUT request to the uppermost entity, and then you send the JSON object for each nested entity along the way. So, to add an address to John’s employer, we would send the following:

PUT https://loanpro.simnang.com/api/public/api/1/odata.svc/Customers(213)
{
"Employer": {
"Address": {
"address1": "53 321 Street",
"address2": null,
"city": "HENEFER",
"state": "geo.state.NJ",
"zipcode": "840331342",
"country": "company.country.usa",
"geoLat": "41.017894",
"geoLon": "-111.4879125",
"active": 1,
"isVerified": 0
}
}
}

If you needed to update the address, you would first need to find out the Address ID by sending the following GET request:

GET https://loanpro.simnang.com/api/public/api/1/odata.svc/Customers(213)?$expand=Employer/Address

Assuming the Address ID is 142, to update it (say, change the city), you would send the following request :

PUT https://loanpro.simnang.com/api/public/api/1/odata.svc/Customers(213)
{
"Employer": {
"Address": {
"__id": "142",
"__update": true,
"city": "Chicago"
}
}
}


How did we do?


Powered by HelpDocs (opens in a new tab)