BEbelvo
Collection Instructions (Brazil)

List collection instructions

Changed on

List the collection instructions of your organization. The response is an array of summaries without the items. To see the items and their statuses, get the instruction's details.

The response is not paginated: it returns every instruction that matches your filters, in no guaranteed order. Use status, consent_id, created_after, and created_before to keep the response small. Belvo ignores any other query parameter.

Errors: A filter value that is not valid (for example, an unknown status or a date that is not YYYY-MM-DD) returns a 500 error.

get/api/collection-instructions/

Request

Query parameters

status'PROCESSING' | 'COMPLETED' | 'CANCELLED'

The status of the collection instruction. Can be one of:

  • PROCESSING: The instruction was created. It stays in this status until you cancel it, even after every item has reached a final status. Check each item's status to see how monitoring ended.
  • COMPLETED: Reserved for future use. Belvo does not currently set this status.
  • CANCELLED: You cancelled the instruction. Any items that were still PENDING or PROCESSING were cancelled too.
Example:PROCESSING

Return only collection instructions with this status.

consent_idstring
Example:0b7c3f2e-9a41-4d8b-8e6f-3c2d1a5b7e90

Return only collection instructions for this data consent. Use the consent_id value from a previous list response.

created_afterstring date
Example:2026-11-01

Return only collection instructions created on or after this date (YYYY-MM-DD), from 00:00 UTC.

created_beforestring date
Example:2026-12-01

Return only collection instructions created before this date (YYYY-MM-DD). The date itself is excluded; the filter stops at 00:00 UTC on this date.

Response

Ok

idstring uuid required

The unique identifier of the collection instruction.

link_idstring uuid required

The link.id whose accounts Belvo monitors for this instruction.

consent_idstring nullable required

The ID of the Open Finance data consent that Belvo found for the Link when you created the instruction. You can use this value in the consent_id filter.

status'PROCESSING' | 'COMPLETED' | 'CANCELLED' required

The status of the collection instruction. Can be one of:

  • PROCESSING: The instruction was created. It stays in this status until you cancel it, even after every item has reached a final status. Check each item's status to see how monitoring ended.
  • COMPLETED: Reserved for future use. Belvo does not currently set this status.
  • CANCELLED: You cancelled the instruction. Any items that were still PENDING or PROCESSING were cancelled too.
created_atstring date-time required

The date and time, in ISO-8601 format (UTC), when Belvo created the instruction.

updated_atstring date-time required

The date and time, in ISO-8601 format (UTC), when the instruction's status last changed.

Example response

[
  {
    "id": "c2a6f1d4-7b3e-4f5a-9c8d-1e2f3a4b5c6d",
    "link_id": "3b979abb-fd60-4d15-a655-8f462ca4ea8f",
    "consent_id": "0b7c3f2e-9a41-4d8b-8e6f-3c2d1a5b7e90",
    "status": "PROCESSING",
    "created_at": "2026-11-04T14:30:12.418230Z",
    "updated_at": "2026-11-04T14:30:12.418230Z"
  }
]

Changes