Create Dataset biconnector.dataset.add
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:
biconnectorWho can execute the method: A user who has both the "Access to BI Builder" and "Access to Analytics Hub" permissions
DEPRECATED
Development of the method has been discontinued. Use biconnector.table.add.
The biconnector.dataset.add method creates a new dataset linked to a data source.
The method works only in the context of an application and only with the sources that the application created itself. When called via a webhook, the method returns the ACCESS_DENIED error
Method Parameters
Required parameters are marked with *
|
Name |
Description |
|
fields* |
An object containing data to create a new dataset. The object format:
|
Parameter fields
|
Name |
Description |
|
name* |
Dataset name. The name must start with a letter and may contain only lowercase Latin letters |
|
externalName* |
Name of the dataset in the external source, in the application. The maximum length is 512 characters |
|
externalCode* |
Unique code of the dataset in the external source, used when selecting data. The maximum length is 512 characters |
|
sourceId* |
Source identifier, can be obtained with the biconnector.source.list or biconnector.source.add method. The source must belong to the connector of the current application, otherwise the method returns |
|
verboseName |
User-friendly dataset name, for example, |
|
description |
Description of the dataset |
|
tableGroupIds |
Array of identifiers of the table groups to add the dataset table to. Each identifier is a positive integer, and the group must exist. If the parameter is not passed or an empty array is passed, the table is added to the user tables group. The list of table groups cannot be retrieved via the REST API. The biconnector.dataset.get and biconnector.dataset.list methods do not return the groups |
|
fields* |
Array of dataset fields, (detailed description) |
Element of the fields array
Each element of the fields array is an object with three required fields and an optional field description. Field visibility is not set on creation: all fields are created visible and can be hidden later with the biconnector.dataset.fields.update method.
|
Name |
Description |
|
name* |
Field name. The name must start with a letter and may contain only uppercase Latin letters |
|
externalCode* |
External code of the field — the name the application knows the field by. Bitrix24 passes exactly this code in the data request |
|
type* |
Data type of the field. Allowed values: The value is case-sensitive: an uppercase |
|
description |
Field description. If the parameter is not passed, the description stays empty |
Field names and external codes must not repeat within one request: on a repeated name the method returns the DUPLICATE_FIELDS error, and on a repeated externalCode — VALIDATION_DUPLICATE_FIELD_CODE.
Code Examples
How to Use Examples in Documentation
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"fields": {
"sourceId": 3,
"name": "rest_dataset",
"externalName": "Sales orders",
"externalCode": "sales_orders",
"description": "Dataset description",
"fields": [
{ "type": "int", "name": "ID", "externalCode": "ID" },
{ "type": "string", "name": "NAME", "externalCode": "NAME" },
{ "type": "string", "name": "SURNAME", "externalCode": "SURNAME" },
{ "type": "double", "name": "SCORE", "externalCode": "SCORE" },
{ "type": "date", "name": "DATA", "externalCode": "DATA" },
{ "type": "datetime", "name": "TIME", "externalCode": "TIME" }
]
},
"auth": "**put_access_token_here**"
}' \
https://**put_your_bitrix24_address**/rest/biconnector.dataset.add
// 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
// Methods of this section put errors inside result and answer with HTTP 200
type BiconnectorError = {
error: {
error: string
error_description: string
}
}
// Shape of the payload returned in result (match the "response handling" section of the page)
type DatasetAddResult = {
id: number
}
try {
const response = await $b24.actions.v2.call.make<DatasetAddResult | BiconnectorError>({
method: 'biconnector.dataset.add',
params: {
fields: {
sourceId: 3,
name: 'rest_dataset',
externalName: 'Sales orders',
externalCode: 'sales_orders',
description: 'Dataset description',
fields: [
{ type: 'int', name: 'ID', externalCode: 'ID' },
{ type: 'string', name: 'NAME', externalCode: 'NAME' },
{ type: 'string', name: 'SURNAME', externalCode: 'SURNAME' },
{ type: 'double', name: 'SCORE', externalCode: 'SCORE' },
{ type: 'date', name: 'DATA', externalCode: 'DATA' },
{ type: 'datetime', name: 'TIME', externalCode: 'TIME' },
],
},
},
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
// The SDK sees HTTP 200 as success, so check the error inside result yourself
if ('error' in result) {
console.error(result.error.error, result.error.error_description)
} else {
console.info('Created dataset id:', result.id)
}
}
} 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 addDataset() {
try {
// Initialize the SDK inside a Bitrix24 frame
const $b24 = await B24Js.initializeB24Frame()
const response = await $b24.actions.v2.call.make({
method: 'biconnector.dataset.add',
params: {
fields: {
sourceId: 3,
name: 'rest_dataset',
externalName: 'Sales orders',
externalCode: 'sales_orders',
description: 'Dataset description',
fields: [
{ type: 'int', name: 'ID', externalCode: 'ID' },
{ type: 'string', name: 'NAME', externalCode: 'NAME' },
{ type: 'string', name: 'SURNAME', externalCode: 'SURNAME' },
{ type: 'double', name: 'SCORE', externalCode: 'SCORE' },
{ type: 'date', name: 'DATA', externalCode: 'DATA' },
{ type: 'datetime', name: 'TIME', externalCode: 'TIME' },
],
},
},
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
// The SDK sees HTTP 200 as success, so check the error inside result yourself
if (result && result.error) {
console.error(result.error.error, result.error.error_description)
return
}
console.info('Created dataset id:', result.id)
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', addDataset)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
try:
bitrix_response = client.biconnector.dataset.add(
fields={
"sourceId": 3,
"name": "rest_dataset",
"externalName": "Sales orders",
"externalCode": "sales_orders",
"description": "Dataset description",
"fields": [
{
"type": "int",
"name": "ID",
"externalCode": "ID",
},
{
"type": "string",
"name": "NAME",
"externalCode": "NAME",
},
{
"type": "string",
"name": "SURNAME",
"externalCode": "SURNAME",
},
{
"type": "double",
"name": "SCORE",
"externalCode": "SCORE",
},
{
"type": "date",
"name": "DATA",
"externalCode": "DATA",
},
{
"type": "datetime",
"name": "TIME",
"externalCode": "TIME",
},
],
},
).response
result = bitrix_response.result
# Methods of this section put errors inside result and answer with HTTP 200
if isinstance(result, dict) and "error" in result:
print(
"BIconnector error",
f"error: {result['error']['error']}",
f"error_description: {result['error']['error_description']}",
sep="\n",
)
else:
print(result)
except BitrixAPIError as error:
print(
"Bitrix API error",
f"error: {error.error}",
f"error_description: {error.error_description}",
sep="\n",
)
except BitrixSDKException as error:
print(f"Bitrix SDK error: {error.message}")
except Exception as error:
print(f"Unexpected error: {error}")
try {
$response = $b24Service
->core
->call(
'biconnector.dataset.add',
[
'fields' => [
'sourceId' => 3,
'name' => 'rest_dataset',
'externalName' => 'Sales orders',
'externalCode' => 'sales_orders',
'description' => 'Dataset description',
'fields' => [
['type' => 'int', 'name' => 'ID', 'externalCode' => 'ID'],
['type' => 'string', 'name' => 'NAME', 'externalCode' => 'NAME'],
['type' => 'string', 'name' => 'SURNAME', 'externalCode' => 'SURNAME'],
['type' => 'double', 'name' => 'SCORE', 'externalCode' => 'SCORE'],
['type' => 'date', 'name' => 'DATA', 'externalCode' => 'DATA'],
['type' => 'datetime', 'name' => 'TIME', 'externalCode' => 'TIME'],
],
],
]
);
$result = $response
->getResponseData()
->getResult();
if ($result->error()) {
error_log($result->error());
echo 'Error: ' . $result->error();
} else {
$data = $result->data();
// Methods of this section put errors inside result and answer with HTTP 200
if (isset($data['error'])) {
echo 'BIconnector error: ' . $data['error']['error'] . ': ' . $data['error']['error_description'];
} else {
echo 'Success: ' . print_r($data, true);
}
}
} catch (Throwable $e) {
error_log($e->getMessage());
echo 'Error adding dataset: ' . $e->getMessage();
}
BX24.callMethod(
'biconnector.dataset.add',
{
fields: {
"sourceId": 3,
"name": "rest_dataset",
"externalName": "Sales orders",
"externalCode": "sales_orders",
"description": "Dataset description",
"fields": [
{ "type": "int", "name": "ID", "externalCode": "ID" },
{ "type": "string", "name": "NAME", "externalCode": "NAME" },
{ "type": "string", "name": "SURNAME", "externalCode": "SURNAME" },
{ "type": "double", "name": "SCORE", "externalCode": "SCORE" },
{ "type": "date", "name": "DATA", "externalCode": "DATA" },
{ "type": "datetime", "name": "TIME", "externalCode": "TIME" }
]
}
},
(result) => {
if (result.error()) {
console.error(result.error());
return;
}
const data = result.data();
// Methods of this section put errors inside result and answer with HTTP 200
if (data && data.error) {
console.error(data.error.error, data.error.error_description);
return;
}
console.info(data);
}
);
require_once('crest.php');
$result = CRest::call(
'biconnector.dataset.add',
[
'fields' => [
'sourceId' => 3,
'name' => 'rest_dataset',
'externalName' => 'Sales orders',
'externalCode' => 'sales_orders',
'description' => 'Dataset description',
'fields' => [
[ 'type' => 'int', 'name' => 'ID', 'externalCode' => 'ID' ],
[ 'type' => 'string', 'name' => 'NAME', 'externalCode' => 'NAME' ],
[ 'type' => 'string', 'name' => 'SURNAME', 'externalCode' => 'SURNAME' ],
[ 'type' => 'double', 'name' => 'SCORE', 'externalCode' => 'SCORE' ],
[ 'type' => 'date', 'name' => 'DATA', 'externalCode' => 'DATA' ],
[ 'type' => 'datetime', 'name' => 'TIME', 'externalCode' => 'TIME' ]
]
]
]
);
// Methods of this section put errors inside result and answer with HTTP 200
if (isset($result['result']['error'])) {
echo 'BIconnector error: ' . $result['result']['error']['error']
. ': ' . $result['result']['error']['error_description'];
} else {
echo '<PRE>';
print_r($result);
echo '</PRE>';
}
// client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "biconnector.dataset.add", b24.Params{
"fields": b24.Params{
"sourceId": 3,
"name": "rest_dataset",
"externalName": "Sales orders",
"externalCode": "sales_orders",
"description": "Dataset description",
"fields": []b24.Params{
{
"type": "int",
"name": "ID",
"externalCode": "ID",
},
{
"type": "string",
"name": "NAME",
"externalCode": "NAME",
},
{
"type": "string",
"name": "SURNAME",
"externalCode": "SURNAME",
},
{
"type": "double",
"name": "SCORE",
"externalCode": "SCORE",
},
{
"type": "date",
"name": "DATA",
"externalCode": "DATA",
},
{
"type": "datetime",
"name": "TIME",
"externalCode": "TIME",
},
},
},
})
if err != nil {
return fmt.Errorf("biconnector.dataset.add: %w", err)
}
// Methods of this section put errors inside result and answer with HTTP 200.
var apiErr struct {
Error *struct {
Error string `json:"error"`
Description string `json:"error_description"`
} `json:"error"`
}
if err := json.Unmarshal(res.Result, &apiErr); err == nil && apiErr.Error != nil {
return fmt.Errorf("biconnector.dataset.add: %s: %s", apiErr.Error.Error, apiErr.Error.Description)
}
var item struct {
ID b24.ID `json:"id"`
}
if err := json.Unmarshal(res.Result, &item); err != nil {
return fmt.Errorf("parse response: %w", err)
}
fmt.Println(item.ID)
Response Handling
HTTP status: 200
{
"result": {
"id": 10
},
"time": {
"start": 1725013197.635808,
"finish": 1725013198.580873,
"duration": 0.9450650215148926,
"processing": 0.6822988986968994,
"date_start": "2024-08-30T12:19:57+02:00",
"date_finish": "2024-08-30T12:19:58+02:00",
"operating": 0
}
}
Returned Data
|
Name |
Description |
|
result |
Root element of the response (detailed description) |
|
time |
Information about the request execution time |
The result object
|
Name |
Description |
|
id |
Identifier of the created dataset. Use it in the biconnector.dataset.get, biconnector.dataset.update, and biconnector.dataset.fields.update methods |
Error Handling
HTTP status: 200
{
"result": {
"error": {
"error": "VALIDATION_FIELDS_NOT_PROVIDED",
"error_description": "Fields not provided."
}
}
}
The method returns an error inside the result field and with HTTP status 200. Check result.error: the SDK wrappers parse only the top level of the response and treat such an error as a success
|
Name |
Description |
|
error |
String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only |
|
error_description |
Error message for the developer. Do not show it to the end user without processing |
Possible Error Codes
|
Code |
Description |
Value |
|
|
Access denied. |
One of the two permissions is missing, BI Builder external data sources are not available on this Bitrix24, or the method was called via a webhook or outside the application context |
|
|
Fields not provided. |
Fields were not passed in the request |
|
|
Unknown parameters: #LIST_OF_PARAMS# |
Unknown parameters detected: list |
|
|
Field "#TITLE#" is required. |
Required field #TITLE# was not provided |
|
|
Field "#TITLE#" is read only. |
Field #TITLE# is read-only and cannot be modified |
|
|
Field "#TITLE#" must be of type #TYPE#. |
Field #TITLE# must be of type #TYPE# |
|
|
Field "tableGroupIds" must be an array of positive integers. |
The |
|
|
Field "description" must be of type string. |
A field description in the |
|
|
Table group was not found. |
There is no table group with one of the identifiers from |
|
|
The length of "VERBOSE_NAME" should not exceed 255 characters. |
The |
|
|
Source was not found. |
The source does not exist or belongs to another application |
|
|
Table with this name already exists. |
The name is taken by a table that already exists in BI Builder itself |
|
|
Dataset name is reserved by a system table. |
The dataset name is taken by a BI Builder system table |
|
|
A table named "#NAME#" already exists. |
The #NAME# name is already taken by another dataset in Bitrix24. The name is checked across the entire Bitrix24, not within the source |
|
|
$fields is empty |
An empty |
|
|
Duplicate column names: #FIELD_NAMES#. |
The |
|
|
Dataset name has to start with a lowercase Latin character. Possible entry includes lowercase Latin characters (a-z), numbers (0-9) and underscores. |
Invalid format of the dataset name. The name must start with a letter and may contain only lowercase Latin letters |
|
|
Dataset name must not exceed 230 characters. |
Dataset name must not exceed 230 characters |
|
|
Duplicate values found in the "code" parameter: #LIST_CODES# |
Duplicates found in the |
|
|
Field must include the required parameters: "name", "externalCode" and "type". |
Field must include the parameters |
|
|
Field "name" has to start with an uppercase Latin character. Possible entry includes uppercase Latin characters (A-Z), numbers (0-9) and underscores. |
Invalid format of the field name. The name must start with a letter and may contain only uppercase Latin letters |
|
|
Field "name" must not exceed 32 characters. |
The field name must not exceed 32 characters |
|
|
Invalid field type. |
Invalid field type |
|
Empty value |
Error creating table. or Error adding dataset |
The dataset could not be created in BI Builder. This error has no string code of its own: the |
The method creates two objects at once: a table — the same object as biconnector.table.add creates — and a BI Builder dataset on top of it. If the second step fails, the first one is rolled back: no partially created table is left. The biconnector.table.add method has no such step, so it never returns this error
Statuses and System Error Codes
HTTP Status: 4xx, 5xx
The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.
|
Status |
Code |
Description |
|
|
|
An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support |
|
|
|
The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support |
|
|
|
The request intensity limit has been exceeded |
|
|
|
The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit |
|
|
|
The request contains no authorization data: neither an access token nor a webhook code was passed |
|
|
|
Methods are called over the HTTPS protocol only |
|
|
|
The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support |
|
|
|
REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — |
|
|
|
No active webhook with the specified user identifier and secret code was found |
|
|
|
No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope |
|
|
|
The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with |
|
|
|
The access token has expired |
|
|
|
The application is installed, but the Bitrix24 administrator has granted access to it only to specific users |
|
|
|
The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site |
Continue Learning
- Deprecated biconnector.dataset.* Methods: Overview of Methods
- Update Dataset biconnector.dataset.update
- Get dataset by id biconnector.dataset.get
- Get a List of Datasets biconnector.dataset.list
- Delete dataset biconnector.dataset.delete
- Update Dataset Fields biconnector.dataset.fields.update
- Get Dataset Fields biconnector.dataset.fields