Bank Details Autofill in the CRM Card CRM_BANK_DETAIL_AUTOCOMPLETE
Choose a tool for developing with an AI agent:
- use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
- use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation
Scope:
placement, crm
The CRM_BANK_DETAIL_AUTOCOMPLETE point connects an application handler to the bank details search in a CRM card. It is required when an application searches for and populates bank company details, for example, by BIC.
The embedding point code is passed in the PLACEMENT parameter of the placement.bind method.
The general workflow is described in the Autofilling details in the CRM card overview.
The handler will not be available in the search source selection interface until the application installation is complete. Check the application installation
Where the Widget Is Embedded
|
Embedding Point Code |
Location |
|
|
Search source in the Find details field of the Banking details section of the details form |
Where to Find It in the Interface
To reach the search field:
- Open a company or contact card
- In the Details field, click the details link
- In the details form, add banking details
The handler is connected to the Find details field in the Banking details section.
If only one search source is available, its name is shown as a hint inside the field. If there are several sources, they are offered in a list below the field as you type a query. The application handler appears in this list under the name from the TITLE parameter.

What the Handler Receives
Data is sent in a POST request: some parameters come in the handler URL query string, the rest in the request body
Array
(
[DOMAIN] => xxx.bitrix24.com
[PROTOCOL] => 1
[LANG] => en
[APP_SID] => 8b3f2c5d9c1a4f6e9d7a2b4c6f8e1a3d
[AUTH_ID] => 1f0f107e5806d5fe9a98e02021a72e57645f86a
[AUTH_EXPIRES] => 3600
[REFRESH_ID] => 1f0f107a80816604b24a8719792ac2a21d629b5
[SERVER_ENDPOINT] => https://oauth.bitrix.info/rest/
[APPLICATION_TOKEN] => ec1b2074a9d3f5c81b6e40d27a95cf38
[APPLICATION_SCOPE] => crm,placement
[member_id] => da45a03b265edd8787f8a258d793cc5d
[status] => L
[PLACEMENT] => CRM_BANK_DETAIL_AUTOCOMPLETE
[PLACEMENT_OPTIONS] => {"searchQuery":"044599999","URI":"\/bitrix\/components\/bitrix\/crm.requisite.details\/slider.ajax.php?requisite_id=n0&sessid=1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d&etype=4&eid=2979&external_context_id=COMPANY_2979&pid=1&cid=0&IFRAME=Y&IFRAME_TYPE=SIDE_SLIDER"}
)
After parsing, the PLACEMENT_OPTIONS string from this example looks like this:
{
"searchQuery": "044599999",
"URI": "/bitrix/components/bitrix/crm.requisite.details/slider.ajax.php?requisite_id=n0&sessid=1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d&etype=4&eid=2979&external_context_id=COMPANY_2979&pid=1&cid=0&IFRAME=Y&IFRAME_TYPE=SIDE_SLIDER"
}
Parameters in the Handler URL Query String
|
Parameter |
Description |
|
DOMAIN* |
The Bitrix24 address where the widget handler was invoked |
|
PROTOCOL* |
Secure or non-secure HTTP protocol:
|
|
LANG* |
The user interface language of Bitrix24 that invoked the widget. You can localize the interface language in your widget based on this value |
|
APP_SID* |
Application session identifier. Bitrix24 generates a new one each time the widget is rendered and uses it to link the js library with the application environment |
Parameters in the POST Request Body
|
Parameter |
Description |
|
AUTH_ID |
Authorization token OAuth 2 issued for the user who invoked the widget. Can be used for REST API calls on behalf of this user |
|
AUTH_EXPIRES |
Time in seconds after which the authorization token will become invalid |
|
REFRESH_ID |
Refresh token OAuth 2 issued for the user who invoked the widget. Can be used to refresh the authorization token on behalf of this user |
|
SERVER_ENDPOINT* |
Address of the Bitrix24 authorization server needed to refresh OAuth 2 tokens |
|
APPLICATION_TOKEN* |
Application token. The same value is passed in the |
|
APPLICATION_SCOPE* |
List of scopes granted to the application, separated by commas. Shows which REST API methods are available with the authorization token received |
|
member_id* |
Unique string identifier of Bitrix24 where the widget handler was invoked. |
|
status |
Type of application that registered the handler for this widget. Accepts values:
|
|
PLACEMENT* |
The placement code. You can use the same handler URL for all your widgets. The value that Bitrix24 will report in the |
|
PLACEMENT_OPTIONS |
Additional data in the form of a JSON string that defines the context of the widget execution. For example, this could be an array containing the numeric identifier of the CRM object in the detail form where the widget handler was invoked, etc. The |
Bitrix24 adds a URI key to PLACEMENT_OPTIONS — the path with the query string of the page from which the widget was opened. It arrives for any placement, along with the keys of that placement itself. The key is absent if the browser did not send the Referer header or if the widget was opened from a page on a different domain.
How to Parse the Call Context
PLACEMENT_OPTIONS arrives as a JSON string, not as an array: parse it on the handler side before use. The set of keys is specific to each placement and is described in the PLACEMENT_OPTIONS section of this page.
$placement = $_POST['PLACEMENT'] ?? '';
$options = json_decode($_POST['PLACEMENT_OPTIONS'] ?? '{}', true);
options = json.loads(request.form.get("PLACEMENT_OPTIONS", "{}") or "{}")
In B24JsSDK, there is no need to parse the string: the $b24.placement.options property returns a ready object, and $b24.placement.placement returns the placement code.
What the Handler Must Return
The handler responds with a regular HTML page — Bitrix24 displays it in a frame in place of the widget. The page must allow embedding: if the application server sends the X-Frame-Options or Content-Security-Policy headers that prohibit framing, an empty area remains in place of the widget. How to fix it is described in the article Site Does Not Allow Connection.
PLACEMENT_OPTIONS
The value of PLACEMENT_OPTIONS is passed as a JSON string with the context of the call. Along with the universal URI key, the context carries the key of the placement itself. For this placement, URI is filled in differently from the other CRM placements, so it is described in the table separately.
Required parameters are marked with *
|
Parameter |
Description |
|
searchQuery* |
The string that the user entered in the bank details search field |
|
URI* |
Address of the page the widget is opened from. The details form is a separate document of the |
OPTIONS When Registering via placement.bind
The placement supports the OPTIONS parameter of the placement.bind method. It restricts the list of countries the handler works for and is not included in the data that Bitrix24 passes to the handler during a search.
|
Parameter |
Description |
|
countries |
Country identifiers separated by commas without spaces. If the parameter is not passed, the handler is available to all countries for which the search field is open. Country identifiers can be obtained via the crm.requisite.preset.countries |
How to Return Found Options
Pass the found options using the BX24.placement.call command with the name crmShowFoundEntities.
|
Field |
Description |
|
data |
List of found options |
|
data[].id |
Option identifier on the application side |
|
data[].name |
Option name that will be shown to the user |
|
data[].phone |
Option phone. Pass the field if the number is found |
|
data[].email |
Option E-mail. Pass the field if the address is found |
|
data[].web |
Option website. Pass the field if the website is found |
BX24.placement.call(
'crmShowFoundEntities',
{
data: [
{
id: 'bank-123456789',
name: 'Ltd. Superbank',
phone: '+49 30 000-00-00',
web: 'https://bank.example.com'
}
]
}
);
How to Fill the Selected Option Into the Card
If a user selects an option from the application response, Bitrix24 triggers the onCrmEntityIsNeedToCreate interface event. Subscribe to it using the BX24.placement.bindEvent method.
The data of the selected option is passed to the onCrmEntityIsNeedToCreate event handler.
|
Field |
Description |
|
appSid |
Application session identifier in which the selected option was found |
|
data |
Selected option data from the list that the application passed via |
In the fields object, pass the bank detail fields that need to be populated in the CRM card.
BX24.placement.bindEvent('onCrmEntityIsNeedToCreate', function (eventData) {
const selected = eventData.data;
const selectedTitle = selected.title || selected.name;
BX24.placement.call(
'crmShowCreatedEntity',
{
entityType: 'bank',
id: selected.id,
title: selectedTitle,
fields: {
NAME: selectedTitle,
RQ_BANK_NAME: selectedTitle,
RQ_BIK: '123456789',
RQ_BANK_ADDR: 'Berlin',
RQ_COR_ACC_NUM: '1234567890',
RQ_SWIFT: 'EXAMPLEDE'
}
}
);
});
Fields of the crmShowCreatedEntity command:
|
Field |
Description |
|
entityType |
Type of the created option on the application side |
|
id |
Identifier of the created option on the application side |
|
title |
Name of the created option |
|
fields |
Bank details fields that need to be filled into the CRM card |
Bank detail fields:
|
Field |
Description |
|
NAME |
Bank name |
|
RQ_BANK_NAME |
Bank name in bank details |
|
RQ_BIK |
Bank BIK |
|
RQ_BANK_ADDR |
Bank address |
|
RQ_COR_ACC_NUM |
Correspondent account |
|
RQ_SWIFT |
SWIFT |
Code Examples
How to Use Examples in Documentation
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"PLACEMENT": "CRM_BANK_DETAIL_AUTOCOMPLETE",
"HANDLER": "https://your-domain.com/widgets/crm-bank-detail-autocomplete-handler.php",
"TITLE": "Bank detail search",
"LANG_ALL": {
"de": {
"TITLE": "Bank detail search"
},
"en": {
"TITLE": "Bank detail search"
}
},
"OPTIONS": {
"countries": "1"
},
"auth": "**put_access_token_here**"
}' \
https://**put_your_bitrix24_address**/rest/placement.bind
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'
declare const $b24: B24Frame
try {
const response = await $b24.actions.v2.call.make<boolean>({
method: 'placement.bind',
params: {
PLACEMENT: 'CRM_BANK_DETAIL_AUTOCOMPLETE',
HANDLER: 'https://your-domain.com/widgets/crm-bank-detail-autocomplete-handler.php',
TITLE: 'Bank detail search',
LANG_ALL: {
de: {
TITLE: 'Bank detail search',
},
en: {
TITLE: 'Bank detail search',
},
},
OPTIONS: {
countries: '1',
},
},
requestId: Text.getUuidRfc4122()
})
// The payload is available only on a successful response
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
} else {
const result = response.getData()!.result
console.info('Placement bound successfully:', result)
}
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
async function bindCrmBankDetailAutocomplete() {
try {
// Initialize the SDK inside a Bitrix24 frame
const $b24 = await B24Js.initializeB24Frame()
const response = await $b24.actions.v2.call.make({
method: 'placement.bind',
params: {
PLACEMENT: 'CRM_BANK_DETAIL_AUTOCOMPLETE',
HANDLER: 'https://your-domain.com/widgets/crm-bank-detail-autocomplete-handler.php',
TITLE: 'Bank detail search',
LANG_ALL: {
de: {
TITLE: 'Bank detail search',
},
en: {
TITLE: 'Bank detail search',
},
},
OPTIONS: {
countries: '1',
},
},
requestId: B24Js.Text.getUuidRfc4122()
})
// The payload is available only on a successful response
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
return
}
const result = response.getData().result
console.info('Placement bound successfully:', result)
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', bindCrmBankDetailAutocomplete)
</script>
try {
$response = $b24Service
->core
->call(
'placement.bind',
[
'PLACEMENT' => 'CRM_BANK_DETAIL_AUTOCOMPLETE',
'HANDLER' => 'https://your-domain.com/widgets/crm-bank-detail-autocomplete-handler.php',
'TITLE' => 'Bank detail search',
'LANG_ALL' => [
'de' => [
'TITLE' => 'Bank detail search',
],
'en' => [
'TITLE' => 'Bank detail search',
],
],
'OPTIONS' => [
'countries' => '1',
],
]
);
$result = $response->getResponseData()->getResult();
if ($result->error()) {
error_log($result->error());
} else {
echo 'Success: ' . print_r($result->data(), true);
}
} catch (Throwable $e) {
error_log($e->getMessage());
echo 'Error binding placement: ' . $e->getMessage();
}
BX24.callMethod(
'placement.bind',
{
PLACEMENT: 'CRM_BANK_DETAIL_AUTOCOMPLETE',
HANDLER: 'https://your-domain.com/widgets/crm-bank-detail-autocomplete-handler.php',
TITLE: 'Bank detail search',
LANG_ALL: {
de: { TITLE: 'Bank detail search' },
en: { TITLE: 'Bank detail search' }
},
OPTIONS: {
countries: '1'
}
},
function(result) {
if (result.error()) {
console.error(result.error());
} else {
console.log(result.data());
}
}
);
require_once('crest.php');
$result = CRest::call(
'placement.bind',
[
'PLACEMENT' => 'CRM_BANK_DETAIL_AUTOCOMPLETE',
'HANDLER' => 'https://your-domain.com/widgets/crm-bank-detail-autocomplete-handler.php',
'TITLE' => 'Bank detail search',
'LANG_ALL' => [
'de' => [
'TITLE' => 'Bank detail search',
],
'en' => [
'TITLE' => 'Bank detail search',
],
],
'OPTIONS' => [
'countries' => '1',
],
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
// client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "placement.bind", b24.Params{
"PLACEMENT": "CRM_BANK_DETAIL_AUTOCOMPLETE",
"HANDLER": "https://your-domain.com/widgets/crm-bank-detail-autocomplete-handler.php",
"TITLE": "Bank detail search",
"LANG_ALL": b24.Params{
"de": b24.Params{
"TITLE": "Bank detail search",
},
"en": b24.Params{
"TITLE": "Bank detail search",
},
},
"OPTIONS": b24.Params{
"countries": "1",
},
})
if err != nil {
return fmt.Errorf("placement.bind: %w", err)
}
// The response arrives as json.RawMessage — unmarshal it into the response
// shape of the placement.bind method, see "Response Handling" on its page.
fmt.Printf("%s\n", res.Result)
Common Mistakes
|
Mistake |
Solution |
|
|
Register the placement on behalf of an application. A placement cannot be bound with a webhook |
|
The handler is registered but does not appear in the list of search sources |
Complete the application installation and check that the |
|
The handler is unavailable for the required country |
Check the value of |
|
The handler is not called while the user is typing the query |
Bitrix24 calls the external search when the search string contains at least three characters |
|
The handler does not find the search string in the request body |
|
|
The |
The details form is a separate document of the |
|
Found options are not displayed |
Pass the array of options to the |
|
The option is not filled into the card after selection |
Subscribe to |
Other registration error codes are listed in the "Possible Error Codes" section of the placement.bind page.