--- title: "Batch upsert a JSON array" method: POST path: "/batchupsert_4FY_v1" --- # Batch upsert a JSON array `POST /batchupsert_4FY_v1` Perform batch upserts of JSON arrays ## Request body - object - `dataOptions` object, required — The information that determines the behavior of the batch upsert operations. - `table` string, required — The type of records to alter. Can be either Documents or Contacts. - `subtypeForNewRecords` string — The contact or asset subtype of any newly-created records. This is required when your call creates new records.
This parameter uses the DataTable API syntax for assets and Contacts in the format {Documents-or-Contacts}.{Asset_type}.{Asset_subtype}. For example, for a standard video you would use Documents.Video.Default.
For more information on asset types and subtypes, go to the Assets article. - `fieldToMatch` 'MediaEncryptedIdentifier' | 'CoreField.Identifier' | 'CoreField.Id_client' | 'CoreField.OriginalFileName', required — The field used to identify records to update in Orange Logic. This field must match the field used to identify records to update or create in the records object.

The MediaEncryptedIdentifier is the Record ID.
The CoreField.Identifier is the Unique ID.
The CoreField.Id_client is the Legacy ID.
The CoreField.OriginalFileName is the Original File Name.

- `ignoreExistingRecords` boolean — Whether to update records that already exist in the Orange Logic database.

When true, the call returns the code IGNORED_EXISTING_RECORD if a provided record is found in the Orange Logic database.
When false, the call updates the provided record.

- `ignoreMissingRecords` boolean — Whether to create new records if a provided record does not match any records in the Orange Logic database.

When true, the call returns the code IGNORED_MISSING_RECORD if a provided record is not found.
When false, the call creates a new database entry with the provided record if that record is not found in the Orange Logic database.

- `multiValueSeparator` string — The separator used to pass values to a multi-valued field, including an authority list, with a single string. For example, let’s say you want a multi-valued field to include the values red, blue, and yellow. If you leave the default multiValueSeparator pipe (|), your field entry would be "red|blue|yellow".
However, we recommend instead using an array of strings with the syntax ["red", "blue", "yellow"] because it allows more flexibility in your field entries. - `augmentAuthorityListsOnTheFly` boolean — Whether to create new tags if the provided tags do not exist in a multi-valued field’s authority list.

When true, if one of the values assigned to a multi-valued field doesn’t exist in that field’s authority list, Orange Logic creates a new tag for that value, includes it in the authority list, and assigns it to the multi-value field.
When false, if a value assigned to a multi-valued field doesn’t exist in that field’s authority list, Orange Logic does not create a new tag or assign the value to that field.

- `maxRecordsAffected` integer — The maximum number of Orange Logic database records that the call alters for each record submitted in the call. If Orange Logic finds more records than the maximum specified, it returns an error and doesn’t make any updates.
For example, let’s say you want to update the record with the Original File Name “London sunset.” If you set this parameter to one and more than one Orange Logic record has “London sunset” as the Original File Name, Orange Logic will not change any records. - `indexInBackground` boolean — Set to `true` to delay indexing and speed up the API call processing time.
This parameter is available beginning in [Orange Logic Ottawa](https://developer.orangelogic.com/reference/about#orange-logic-api-versioning). - `indexingPriority` 'Medium' | 'Low' | 'VeryLow' — Forces the records to be indexed in a lower-priority queue to avoid impacting the primary indexing queue. For example, if you are calling large batches of records, the calls might fire faster than the database can index them. You can append IndexingPriority=Low to avoid overloading the queue. Leave this parameter blank to keep the call in a high priority indexing queue.
This parameter is available beginning in [Orange Logic Ottawa](https://developer.orangelogic.com/reference/about#orange-logic-api-versioning). - `executionOptions` object — Determines how Orange Logic completes the call. - `executeSynchronously` boolean — Whether the batch job is executed synchronously (foreground) or asynchronously via the agent job (background).

When true, the API call is executed synchronously and you must wait until the server returns the response, including all the results of the batch operation.
When false, the API call is executed asynchronously. The batch job is passed to the agent and the API responds immediately with the jobRecordID of the asynchronous processing task. You can use this processing task recordID to query the status and the result of the batch job via the Query asynchronous batch upsert calls API or in the Orange Logic interface in Administration > Maintenance > Show Processing Tasks.

- `successWebHookEndpoint` string — The webhook that receives success notifications for each upsert operation in an asynchronous batch. - `failureWebHookEndpoint` string — The webhook that receives failure notifications for each upsert operation in an asynchronous batch. - `webHookCustomHttpHeaders` object — The custom header is included in the **POST** request to the webhook endpoints. You can use this to add extra context to the webhook notifications with the format "description": "string". - `jobID` string — Example custom webhook header. - `records` object[], required — An array that includes one object for each record you want to update or create. Each object must include the field you used in the fieldsToMatch parameter. This field is used to find the record in the Orange Logic platform. You can update multiple fields for each record. - `CoreField.Identifier` string — The record's Unique ID. Enter only if you selected this in the fieldToMatch parameter. - `CoreField.MediaEncryptedIdentifier` string — The record's Media Encrypted Identifier, or Record ID. Enter only if you selected this in the fieldToMatch parameter. - `CoreField.Id_client` string — The record’s Legacy Identifier. Enter only if you selected this in the fieldToMatch parameter. - `Corefield.OriginalFileName` string — The record's Original File Name. Enter only if you selected this in the fieldToMatch parameter. - `CoreField.Title` string — The title of the updated or newly created record. (The title is not required; this is just an example of metadata you might want to add to the asset.) - `CoreField.Keywords` string[] — The keywords to add to the title as an array, in the format ["Tower of London", "sightseeing"]. (Keywords are not required; this is just an example of metadata you might want to add to the asset.) - `[Custom_Metadata]` string — You can add other metadata fields with this syntax "FieldAPIname": "value". ## Response `200` 200 - union - object - `transactionID` string - `results` object[] - `recordID` string - `matchedFieldValue` string - `code` string - `error` unknown - `executeInBackground` boolean - `jobRecordID` unknown - object - `transactionID` unknown - `results` unknown - `executeInBackground` boolean - `jobRecordID` string --- [API](https://skmtc.net/orangelogic/apis/security.md) · [All operations](https://skmtc.net/orangelogic/apis/security/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orangelogic/security/versions/c8e945426c5e/schema)