Invoice fields

GET /v1/invoices/fields

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

Examples

curl — personal key

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

curl — OAuth application

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

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

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.

Standard invoice fields

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. Twelve of them — taxValue, observers, contactIds, locationId, webformId, lastActivityBy, lastActivityTime, utmSource, utmMedium, utmCampaign, utmContent, utmTerm — arrive in the response, but return 400 UNKNOWN_FILTER_FIELD in a filter and 400 UNKNOWN_SORT_FIELD in a sort; the not-returned contacts is refused the same way. The first seven fields are supported in select by every read endpoint; the five utm* arrive only in the full record (no select) and in GET /v1/invoices/{id} — in an explicit select on list or search Bitrix24 ignores their names, and the rows carry no such keys. 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

{
  "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:

{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Errors

For the full list of common API errors, see Errors.

See also

• Create invoice
• List invoices
• Entity API