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

List invoices

GET /v1/invoices

Returns a list of invoices with filtering, sorting and pagination.

Parameters

Parameter Type Default Description
limit number 50 Number of records (up to 5000)
offset number 0 Skip N records
order object — Sorting: ?order[createdTime]=desc
select string — Field selection: ?select=id,title,stageId
filter object — Filtering by GET /v1/invoices/fields fields.
Filter syntax. Example: ?filter[stageId]=DT31_5:N

Examples

curl — personal key

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/invoices?limit=10&sort=-createdTime&filter[stageId]=DT31_5:N" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/invoices?limit=10&sort=-createdTime&filter[stageId]=DT31_5:N" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const params = new URLSearchParams({
  limit: '10',
  sort: '-createdTime',
  'filter[stageId]': 'DT31_5:N',
})

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

const { success, data, meta } = await res.json()
console.log(`Found: ${meta.total}`)

JavaScript — OAuth application

javascript 
const params = new URLSearchParams({
  limit: '10',
  sort: '-createdTime',
  'filter[stageId]': 'DT31_5:N',
})

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

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

Response fields

Field Type Description
data array Array of invoices
meta.total number Total number of records matching the filter
meta.hasMore boolean Whether there are more records beyond limit
data[].id number Invoice ID
data[].title string Title
data[].stageId string Stage
data[].opportunity number Amount
data[].currencyId string Currency
data[].contactId number Contact ID
data[].companyId number Company ID
data[].assignedById number Assignee
data[].createdTime datetime Creation date

The card URL of any invoice from the data array is its id:

https://<portal>.bitrix24.com/crm/type/31/details/<id>/

31 — the entityTypeId of the smart invoice in Bitrix24. <portal> — the Bitrix24 account domain. Access is restricted by the employee's permissions in Bitrix24.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 891,
      "title": "Invoice for services",
      "stageId": "DT31_5:N",
      "categoryId": 5,
      "contactId": 42,
      "companyId": 15,
      "opportunity": 150000,
      "currencyId": "USD",
      "assignedById": 1,
      "createdBy": 1,
      "createdTime": "2026-04-15T14:30:00+00:00",
      "updatedTime": "2026-04-15T14:30:00+00:00"
    }
  ],
  "meta": {
    "total": 47,
    "hasMore": false
  }
}

Error response example

403 — no scope:

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

Errors

HTTP Code Description
403 SCOPE_DENIED API key lacks the crm scope
401 TOKEN_MISSING API key has no configured tokens

Full list of common API errors — Errors.

See also