Edit multiple records with only one network roundtrip
You can use a batch upsert call to create or update records in the Orange Logic platform. You provide a list of records as either a JSON array or CSV file, and the API then performs a series of record updates. If a record doesn’t exist, it is created. Using these endpoints allows you to edit multiple records with only one network roundtrip.
There are three batch upsert endpoints:
- Batch upsert a JSON array: This call performs batch upserts when the list of records to upsert is a JSON array.
- Batch upsert a CSV file: This call performs batch upserts when the list of records is a CSV file.
- Query the status of asynchronous Batch Upsert requests: This call allows you to query the status and results of an asynchronous batch upsert request.
Note
These endpoints are available beginning in Orange Logic Juneau.
Call execution
Record updates
Record updates with these APIs are done in parallel, not sequentially. If you need to make sequential updates, use multiple calls.
Caution
Do not update the same records multiple times within a batch. Doing so could cause your updates to happen out of order, resulting in changes you did not intend.
Synchronous versus asynchronous execution
The batch upsert endpoints can run:
- Synchronously in the Orange Logic platform.
- Asynchronously in the background via an agent job.
When you run a call synchronously, you must wait until the server responds before continuing to use the Orange Logic platform. When you run a call asynchronously, you can use the Orange Logic platform while the call is executed. You can receive updates on the call’s status either via a separate endpoint that regularly queries the request’s status or instantaneously via webhooks.
Note
Asynchronous processing is off by default. To activate it, submit a support request.
Call responses
The batch upsert endpoints return the following information:
| Parameter | Returned Information |
|---|---|
transactionID | If needed, use this parameter to revert a batch request’s operations. |
results | The array of records affected by the batch operation. Each result in the array includes:
|
code | The operation’s return code for each record. Possible values:
|
error | A detailed error message. Only returned if applicable. |
executeInBackground | A boolean field that indicates whether the batch request was handled in the background (agent) or foreground (web).
|
jobRecordID | The asynchronous processing task recordID for the batch operation. Record updates can be received via webhook instantly if the webhook endpoints are specified. No jobRecordID is returned for synchronous tasks. |