How To: Create & Update Entities In Batch

13min

For information about prerequisites, see How to use Entities?﻿. Batch endpoints are provided to create and update Entities in batches. The Batch endpoints support two methods to supply the Entity data:
JSON
CSV file upload
Create Entities in Batch via JSON
To create Entities in batch, call the Create Batch Request﻿ endpoint and specify the entityTypePluralName in the path parameter.
Learn more about the necessary attributes﻿ listed for creating Entities in Batch using the JSON.
The following examples show a request body for creating a Batch Entities request:
JSON
{
   "payload":[
      {
         "uniqueCode":"QK6A-JI6S-7ETR",
         "name":"vehicles",
         "owner":"worldlogistics",
         "category":"four-wheeler",
         "subCategory":"truck",
         "properties":{
            "color":"red"
         }
      },
      {
         "uniqueCode":"XNSS-HSJW-3NGU",
         "name":"car2",
         "owner":"worldlogistics",
         "category":"four-wheeler",
         "subCategory":"truck",
         "properties":{
            "color":"blue"
         }
      },
      {
         "uniqueCode":"NHLE-L6MI-4GE4",
         "name":"car3",
         "owner":"worldlogistics",
         "category":"four-wheeler",
         "subCategory":"truck",
         "properties":{
            "color":"black"
         }
      },
      {
         "uniqueCode":"6ETI-UIL2-9WAX",
         "name":"car4",
         "owner":"worldlogistics",
         "category":"four-wheeler",
         "subCategory":"truck",
         "properties":{
            "cole":"silver"
         }
      },
      {
         "uniqueCode":"2E62-E3SR-33FI",
         "name":"car5",
         "owner":"worldlogistics",
         "category":"four-wheeler",
         "subCategory":"truck",
         "properties":{
            "color":"white"
         }
      }
   ],
   "callback":"https://examplecallback.com"
}
{
   "payload":[
      {
         "uniqueCode":"QK6A-JI6S-7ETR",
         "name":"vehicles",
         "owner":"worldlogistics",
         "category":"four-wheeler",
         "subCategory":"truck",
         "properties":{
            "color":"red"
         }
      },
      {
         "uniqueCode":"XNSS-HSJW-3NGU",
         "name":"car2",
         "owner":"worldlogistics",
         "category":"four-wheeler",
         "subCategory":"truck",
         "properties":{
            "color":"blue"
         }
      },
      {
         "uniqueCode":"NHLE-L6MI-4GE4",
         "name":"car3",
         "owner":"worldlogistics",
         "category":"four-wheeler",
         "subCategory":"truck",
         "properties":{
            "color":"black"
         }
      },
      {
         "uniqueCode":"6ETI-UIL2-9WAX",
         "name":"car4",
         "owner":"worldlogistics",
         "category":"four-wheeler",
         "subCategory":"truck",
         "properties":{
            "cole":"silver"
         }
      },
      {
         "uniqueCode":"2E62-E3SR-33FI",
         "name":"car5",
         "owner":"worldlogistics",
         "category":"four-wheeler",
         "subCategory":"truck",
         "properties":{
            "color":"white"
         }
      }
   ],
   "callback":"https://examplecallback.com"
}
﻿
Create Entities in Batch via CSV Upload
To create Entities in batch through CSV, call the File Upload Create Request﻿ endpoint and specify entityTypePluralName in the path parameter. Upload the CSV file with all the details as shown in the sample CSV.
Updating Entities In Batch Via JSON
To update Entities in batch, call the Update Batch Request﻿ endpoint and specify entityTypePluralName in the path parameter. The following examples show a request body for updating a Batch Entity request:
JSON
{
   "payload":[
      {
         "properties":{
            "color":"black"
         }
      },
      {
         "properties":{
            "color":"silver"
         }
      },
      {
         "properties":{
            "color":"white"
         }
      },
      {
         "properties":{
            "color":"blue"
         }
      },
      {
         "properties":{
            "color":"red"
         }
      }
   ],
   "callback":"https://examplecallback.com"
}
{
   "payload":[
      {
         "properties":{
            "color":"black"
         }
      },
      {
         "properties":{
            "color":"silver"
         }
      },
      {
         "properties":{
            "color":"white"
         }
      },
      {
         "properties":{
            "color":"blue"
         }
      },
      {
         "properties":{
            "color":"red"
         }
      }
   ],
   "callback":"https://examplecallback.com"
}
﻿
Update Enities in Batch with Conditional Updates
Conditional updates can also be applied to batch updates, where multiple entity instances are updated in a single request. Each entry in the batch can have its own conditionExpression.
JS
https PUT {{baseUrl}}/:entityType/batch
https PUT {{baseUrl}}/:entityType/batch
﻿
Payload
JS
http PUT {{baseUrl}}/:entityType/batch
Content-Type: application/json

