REST API:bulk record Resource

Manage multiple Object records using the REST API.

About the Bulk Record Resource

Available Objects

These objects are available in the record Resource

• System Objects (except the special System Objects, listed below)
• Custom Objects

Predefined Custom Object Fields

Every Custom Object is created with a number of fields that are automatically modified for each record.

Learn more: Custom Object#Predefined Fields

Data Format for Different Field Types

When adding and updating records, the field type determines the data format.

Learn more: REST API:Field Type Reference

Special Considerations for Enumerated Fields

When a record contains Enumerated Fields, there are additional factors to take into account.

Learn more: Enumerated Field Behavior For REST Web Services

Special System Objects

These System Objects can not be retrieved using the record Resource. They have specific resource URLs, instead:

• User - use the user Resource
• Role - use the role Resource
• Team - use the team Resource
• USER_TEAM - use the userTeam Resource

Requirements

• The logged-in user must have the permissions needed to access and/or modify the object in question.

Record access:

In general, any user who can access an object can view all of the records it contains. (To access the object, they must be granted access to an application that contains it.) One special case occurs when a record is owned by some other member of their team. In that case, the record becomes invisible, unless View permission has enabled in their Role Permissions, or unless their Access Profile gives them Global View permission. Another special case occurs when Record Level Visibility has been enabled for an object, and visibility criteria has been specified for an individual record. In that case, a user who can see the record only when (a) They have been granted access to an application that contains the object, and (b) They match the visibility criteria specified for that record. Users with Add permission enabled in Role Permissions or the Access Profile can add records Users with Update permission enabled in Role Permissions or the Access Profile can update records Users with Delete permission enabled in Role Permissions or the Access Profile can delete records

Access to records owned by other team members:

Read: View permission enabled in Role Permissions unless Record Level Visibility has been enabled, and visibility criteria has been specified for a record. (In that case, only users who match the criteria can read the record.) Update: Update permission enabled in Role Permissions Delete: Delete permission enabled in Role Permissions

Add Records

Adds records to an Object.

Method

POST

URI

https://{yourDomain}/networking/rest/record/{objectName}/bulk/add

https://{yourDomain}/networking/rest/record/{objectName}/bulk/add?{query_parameters}

Query Parameters

• retrieveRecord (optional)
  • true: the record is also returned
  • false: the record is not returned (default)

For more information, see: Specifying Query Parameters in REST APIs

Request

One or more record structures that specify fields and a transaction ID for that record.

<syntaxhighlight lang="xml" enclose="div">

<platform>

   <record>
       <field1>...</field1>
       <field2>...</field2>
       ...
       <__transaction_id__>nnn</__transaction_id__>
   </record>
   <record>
       ...
       <__transaction_id__>nnn+1</__transaction_id__>
   </record>
     ...

</platform> </syntaxhighlight>

Notes:

• Each <fieldN> element has the name of a field in the object. For example:

<syntaxhighlight lang="java" enclose="div">

<company_name>ABC Co.</company_name> <street_address>21 Jump Street</street_address> </syntaxhighlight>

• When specifying a Multi Object Lookup field, you specify the object identifier (name or ID) in the type attribute, and the record ID as the field value. The syntax looks like this:

<syntaxhighlight lang="java" enclose="div">

<field_name type="{objectName}">{record_id}</field> </syntaxhighlight>

For example, in the Sample Order Processing System, if priority tags were in a separate table, then the field might look like this:

<syntaxhighlight lang="java" enclose="div">

<tag type="Priority_Tag">9467890</tag> </syntaxhighlight>

• To not trigger the rules via REST API, use the following parameter:

<syntaxhighlight lang="java" enclose="div">

<PLATFORM.PARAMS.RECORD.DO_NOT_EXEC_DATA_POLICY>1</PLATFORM.PARAMS.RECORD.DO_NOT_EXEC_DATA_POLICY> </syntaxhighlight>

Response

<syntaxhighlight lang="xml" enclose="div">

<platform>

   <message>
       0
       <description>Success</description>
   </message>
   <id>...</id>      
   ... 

</platform> </syntaxhighlight> One <id> element is returned for added record, giving its record ID.

If the retrieveRecord query parameter was specified, the response contains one <record> element for each add. The <id> is contained within that element.

A <message> element is returned for each failure. That element contains the error code, description, and the <__transaction_id__> element to identify the record that failed.

Update Record

Updates records in an Object.

Method

PUT

URI

https://{yourDomain}/networking/rest/record/{objectName}/bulk/update

https://{yourDomain}/networking/rest/record/{objectName}/bulk/update?{query_parameters}

Query Parameters

• retrieveRecord (optional)
  • true: the record is also returned
  • false: the record is not returned (default)

For more information, see: Specifying Query Parameters in REST APIs

Request

One or more record structures that specify fields to update and a transaction ID for that record.

<syntaxhighlight lang="xml" enclose="div">

<platform>

   <record>
       <id>...</id>              
       <field1>...</field1>
       <field2>...</field2>
       ...
       <__transaction_id__>nnn</__transaction_id__>
   </record>
   <record>
       <id>...</id>
       ...
       <__transaction_id__>nnn+1</__transaction_id__>
   </record>
     ...

</platform> </syntaxhighlight>

Notes:

• Each <__transaction_id__> elements are optional (but highly desirable) elements that can be added. Each should have a unique value. When an error occurs, that value is included to identify the record that failed.

• Each <fieldN> element has the name of a field in the object. For example:

<syntaxhighlight lang="java" enclose="div">

<company_name>ABC Co.</company_name> <street_address>21 Jump Street</street_address> </syntaxhighlight>

• When specifying a Multi Object Lookup field, you specify the object identifier (name or ID) in the type attribute, and the record ID as the field value. The syntax looks like this:

<syntaxhighlight lang="java" enclose="div">

<field_name type="{objectName}">{record_id}</field> </syntaxhighlight>

For example, in the Sample Order Processing System, if priority tags were in a separate table, then the field might look like this:

<syntaxhighlight lang="java" enclose="div">

<tag type="Priority_Tag">9467890</tag> </syntaxhighlight>

• To not trigger the rules via REST API, use the following parameter:

<syntaxhighlight lang="java" enclose="div">

<PLATFORM.PARAMS.RECORD.DO_NOT_EXEC_DATA_POLICY>1</PLATFORM.PARAMS.RECORD.DO_NOT_EXEC_DATA_POLICY> </syntaxhighlight>

• Each <fieldN> element has the name of a field in the object.

Response

<syntaxhighlight lang="xml" enclose="div">

<platform>

   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight> If the retrieveRecord query parameter was specified, the response contains one <record> element for each add.

A <message> element is returned for each failure. That element contains the error code, description, and the <__transaction_id__> element to identify the record that failed.

Delete Record

Deletes records in an Object.

Method

DELETE

URI

https://{yourDomain}/networking/rest/record/{objectName}/bulk/delete

Request

One or more record structures that specify the IDs of records to delete and a transaction ID for that record.

<syntaxhighlight lang="xml" enclose="div">

<platform>

   <record>
       <id>...</id>
       <__transaction_id__>nnn</__transaction_id__>
   </record>
   <record>
       <id>...</id>
       <__transaction_id__>nnn+1</__transaction_id__>
   </record>
     ...

</platform> </syntaxhighlight>

Response

<syntaxhighlight lang="xml" enclose="div">

<platform>

   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight> One or more messages are returned if there are any failures. That element contains the error code, description, and the <__transaction_id__> element to identify the record that failed.