Documentation

batch

Batch call method.

It is not uncommon for an application to send requests in series. To optimize the process, use this function to batch call REST methods instead of sending requests one by one.

Parameters

Parameter Description
halt Determines if the sequence of requests to be aborted in case of an error.
cmd Specifies a standard array of requests. Notice that the request data must be quoted; therefore, the request data inside a request must be quoted again.

Note: Number of batch calls is limited to 50.

The request array can be a simple indexed array or an associative array. The return value of a preceding request may be used in each subsequent request by addressing it in a result array:

$result[request_ID][response_field]

where the request ID is the request key in the request array.

Example

https://my.bitrix24.com/rest/batch.xml?auth=d161f25928c3184678924ec127edd29a&halt=0&cmd[get_user]=user.current%3F&cmd[get_department]=department.get%3FID%3D%2524result%255Bget_user%255D%255BUF_DEPARTMENT%255D

Attention: URL parameters are encoded. It's strongly recommended to encode parameters as a requirement, otherwise correct results aren't guaranteed.

XML response:

<response>
	<result>
		<result>
			<get_user>
				<ID>1</ID>
				<LOGIN>admin</LOGIN>
				<ACTIVE>1</ACTIVE>
				<EMAIL>sigurd@example.com</EMAIL>
				<NAME>Admin</NAME>
				<LAST_NAME/>
				<SECOND_NAME/>
				<PERSONAL_GENDER/>
				<PERSONAL_PROFESSION/>
				<PERSONAL_WWW/>
				<PERSONAL_BIRTHDAY>1955-04-10T00:00:00+03:00</PERSONAL_BIRTHDAY>
				<PERSONAL_PHOTO>/upload/main/80c/44169_C5_PrimalWaterE500CC.jpg</PERSONAL_PHOTO>
				<PERSONAL_ICQ/>
				<PERSONAL_PHONE/>
				<PERSONAL_FAX/>
				<PERSONAL_MOBILE/>
				<PERSONAL_PAGER/>
				<PERSONAL_STREET/>
				<PERSONAL_CITY/>
				<PERSONAL_STATE/>
				<PERSONAL_ZIP/>
				<PERSONAL_COUNTRY>0</PERSONAL_COUNTRY>
				<WORK_COMPANY/>
				<WORK_POSITION/>
				<UF_DEPARTMENT>
				<item>128</item>
				</UF_DEPARTMENT>
				<UF_INTERESTS/>
				<UF_SKILLS/>
				<UF_WEB_SITES/>
				<UF_XING/>
				<UF_LINKEDIN/>
				<UF_FACEBOOK/>
				<UF_TWITTER/>
				<UF_SKYPE/>
				<UF_DISTRICT/>
				<UF_PHONE_INNER/>
			</get_user>
			<get_department>
				<item>
					<ID>128</ID>
					<NAME>IT Department</NAME>
					<SORT>500</SORT>
					<PARENT>114</PARENT>
					<UF_HEAD>255</UF_HEAD>
				</item>
			</get_department>
		</result>
		<result_error/>
		<result_total>
			<get_department>1</get_department>
		</result_total>
		<result_next/>
	</result>
</response>

Example of JSON string for allocating into POST query body for the batch method.

BX24.callMethod(
	'batch',
	{
		'halt': 0,
		'cmd': {
			'user': 'user.get?ID=1',
			'first_lead': 'crm.lead.add?fields[TITLE]=Test Title',
			'user_by_name': 'user.search?NAME=Test2',
			'user_lead': 'crm.lead.add?fields[TITLE]=Test Assigned&fields[ASSIGNED_BY_ID]=$result[user_by_name][0][ID]',
		}
	},
	function(result)
	{
		console.log(result.answer);
	}
);

Result:

  • user - returns user with ID = 1
  • first_lead - creates a lead
  • user_by_name - finds a user with the name "Test2"
  • user_lead - creates a lead with a responsible user, found in user_by_name

For PHP, it's recommended to use CRest::callBatch()

See Also

© «Bitrix24», 2001-2024
Up