{
    "payload": [
        {
            "entityInstanceId": "exampleId1",
            "properties": {
                "status": "closed"
            },
            "conditionExpression": "properties.paymentStatus == 'paid'"
        },
        {
            "entityInstanceId": "exampleId2",
            "properties": {
                "status": "pending"
            },
            "conditionExpression": "properties.userRole == 'admin'"
        }
    ]
}
http PUT {{baseUrl}}/:entityType/batch
Content-Type: application/json

{
    "payload": [
        {
            "entityInstanceId": "exampleId1",
            "properties": {
                "status": "closed"
            },
            "conditionExpression": "properties.paymentStatus == 'paid'"
        },
        {
            "entityInstanceId": "exampleId2",
            "properties": {
                "status": "pending"
            },
            "conditionExpression": "properties.userRole == 'admin'"
        }
    ]
}
﻿
Understand the Batch Payload
URL: Replace {{baseUrl}} and :entityType with the appropriate details for your batch update endpoint.
payload: This array contains multiple entity instances to be updated.
Each object within the array represents an individual update:
entityInstanceId: The unique identifier for the entity instance being updated.
properties: The attributes to be updated for that instance.
conditionExpression: A condition specific to that instance that must evaluate to true for the update to proceed.
Batch Update with Multiple Conditions
Request Headers
Headers
Description
Example Value
Required
X-COREOS-REQUEST-ID
Unique request identifier for tracking purposes
32876292-bde0-438d-ac75-6fe4eb78c073
Yes
X-COREOS-TID
Tenant identifier for the organization
delhivery
Yes
X-COREOS-USERINFO
Information about the user making the request
{} (Empty JSON in this example)
Yes
X-COREOS-APPID
Identifier for the application making the request
b0ecb6e12f5e4fd38f9f04125f8db1ea
Yes
Content-Type
The media type of the resource being sent
application/json
Yes
Accept
The media type expected in the response
application/json
Yes
 Request Parameters
Parameter
Description
Example Value
Type
Required
payload
Array of objects containing entity details to be updated
Array of entity instance objects (shown in payload below)
JSON Array
Yes
entityInstanceId
Unique identifier for the entity instance being updated
testfives:a5fb93b0-e1b8-5acf-9cb8-351cee15bcd2
String
Yes
owner
Owner identifier for the entity instance
3RTrlmIFfo50wNDBv2mDlAHKUGz3SQ5v
String
Yes
properties
Properties of the entity instance
{"manufacturer": "hyundai"}
JSON Object
Yes
name
Name of the entity instance
"USB", "Direct", "Garden"
String
Yes
category
Category of the entity instance
"four-wheeler"
String
Yes
subCategory
Subcategory of the entity instance
"car"
String
Yes
conditionExpression
Condition that must be true for the update to occur
properties.manufacturer == 'honda', etc.
String
Yes
callback.url
URL to send callback notifications upon completion
https://many-baby-86.webhook.cool
URL String
No
Payload
JSON

   "payload": [
       {
           "entityInstanceId": "testfives:a5fb93b0-e1b8-5acf-9cb8-351cee15bcd2",
           "owner": "3RTrlmIFfo50wNDBv2mDlAHKUGz3SQ5v",
           "properties": {
               "manufacturer": "hyundai"
           },
           "name": "USB",
           "category": "four-wheeler",
           "subCategory": "car",
           "conditionExpression": "properties.manufacturer == '\''honda'\''"
       },
       {
           "entityInstanceId": "testfives:a5fb93b0-e1b8-5acf-9cb8-351cee15bcd2",
           "owner": "3RTrlmIFfo50wNDBv2mDlAHKUGz3SQ5v",
           "properties": {
               "manufacturer": "honda"
           },
           "name": "Direct",
           "category": "four-wheeler",
           "subCategory": "car",
           "conditionExpression": "properties.manufacturer == '\''hyundai'\''"
       },
       {
           "entityInstanceId": "testfives:a5fb93b0-e1b8-5acf-9cb8-351cee15bcd2",
           "owner": "3RTrlmIFfo50wNDBv2mDlAHKUGz3SQ5v",
           "properties": {
               "manufacturer": "honda"
           },
           "name": "Garden",
           "category": "four-wheeler",
           "subCategory": "car",
           "conditionExpression": "properties.manufacturer == '\''toyota'\''"
       }


   ],
   "callback": {
       "url": "https://many-baby-86.webhook.cool"
   }
}'


   "payload": [
       {
           "entityInstanceId": "testfives:a5fb93b0-e1b8-5acf-9cb8-351cee15bcd2",
           "owner": "3RTrlmIFfo50wNDBv2mDlAHKUGz3SQ5v",
           "properties": {
               "manufacturer": "hyundai"
           },
           "name": "USB",
           "category": "four-wheeler",
           "subCategory": "car",
           "conditionExpression": "properties.manufacturer == '\''honda'\''"
       },
       {
           "entityInstanceId": "testfives:a5fb93b0-e1b8-5acf-9cb8-351cee15bcd2",
           "owner": "3RTrlmIFfo50wNDBv2mDlAHKUGz3SQ5v",
           "properties": {
               "manufacturer": "honda"
           },
           "name": "Direct",
           "category": "four-wheeler",
           "subCategory": "car",
           "conditionExpression": "properties.manufacturer == '\''hyundai'\''"
       },
       {
           "entityInstanceId": "testfives:a5fb93b0-e1b8-5acf-9cb8-351cee15bcd2",
           "owner": "3RTrlmIFfo50wNDBv2mDlAHKUGz3SQ5v",
           "properties": {
               "manufacturer": "honda"
           },
           "name": "Garden",
           "category": "four-wheeler",
           "subCategory": "car",
           "conditionExpression": "properties.manufacturer == '\''toyota'\''"
       }


   ],
   "callback": {
       "url": "https://many-baby-86.webhook.cool"
   }
}'
﻿
In this example, the last object in the json with "conditionExpression": "properties.manufacturer == '\''toyota'\''" fails to meet the condition and fails to update.
Updating Entities In Batch Via CSV Upload
To update Entities in batch through CSV, call the File Upload to Update Entities Request ﻿endpoint and specify entityTypePluralName in the path parameter. Upload the CSV file with all the details as shown in the sample CSV.
Update Entities in Batch via CSV with conditional expression
Now, when converting the above JSON payload to a CSV file and making the following request, the same behavior occurs with the last record failing to update as a condition not met.
CSV file data 
entityInstanceId
properties
conditionExpression
testfives:a5fb93b0-e1b8-5acf-9cb8-351cee15bcd2
{"manufacturer": "honda"}
properties.manufacturer == 'hyundai'
testfives:a5fb93b0-e1b8-5acf-9cb8-351cee15bcd2
{"manufacturer": "hyundai"}
properties.manufacturer == 'honda'
testfives:a5fb93b0-e1b8-5acf-9cb8-351cee15bcd2
{"manufacturer": "hyundai"}
properties.manufacturer == 'toyota'
Upload Request
Curl

