For AI agents: markdown of this page — /docs-content-en/entities/invoices/fields.md documentation index — /llms.txt

Invoice fields

GET /v1/invoices/fields

Returns a description of all invoice fields, including user fields (ufCrm_*).

Examples

curl — personal key

Terminal

curl -X GET https://vibecode.bitrix24.com/v1/invoices/fields \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal

curl -X GET https://vibecode.bitrix24.com/v1/invoices/fields \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/invoices/fields', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data } = await res.json()
console.log('Fields:', Object.keys(data.fields).length)

JavaScript — OAuth application

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/invoices/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Response fields

The label and description field captions are returned in English, while the ones the platform takes straight from the Bitrix24 account come in the account language. Request headers do not switch the language.

Field	Type	Description
`success`	boolean	Always `true` on success
`data.fields`	object	The invoice field schema: field name → `type`, `readonly`, `label`, `description`. The standard fields are listed below, and the `ufCrm_*` user fields of this Bitrix24 account are added to them
`data.relations`	object	Related entities with the `includable` flag: `contact`, `company`, and `deal`
`data.products`	object	Product-row operations and their field schema. See Product fields
`data.aggregatable`	array	Standard fields allowed in the aggregation `groupBy`: `opportunity`, `stageId`, `assignedById`
`data.batch`	array	Invoice operations available in `POST /v1/batch`: `create`, `update`, `delete`
`data.import`	object	Method, path and maximum batch size for importing records
`data.include`	array	The names the `include` parameter accepts

Standard invoice fields

Field	Type	Read-only	Description
`id`	number	yes	Invoice ID
`title`	string		Invoice title
`stageId`	string		Stage. Format: `DT31_{categoryId}:{stage}`. Stage list: `GET /v1/statuses?filter[entityId]=SMART_INVOICE_STAGE_{categoryId}` — categoryId depends on the Bitrix24 account. To find it: `GET /v1/invoices?limit=1&select=categoryId` or ask your Bitrix24 account administrator
`categoryId`	number		Pipeline ID
`assignedById`	number		Assignee. List: `GET /v1/users`
`contactId`	number		Payer contact ID. Lookup: `GET /v1/contacts`
`companyId`	number		Payer company ID. Lookup: `GET /v1/companies`
`mycompanyId`	number		ID of your own company (the seller) issuing the invoice. Lookup: `GET /v1/companies`
`opportunity`	number		Invoice total amount
`currencyId`	string		Currency. List: `GET /v1/currencies`
`taxValue`	double		Tax amount
`begindate`	datetime		Invoice start date
`closedate`	datetime		Invoice closing date
`accountNumber`	string		Printable invoice number
`comments`	string		Free-text comment
`sourceId`	string		Source. List: `GET /v1/statuses?filter[entityId]=SOURCE`
`sourceDescription`	string		Free-text description of the source
`xmlId`	string		External identifier for integration mapping
`opened`	boolean		Whether the invoice is visible to all employees, not only the assignee
`isManualOpportunity`	boolean		Manual amount mode
`isRecurring`	boolean		Recurring invoice template
`observers`	user		Observers. List: `GET /v1/users`
`contactIds`	crm_contact		Invoice contacts. Lookup: `GET /v1/contacts`
`contacts`	crm_contact		Invoice contacts, expanded
`locationId`	location		Location
`webformId`	crm_webform		The CRM form that created the invoice
`parentId2`	crm_entity		Related deal. Lookup: `GET /v1/deals`
`parentId7`	crm_entity		Related quote. Lookup: `GET /v1/quotes`
`createdBy`	number	yes	Creator ID
`createdTime`	datetime	yes	Creation date
`updatedBy`	number	yes	ID of the employee who last changed the invoice
`updatedTime`	datetime	yes	Modification date
`movedBy`	number	yes	ID of the employee who last changed the stage
`movedTime`	datetime	yes	Date of the last stage change
`previousStageId`	string	yes	The stage before the current one
`lastActivityBy`	user		Author of the last timeline activity
`lastActivityTime`	datetime		Date of the last activity
`lastCommunicationTime`	datetime	yes	Date of the last communication on any channel
`lastCommunicationCallTime`	datetime	yes	Date of the last call
`lastCommunicationEmailTime`	datetime	yes	Date of the last email
`lastCommunicationImolTime`	datetime	yes	Date of the last Open Channel communication
`lastCommunicationWebformTime`	datetime	yes	Date of the last web-form communication

User fields (ufCrm_*) come back alongside the standard ones and are writable. Their set and count depend on the Bitrix24 account, so the table does not list them — read the live response.

Not every field in the table is accepted in filter and order. Eight of them — taxValue, observers, contactIds, contacts, locationId, webformId, lastActivityBy, lastActivityTime — arrive in the response and work in select, but return 400 UNKNOWN_FILTER_FIELD in a filter and 400 UNKNOWN_SORT_FIELD in a sort. The relation fields parentId2 and parentId7 are accepted in a filter but not in a sort. For those two axes, take the names from the error message rather than from the table above — the error lists the ones that are accepted.

Response example

JSON

{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "ID", "description": "Unique numeric identifier of the invoice." },
      "title": { "type": "string", "readonly": false, "label": "Title", "description": "Invoice title." },
      "assignedById": { "type": "number", "readonly": false, "label": "Assignee", "description": "ID of the responsible user. List: GET /v1/users." }
    },
    "relations": {
      "contact": { "type": "one", "entity": "contacts", "includable": true },
      "company": { "type": "one", "entity": "companies", "includable": true },
      "deal": { "type": "one", "entity": "deals", "includable": true }
    },
    "aggregatable": ["opportunity", "stageId", "assignedById"],
    "batch": ["create", "update", "delete"],
    "import": { "method": "POST", "path": "/v1/invoices/import", "maxItems": 100 },
    "include": ["contact", "company", "deal"]
  }
}

Three fields from data.fields are shown, along with the other data keys. The data.products block is omitted from the example, and the full set of fields is in the tables above.

The deal relation reads the deal ID from the invoice's dynamic parentId2 field. The field comes from live metadata for the Bitrix24 account and may be absent from data.fields when the response contains a fields_partial warning.

What to do with the names from data.include is covered on the Get invoice page.

Error response example

403 — the key lacks the required scope: