API Reference

Special parameters

You can add special parameters to your DataTable calls to change the default behavior of the call. Each parameter is described in the sections below.

Automatic emails when creating or updating user accounts

When you create an account on a production site, Orange Logic emails that user to notify them of their new account.

When you create an account on a test site, Orange Logic does not email that user.

Review the sections below to change this behavior on either site.

Email notifications on production sites

When you create an account on a production site (via API or in the Orange Logic interface), this triggers the Administrator created a new account Event Type, which sends an email notification to the new user.

If you do not want users to receive email notifications, remove [EMAIL] from the Emails To field in the Administrator created a new account Event Type in the Orange Logic interface.

"Administrator Created a New Account" Event Type

"Administrator created a new account" Event Type

🎓

Insight: Events

Events are logs of all actions performed within the Orange Logic platform (with the exception of simple navigation). You can view events in two places:

  1. The Events module (Administration > Events > Events) keeps a history of all Events.
  2. Other modules have an Events tab or button. For example, all accounts have an "Events" tab that shows events related to that user, such as when they accepted or rejected the Terms and Conditions or when their account was validated or rejected. You can also view an asset’s events, which could include uploading an asset or new version, performing optical character recognition (OCR), and more.

For more information, go to Events and Event Types.

Email notifications on test sites

If you are using CSVs to create accounts via API in a test or pre-prod environment, the “Administrator created a new Contact" event will be triggered and logged, but Orange Logic will not send any email notifications to the new users.

If you want emails to be sent, add &AllowNotifications=1 to your call.

Example:

POST or GET ** /API/DataTable/V2.2/Contacts.Client.Default:Create?CoreField.First_Name:=Kristen&CoreField.Last_Name:=Harrison&CoreField.Counry:=United States of America&CoreField.Email1:[email protected]&AllowNotifications=1

List or update fields

Field length safety

If you create or update fields with values that exceed the maximum length for the field, you will get a failure response indicating the field and its maximum length.

Example failure response:

<Message>Update failed for the given records</Message>  
<ErrorList>  
\<Document.CoreField.Title>This field cannot contain more than 200 characters\</Document.CoreField.Title>  
</ErrorList>

You can retrieve the maximum length for a field with the List all metadata fields call. The returned attribute is DataLength.

You can add FieldLengthSafety=1 to a call to:

  • Truncate the provided value to fit within the maximum length.
  • Append the full value to the "Notes" field.

Example:

POST or GET /API/DataTable/v2.2/Documents.Image.Default:Update?CoreField.identifier=ZZ13UH3&CoreField.Title:=This is such a long title that it exceeds 200 characters and would make the API call fail. A title really should be succinct, further details about the video would be better added to the Caption field. To truncate this title after the first 200 characters, use the Field Length Safety parameter&FieldLengthSafety=1

Include blank fields

Add Verbose=1 to include all of a record’s fields in the response, even if the fields are blank.

Indexing

By default, Orange Logic indexes newly created and updated items at the time of the API call, which means there will be a delay to account for processing time.

You can change the indexing behavior by appending the following parameters and values:

  • IndexInBackground=1: Delays indexing and speeds up the API call processing time.
  • &IndexingPriority=Low: Forces the records to be indexed in a low-priority queue to avoid impacting the indexing queue. For example, if you are calling large batches of records, the calls might fire faster than the database can index them. Therefore, you can append &IndexingPriority=Low to avoid overloading the queue.

Example:

POST or GET ** /API/Datatable/v2.2/Documents.Folder.Default:Update?CoreField.identifier=ZZ13OCB&CoreField.Title:=Spring 2025 Collection&IndexInBackground=1

Update multiple records in one call

By default, you can only update one asset in a DataTable call. However, you might need to update multiple records in a single call. For example, suppose you want to update the approval date for all standard images with the original filename of “London Bridge at dusk.jpeg.” If there are multiple standard images with this file name, then you will receive this error message in the response:

<Response>
<Code>MORE_RECORDS_WOULD_BE_AFFECTED_THAN_ALLOWED</Code>
<Message>If executed, this operation would have updated 4 records. The current syntax authorizes the update of up to 1 record. To upgrade more than 1 record, please use the parameter MaxRecordsAffected (max value 100), or use the parameter ApplyAll to perform this operation on all these 4 records.</Message>
</Response>
</Result>

To update multiple assets in one call, use the MaxRecordsAffected parameter. You can set the maximum records affected to any number up to 100. If you don’t know how many records you need to update, use MaxRecordsAffected=100.

Example:

POST or GET ** /API/DataTable/V2.2/Documents.Image.Default:Update?CoreField.OriginalFileName=London Bridge at dusk.jpeg&media.Approved-Date:=03-01-2025&MaxRecordsAffected=100

The response will include a Result object for each updated asset.

Example response:

<Result>
<APIRequestInfo>
<ProviderVersion>LONDON.R2.2131E.216729</ProviderVersion>
<ProviderIdentity>OLU-T-USW2-APP</ProviderIdentity>
<ProviderID>44ddde3ac27a33c394335f249d4007d4</ProviderID>
<Module>DataTable</Module>
<APIVersion>V2.2</APIVersion>
<Resource>Documents.Image.Default:Update</Resource>
<IsLoggedIn type="Boolean">True</IsLoggedIn>
<Status>LoggedIn</Status>
<UserLogin>[email protected]</UserLogin>
<Session>Jen Demo</Session>
<TimeoutPeriodMinutes type="Numeric">20</TimeoutPeriodMinutes>
</APIRequestInfo>
<RequestInterpretation>
<Filters type="List">
<Filter>
<Field>CoreField.OriginalFileName</Field>
<Operator>=</Operator>
<OperatorDescription>Field must be equal to value</OperatorDescription>
<Value>London Bridge at dusk.jpeg</Value>
</Filter>
</Filters>
<Updates type="List">
<Update>
<Field>Media.Approved-Date</Field>
<Operator>:=</Operator>
<OperatorDescription>Assign a value to a single-value field</OperatorDescription>
<Value>03-01-2025</Value>
</Update>
</Updates>
<IgnoredParameters type="List"/>
</RequestInterpretation>
<ResponseSummary>
<NumberOfRecordsAffected type="Numeric">4</NumberOfRecordsAffected>
</ResponseSummary>
<Response>
<RecordsAffected type="List">
<Result>
<RecordID>2QDTWAWCFK8</RecordID>
<Code>SUCCESS</Code>
</Result>
<Result>
<RecordID>2QDTWAWJ6RO</RecordID>
<Code>SUCCESS</Code>
</Result>
<Result>
<RecordID>2QDTWAOP1_5</RecordID>
<Code>SUCCESS</Code>
</Result>
<Result>
<RecordID>2QDTWAO7JH7</RecordID>
<Code>SUCCESS</Code>
</Result>
</RecordsAffected>
</Response>
</Result>

Response parameters

Change the response format to JSON

All DataTable calls return responses in XML by default. You can add &format=JSON to change the response format to JSON.

Example:

POST or GET ** /API/DataTable/V2.2/Documents.Image.Default:Read?CoreField.Identifier=DM123&format=JSON

Test mode

You can append &TestMode=1 to the end of the call to validate the call prior to running it. When you run a call in test mode, the response will be identical to a live response; however, changes will not be applied to the record. This feature is similar to the “Test next record” feature in iAPI.

Advanced utility parameters

UseSystemNames Parameter

You can add &UseSystemNames=1 to return the system name of all fields instead of the user-defined field names.