#Related data (include)

Load related entities together with the primary records in a single request. Instead of separate calls to fetch a contact, company, or assignee — pass the include parameter, and VibeCode returns everything in the _included field.

The include parameter is optional and works in three places:

  • GET /v1/{entity}/{id}?include=... — fetch a single record
  • GET /v1/{entity}?include=... — fetch a list
  • POST /v1/{entity}/search — search (include in the request body as an array of strings)

#How to use

List relation names separated by commas:

#curl

Terminal 
curl "https://vibecode.bitrix24.tech/v1/deals/741?include=contact,company" \
  -H "X-Api-Key: YOUR_API_KEY"

#JavaScript

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/deals/741?include=contact,company', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()

// data._included.contacts — array of deal contacts
// data._included.company  — company (object or null)

Related data appears in the _included field of each record:

JSON 
{
  "success": true,
  "data": {
    "id": 741,
    "title": "Equipment delivery",
    "contactId": 71,
    "companyId": 15,
    "_included": {
      "contacts": [
        {
          "id": 71,
          "name": "Ivan",
          "lastName": "Petrov",
          "phone": [{ "VALUE": "+79161234567" }],
          "isPrimary": true,
          "sort": 10
        }
      ],
      "company": {
        "id": 15,
        "title": "Romashka LLC",
        "industry": "IT"
      }
    }
  }
}

#Two types of relations

#One-to-one

The entity holds a reference field to the related object (for example, companyId on a contact). The result is a single object or null.

GET /v1/leads/50?include=contact
JSON 
{
  "data": {
    "id": 50,
    "title": "Website request",
    "contactId": 71,
    "_included": {
      "contact": {
        "id": 71,
        "name": "Ivan",
        "lastName": "Petrov"
      }
    }
  }
}

If the reference field is empty or equals 0, null is returned:

JSON 
{
  "_included": {
    "contact": null
  }
}

#Many-to-many

A relation through an intermediate table. The result is an array of objects with additional relation fields.

GET /v1/deals/741?include=contact
JSON 
{
  "_included": {
    "contacts": [
      {
        "id": 71,
        "name": "Ivan",
        "lastName": "Petrov",
        "isPrimary": true,
        "sort": 10,
        "roleId": 0
      },
      {
        "id": 85,
        "name": "Maria",
        "lastName": "Sidorova",
        "isPrimary": false,
        "sort": 20,
        "roleId": 0
      }
    ]
  }
}

Note: the relation name in the request is contact (singular), while in the response it is contacts (plural). VibeCode automatically pluralizes the name for arrays.

Additional relation fields (isPrimary, sort, roleId) are added to each object — their values come from the intermediate table, not from the entity itself.

#curl — list

Terminal 
curl "https://vibecode.bitrix24.tech/v1/deals?limit=10&include=company" \
  -H "X-Api-Key: YOUR_API_KEY"

#JavaScript — list

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/deals?limit=10&include=company', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data, meta } = await res.json()

for (const deal of data) {
  console.log(deal.title, '—', deal._included.company?.title ?? 'no company')
}
// meta.includeSkipped === true if records > 200

Response:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 741,
      "title": "Equipment delivery",
      "companyId": 15,
      "_included": {
        "company": { "id": 15, "title": "Romashka LLC" }
      }
    },
    {
      "id": 742,
      "title": "Tech support",
      "companyId": 15,
      "_included": {
        "company": { "id": 15, "title": "Romashka LLC" }
      }
    }
  ],
  "total": 150,
  "meta": { "hasMore": true }
}

VibeCode deduplicates requests: if several records reference the same company, it is loaded once.

In search, include is passed in the request body as an array.

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/deals/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "stageId": "NEW", "amount": { "$gte": 100000 } },
    "include": ["contact", "company"],
    "limit": 50
  }'
javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/deals/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { stageId: 'NEW', amount: { $gte: 100000 } },
    include: ['contact', 'company'],
    limit: 50,
  }),
})
const { data } = await res.json()

#Multiple relations in one request

You can request up to 3 relations at once:

GET /v1/quotes/18?include=deal,contact,company
JSON 
{
  "_included": {
    "deal": { "id": 741, "title": "Equipment delivery" },
    "contact": { "id": 71, "name": "Ivan", "lastName": "Petrov" },
    "company": { "id": 15, "title": "Romashka LLC" }
  }
}

#Limits

Parameter Value
Maximum relations per request 3
Maximum records for include 200

If a list or search has more than 200 records, include is skipped and a flag is added to meta:

JSON 
{
  "data": [ ... ],
  "meta": {
    "hasMore": true,
    "includeSkipped": true
  }
}

To get related data for large result sets — reduce limit to 200 or less.

#Available relations per entity

You can find the available includes for a specific entity via the fields endpoint:

Terminal 
curl "https://vibecode.bitrix24.tech/v1/deals/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

The response contains an include field with the list of available relations:

JSON 
{
  "success": true,
  "data": {
    "fields": { ... },
    "include": ["contact", "company"]
  }
}

Available relations depend on the entity. Which includes a specific entity supports is stated in each method's documentation and in the GET /v1/{entity}/fields response (the include field).

#Errors

HTTP Code Description
400 INCLUDE_LIMIT_EXCEEDED More than 3 relations requested
400 INVALID_INCLUDE Relation not found. The response contains the list of available relations

If an entity has no relations at all (for example, departments), any include returns INVALID_INCLUDE with an empty Available: list.

Error example:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_INCLUDE",
    "message": "Unknown include 'manager'. Available: contact, company, quote"
  }
}