curl --location --request PUT 'https://os1devs.sandbox.getos1.com/core/api/v2/entity/testfives/upload' \
--header 'X-COREOS-REQUEST-ID: 6629c507-11f3-4e73-8b5c-4457eb35a415' \
--header 'X-COREOS-TID: os1devs \
--header 'X-COREOS-USERINFO: {}' \
--header 'X-COREOS-APPID: b0ecb6e12f5e4fd38f9f04125f8db1ea' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--form 'file=@"/Users/vinothshanmugam/Downloads/entityBatchUpload.csv"' \
--form 'callback="{
       \"url\": \"https://many-baby-86.webhook.cool\"
   }"'



curl --location --request PUT 'https://os1devs.sandbox.getos1.com/core/api/v2/entity/testfives/upload' \
--header 'X-COREOS-REQUEST-ID: 6629c507-11f3-4e73-8b5c-4457eb35a415' \
--header 'X-COREOS-TID: os1devs \
--header 'X-COREOS-USERINFO: {}' \
--header 'X-COREOS-APPID: b0ecb6e12f5e4fd38f9f04125f8db1ea' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--form 'file=@"/Users/vinothshanmugam/Downloads/entityBatchUpload.csv"' \
--form 'callback="{
       \"url\": \"https://many-baby-86.webhook.cool\"
   }"'

﻿
Retrieve Entity Batch Status
To retrieve the information about Entities in Batch processing, call the Get the Status of Batch Request﻿ endpoint and pass the entityTypePluralName, BatchId in the path parameter. This process is common to both JSON and CSV-based APIs.

Headers	Description	Example Value	Required
X-COREOS-REQUEST-ID	Unique request identifier for tracking purposes	32876292-bde0-438d-ac75-6fe4eb78c073	Yes
X-COREOS-TID	Tenant identifier for the organization	delhivery	Yes
X-COREOS-USERINFO	Information about the user making the request	{} (Empty JSON in this example)	Yes
X-COREOS-APPID	Identifier for the application making the request	b0ecb6e12f5e4fd38f9f04125f8db1ea	Yes
Content-Type	The media type of the resource being sent	application/json	Yes
Accept	The media type expected in the response	application/json	Yes

Parameter	Description	Example Value	Type	Required
payload	Array of objects containing entity details to be updated	Array of entity instance objects (shown in payload below)	JSON Array	Yes
entityInstanceId	Unique identifier for the entity instance being updated	testfives:a5fb93b0-e1b8-5acf-9cb8-351cee15bcd2	String	Yes
owner	Owner identifier for the entity instance	3RTrlmIFfo50wNDBv2mDlAHKUGz3SQ5v	String	Yes
properties	Properties of the entity instance	{"manufacturer": "hyundai"}	JSON Object	Yes
name	Name of the entity instance	"USB", "Direct", "Garden"	String	Yes
category	Category of the entity instance	"four-wheeler"	String	Yes
subCategory	Subcategory of the entity instance	"car"	String	Yes
conditionExpression	Condition that must be true for the update to occur	properties.manufacturer == 'honda', etc.	String	Yes
callback.url	URL to send callback notifications upon completion	https://many-baby-86.webhook.cool	URL String	No

entityInstanceId	properties	conditionExpression
testfives:a5fb93b0-e1b8-5acf-9cb8-351cee15bcd2	{"manufacturer": "honda"}	properties.manufacturer == 'hyundai'
testfives:a5fb93b0-e1b8-5acf-9cb8-351cee15bcd2	{"manufacturer": "hyundai"}	properties.manufacturer == 'honda'
testfives:a5fb93b0-e1b8-5acf-9cb8-351cee15bcd2	{"manufacturer": "hyundai"}	properties.manufacturer == 'toyota'

Updated 16 Oct 2024

Did this page help you?

How to: Implement Custom Code in Entity Service

Participant